====== Dropdown List fields ======

**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.

<code javascript>
"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" }
        ]
    }
]
</code>

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**. 

===== Images in options =====

Since the resolution of the [[https://github.com/Gulix/geckos/issues/41|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).

<code javascript>
{ "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" }
      ]
},
</code>

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_String_Variables#dropdown_menu|Advanced Variables]] to access the images of the selected option.

===== Content in options =====

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, ...

<code javascript>
{ "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" }]
   }
},
</code>

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

<code javascript>
{
  "type": "path-group",
  "id": "icon",
  "left": 9,
  "top": 7,
  "fill": "$color1.hexa$",
  "paths": "£icons"
}
</code>
===== Sharing Options =====

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 : 

<code javascript>
"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" }
        ]
    }
]
</code>

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 : 

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

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

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

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

==== Filtering the options ====

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 :

<code javascript>
"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" ] 
        }
    }
</code>

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.