Customize Card Templates - techtalk/SpecLog-Resources GitHub Wiki

WARNING Problems can occur if you update both the card template in SpecLog and your work item settings in TFS at the same time. Make your changes in SpecLog first, and let the changes in SpecLog synchronise with TFS before making any changes to TFS. Do not modify items in TFS that are not yet up-to-date.

You can customize card templates in order to change the appearance of requirements placed on a workspace. To edit the card templates:

1. Either select Edit Card Templates from the New Requirement widget's menu or select Repository settings from the main menu and click on the Edit button next to Card templates. The Edit card templates dialogue is displayed:
   
2. Edit the card templates using either the graphical interface (Visual editor tab) or as XML (XML editor tab):
   • Name: The name of the requirement. This name is displayed in the New Requirement widget and must be unique.
   • Obsolete: This option allows you to remove a requirement type from the New Requirement widget while retaining all existing requirements of that type.
   • Description: Description of the requirement.
   • Color Scheme: Select the card's colour scheme from the drop-down list.
   • ID Prefix: The ID prefix displayed in cards. This ID must be unique, i.e. two card types cannot have the same ID prefix, and can only contain letters.
   • Header: Determines which field's contents is displayed in the card's header. For example, if you select "Goal", the contents of the goal field are displayed in the card's header after the card's ID.
   • Fields: This section determines which fields are available in the card and the field prefixes (can be blank).
     • Goal/Title/Actor/Value: Enable the check box next to a field to include the field in the requirement card. Click on the grey bar to the left of the field and drag it to the desired position to change the order in which fields are displayed on the card.
     • Prefix: Enter a prefix that is displayed at the start of the field here, e.g. "As a" for the Actor field.
   • Refinement: Determines the child requirement type, i.e. the requirement type that the current requirement is the parent of. When adding a new refinement (either in the requirement details or when pressing Ctrl+N on a workspace) to a requirement, the requirement type entered here is added and linked to the current requirement.
   • Sync Agents: Determines which plugins are used to synchronise the requirement with your work item tracking system.
3. Click on Save to save your changes.

Note: The XML elements used by the XML editor are listed below. Changes made on one tab are automatically updated on the other tab.

To delete a card template:

1. Switch to the Visual editor tab.
2. Click on the red X above the requirement card preview.
   The requirement type is deleted.
3. If you have removed a card template that is used by existing requirements in your repository, these requirements are change to the first requirement type in the list.

To add a card template:

1. Switch to the Visual editor tab.
2. Scroll to the bottom of the list of card types.
3. Click on + ADD CARD TEMPLATE. A new card template is added. Customise the new card template as required.

The order in which requirements are defined determines the order they are displayed in the New requirements widget. The first requirement type is treated as the default requirement; the default requirement type is automatically assigned to requirements where the type is otherwise unclear (e.g. when deleting a requirement type, all existing requirements of the type are set to the default requirement type).

To change the order of the requirements:

1. Switch to the Visual editor tab.
2. Click on the grey bar to the left of the requirement type you want to move and keep the mouse button pressed.
3. Drag the card up or down to change the card's position in the list and release the mouse button.

Card templates are stored as an XML file. You can edit the XML directly instead of using the visual card editor on the XML editor tab.

Note: You can use the XML code to transfer requirement card templates between repositories. To do so, copy the XML content to the clipboard (Ctrl+C), open the target repository's card templates, paste (Ctrl+V) the contents of the clipboard to the XML editor tab, and save your changes. You can also do this for individual card templates by copying the card's entire <CardTemplate> element.

Requirement types are defined within the <CardTemplate> element. This element can contain the following attributes:

• ID: Unique card type ID
• Name: Unique name of the requirement type
• DisplayIdPrefix: The card's ID prefix
• Obsolete: Set to 'true' to mark the requirement type as obsolete
• HeaderField: The field displayed in the card's header
• ColorScheme: The card's colour scheme. Possible options: Aqua (cyan), Azure (blue), Lavender (light violet), Coral (light red), Gold (bright gold), Sunshine (bright yellow), Spring (green)
• RefinementType: The child refinement type for this requirement type.

Example:

    <Templates>
        <CardTemplate ID="UserStory" Obsolete="false" Name="User Story" 
        DisplayIdPrefix="US" HeaderField="Goal" ColorScheme="Azure" 
        RefinementType="UserStory">
            ...
        </CardTemplate>
    </Templates>

The <Fields> element specifies which fields are displayed on the card. The following attributes are available:

• Name: The field name (Title, Actor, Goal or Value)
• Prefix: The prefix displayed on the card before the field (can be empty)

Example:

    <CardTemplate ...>
        <Fields>
            <Field Name="Actor" Prefix="As a" />
            <Field Name="Goal" Prefix="I want to" />
            <Field Name="Value" Prefix="So that" />
        </Fields>
        ...
    </CardTemplate>

Note: When using V3 of the synchronisation plugin, card mappings are defined in the plugin's configuration instead.

When using V1 or V2 of the synchronisation plugins, you need to determine which card types should be synchronised with your work item tracking system. To determine that a card type should be synchronised, enable the corresponding check box (SpecLog.JiraPlugin or Techtalk.TFSSync) in the card template. You can also customise the XML directly; in this case your card templates require the <SynchronisedTo> element. Use the <SynchTarget> element to determine which work item synchronization provider should be used to synchronise requirements of this type. The following synchronization targets are supported by default:

• TechTalk.TFSSync
• SpecLog.JiraPlugin

Example:

    <CardTemplate ...>
      ...
        <SynchronisedTo>
            <SynchTarget>TechTalk.TFSSync</SynchTarget>
        </SynchronisedTo>
    </CardTemplate>

More information on synchronisation providers and their configuration can be found here.