Dropdown List fields are useful when an information on the card is a choice to be selected from a list of options. A _Dropdown List_ is created, with the options set in the template. A default choice is selected, and the user can change it to modify the value on the card.

"fields": [
    {
        "name": "withoptions", "label": "Choose one", "type": "options", "default": "option1",
        "options" : [
            { "option" : "option1", "text": "Option 1" },
            { "option" : "option2", "text": "Option 2" },
            { "option" : "option3", "text": "Option 3" }
        ]
    }
]

To set a field to the Dropdown List type, set the type property to options. You can then add a new property, named options, which is an array. Your options are there.

option is the name of the option, which is used to set the default value, or to be retrieved through a variable inside the canvas. text is the text displayed inside the Dropdown List.

Since the resolution of the Issue #41, Images can be added to an option. For this purpose, add the property image to an option. The value has to be the URL or Data-URL of an image. You can also use a miniature, who works the same way with the property miniature. You can have both an image and a miniature, or only one of them (or none).

{ "name": "characterType", "label": "Type", "type": "options", "default": "leader", "options":
      [
        { "option": "leader", "text": "Leader", "image": "data:image/png;base64,iVBORw......==" },
        { "option": "sidekick", "text": "Sidekick", "miniature": "data:image/png;base64,iVBORw.....==", "image": "data:image/png;base64,iVBORw.....g==" },
        { "option": "ally", "text": "Ally" },
        { "option": "follower", "text": "Follower" },
        { "option": "terror", "text": "Terror" },
        { "option": "gang", "text": "Gang" }
      ]
},

If at least one option has an image or a miniature, the UI field will be different, displaying the miniature of each option on the right side of the text. If an option has no miniature but an image, this image is used instead. If neither a miniature or an image is set to this option, it displays nothing.

The miniature & image are reduced to fit the control automatically.

You can use specific Advanced Variables to access the images of the selected option.

Since the release of the Beta 3, Content can be added to an option. For this purpose, add the property content to an option. The value has to be a portion of canvas code : an path, a textbox, a group of paths, …

{ "name": "icons", "label": "Icons", "type": "options", "default": "none", "options":
  [{
    "option": "none",  "text": "None",
    "content": [{ "type": "path","path": [] }]
   }, {
    "option": "alignment-good", "text": "Alignment - Good",
    "content": [{ "type": "path", "path": "./js/templates/align-good.svg" }]
   }, {
    "option": "alignment-neutral", "text": "Alignment - Neutral",
    "content": [{ "type": "path", "path": "./js/templates/align-neutral.svg" }]
   }, {
    "option": "alignment-evil", "text": "Alignment - Evil",
    "content": [{ "type": "path", "path": "./js/templates/align-evil.svg" }]
   }
},

If you have defined a content property on an option, you can retrieve its content by using the £optionsName variable :

{
  "type": "path-group",
  "id": "icon",
  "left": 9,
  "top": 7,
  "fill": "$color1.hexa$",
  "paths": "£icons"
}

Sometimes, it might be convenient to share options through multiple fields of a template. For example, if the abilities of a character card are always a dice (d4, d6, d8, d10, d12), and each card has 6 different abilities, each ability could look that way :

"fields": [
    {
        "name": "ability1", "label": "Ability 1", "type": "options", "default": "d6",
        "options" : [
            { "option" : "d4", "text": "D4" },
            { "option" : "d6", "text": "D6" },
            { "option" : "d8", "text": "D8" },
            { "option" : "d10", "text": "D10" },
            { "option" : "d12", "text": "D12" }
        ]
    }
]

We'll be repeating those options for each ability. Not very fun. And when we need to include the 'D6+1' option, well, we need to add it for each ability. Even less fun !

Shared Options are the solution. At the root of the template, we'll add a sharedOptions array, in which we'll define our options list. And this list will be shared by different fields :

"sharedOptions": [
    { "key": "diceOptions", "options":
        [
            { "option" : "d4", "text": "D4" },
            { "option" : "d6", "text": "D6" },
            { "option" : "d8", "text": "D8" },
            { "option" : "d10", "text": "D10" },
            { "option" : "d12", "text": "D12" }
        ]
    }
],

And the fields in a Style will be modified like this :

"fields": [
    {
        "name": "ability1", "label": "Ability 1", "type": "options", "default": "d6", "sharedOptions" : "diceOptions"
    },
    {
        "name": "ability2", "label": "Ability 2", "type": "options", "default": "d6", "sharedOptions" : "diceOptions"
    }
]

This is much simpler, easier to update (just change one option), and it will result in lighter template (a little bit).

Maybe you don't want all the options on one particular field ? Well, it's possible. For this instance, the sharedOptions property in the field will be an object with a key and the list of displayed options for this field. It will use a filtered version of the complete list from the sharedOptions :

"fields": [
    {
        "name": "ability1", "label": "Ability 1", "type": "options", "default": "d6", "sharedOptions" : "diceOptions"
    },
    {
        "name": "ability2", "label": "Ability 2", "type": "options", "default": "d6", 
        "sharedOptions" : 
        { 
            "key": "diceOptions", 
            "options": [ "d6", "d8", "d10" ] 
        }
    }

In this example, the “Ability 2” only provides three options : d6, d8 and d10. Those three options are specified in the options array, using the value of the option (option property). The referenced sharedOption is found via the key property.