Geckos Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Styles ======

The ''styles'' part of a template is its main part. It defines how the cards are being built.

You can have a single **Style** in your template, or numerous ones. When using a template with multiple styles, you have to choose which one to apply to all the cards in your set. 

<WRAP center round info 60%>
Some older templates could have the **Styles** elements directly at the root of the templates, not using the **styles** array. It's still valid, but it's better to use the **styles** array, even with a single style.
</WRAP>

===== The Style object =====

Look below how is defined a **Style** object : 

<code javascript>
"styles" : [
  {
    "canvasBackground": "#CCCCCC",
    "canvasWidth": 700,
    "canvasHeight": 495,
    "key": "style101",
    "name": "My First Style",
    "description": "It's my first style, so just a simple one !",
    "fields": [ ],
    "canvasFields": [ ]
  },
  {
    -- Another style object
  }
]
</code>

==== General Informations ====

Those fields are required and described some basic elements of the style : 

  * ''canvasBackground'' : defines the background color of the card. Use an hexadecimal color.
  * ''canvasWidth'' : in pixels, the width of the card
  * ''canvasHeight'' : in pixels, the height of the card 
  * ''key'' : a unique string to identify the style. No other style in the template should have the same key.
  * ''name'' : a string to identify the style. Will be used in the dropdown menu to select the style.
  * ''description'' : description of the style, displayed when the style is selected.

==== Editable Fields ====

The editable fields will appear on the left side of the UI. Those are the files the user will be filling to update the card's data. You can add as many fields as you want in your template. The order in which they are defined in the file will be the one they are displayed. Several types of fields exist, but each have common values :

<code javascript>
"fields": [
    { "name": "name", "label": "Name :", "default": "Default name", "isNameField": false }
]
</code>

This describes a simple text input field. The properties shown are common for all the types of fields.

  * ''name'' : the unique name of the field, to identify it and use its value inside the card (better with no space or special characters)
  * ''label'' : text that will be used next to the editable field to describe it
  * ''default'' : default value that will fill the field when a new card is created
  * ''isNameField'' : is this field the one that describe the card ? If ''true'', the value of this field will be used to identify the card in the list. See the [[..:manual:list-of-cards|List of cards]].
  * ''group'' (optional) : specifies the name of the [[Group of Fields|Group]] the field is part of. The Group must exist, and a Group cannot be in a Group.

Each type of fields then have different properties that define how it is displayed, what data can be obtained with it, and so on. Here's the list of available editable fields :

  * [[Group of Fields]]
  * [[Text input]]
  * [[Choice input]]
  * [[Checkbox]]
  * [[Image input]]
  * [[Multiline text input]]
  * [[Rich Text Field]]
  * [[Numeric Input Field]]
  * [[Color Picker]]

=== Order of the Editable fields ===

The editable fields are //displayed// one after the other, the first item of the array being the one first displayed. You can change this by setting an ''order'' property on a field, and defining the order of the element (an integer). The editable fields are sorted in ascending order. 

Note that the ''order'' property is set by default to a value of ''1''.

==== The Card / Canvas ====

The canvas fields are processed through the [[http://fabricjs.com/|FabricsJS]] engine to be then displayed as a card. You can play with this engine in the [[http://fabricjs.com/kitchensink|Kitchensink]], and get the associated JSON. Then, copy the ''objects'' values into the ''canvasFields'' of your template : you'll get your card !

Each //editable field// of the card generates a variable, that can be used inside the canvas data. Here's the different types of variables (see each type of field to know the variables associated) :

  * [[Text Variables]]
  * [[Boolean Variables]]
  * [[Dataurl Variables]]
  * [[Advanced String Variables]]
  * [[Code Variables]]

=== Order of the Canvas elements (Z-Index) ===

The elements of the canvas are //drawn// one after the other, the first item of the array being the one first drawn. Sometimes, elements can be mixed together and will not appear in the desired order. If you need some elements to be on the background, other on the foreground (like different layers), you can change this by setting a ''zindex'' property on a field, and defining the order of the element (an integer). The elements of the canvas are sorted in ascending order (Z-Index of 1 is displayed underneath Z-Index of 2, and so on).

Note that the ''zindex'' property is set by default to a value of ''1''.
===== Inheriting styles =====

Sometimes, a Style is just a slight derivation from another one. For example, you could have an english style, and a french one, with just labels being modified. It would be a shame to repeat large amount of code to describe those two styles. Here comes the **Inheritance**.

You first need to define a classic style, which we'll call the /Parent/. Then create another style by `copying / pasting` the first one. Finally, for this first steps, modify the general informations : 

<code javascript>
"styles" : [
  {
    "canvasBackground": "#CCCCCC",
    "canvasWidth": 700,
    "canvasHeight": 495,
    "key": "parentStyle",
    "name": "Parent Style",
    "description": "It's the Parent Style !",
    "fields": [ ],
    "canvasFields": [ ]
  },
  {
    "canvasBackground": "#CCCCCC",
    "canvasWidth": 700,
    "canvasHeight": 495,
    "key": "childStyle",
    "name": "Child Style",
    "description": "It's the Child Style !",
    "fields": [ ],
    "canvasFields": [ ], 
    "basedOn": "parentStyle"
  }
]
</code>

You could see that a ''basedOn'' property has been added. That's the key of the inheritance ! Enter the key of the Parent Style in this property, and the inheritance is set. Now, you only need to describe in your template what is changing. If the ''canvasXXX'' properties stay the same, well, remove them from the child : 

<code javascript>
"styles" : [
  {
    "canvasBackground": "#CCCCCC",
    "canvasWidth": 700,
    "canvasHeight": 495,
    "key": "parentStyle",
    "name": "Parent Style",
    "description": "It's the Parent Style !",
    "fields": [ ],
    "canvasFields": [ ]
  },
  {
    "key": "childStyle",
    "name": "Child Style",
    "description": "It's the Child Style !",
    "fields": [ ],
    "canvasFields": [ ], 
    "basedOn": "parentStyle"
  }
]
</code>

==== Editable fields and Inheritance ====

If the editable fields of your child style are exactly the same as the parent's ones, then, don't even declare the ''fields'' array.

If there is a modification, here's how to procede for each field : 

  * The field remains exactly the same (''field01'' in example code)
    * Don't put that field in the child fields
  * Some properties of the field are modified (''field02'' in example code)
    * Add a new field with the same ''name'', and then only write the modified properties.
  * This field was not on the parent style (''field03'' in example code)
    * Add it to the fields

Parent's fields : 

<code javascript>
"fields": [
    { "name": "field01", "label": "Name :", "default": "Default name", "isNameField": true },
    { "name": "field02", "label": "Class :", "default": "Default class", "isNameField": false }
]
</code>

Child's fields : 

<code javascript>
"fields": [
    { "name": "field02", "label": "Current Class :" }
    { "name": "field03", "label": "Level :", "default": "Default level" }
]
</code>

Any property of a field can be modified in a child field : ''sharedOptions'', ''options'', ''default'', ... Feel free to have a look at existing templates to discover how inheritance works.

==== Canvas fields and Inheritance ====

If the canvas fields of your child style are exactly the same as the parent's ones, then, don't even declare the ''canvasFields'' array.

If there is a modification, here's how to procede for each canvasField : 

  * The canvasField remains exactly the same ?
    * Don't put that canvasField in the child canvasFields
  * Some properties of the field are modified ?
    * Add an ''id'' property to the parent canvasField, with a unique string describing it.
    * Add a new field with the same ''id'' property in the child canvasField, and then only write the modified properties.
  * This canvasField was not on the parent style ?
    * Add it to the ''canvasFields''

Parent's canvasFields : 

<code javascript>
    "fields": [
    { "type": "textbox", "text": "$name", "left": 91, "top": 11, "width": 351, "textAlign": "center", "fill": "#FFD800", "fontFamily": "Arial", "fontWeight": 700, "fontSize": 38 },
    { "id": "class", "type": "textbox", "text": "$class", "left": 91, "top": 60, "width": 351, "textAlign": "center", "fill": "#FFD800", "fontFamily": "Arial", "fontWeight": 700, "fontSize": 38 }
]
</code>

Child's fields : 

<code javascript>
"fields": [
    { "id": "class", "text": "$class$ - Lvl.$level$" },
    { "type": "textbox", "text": "Current class", "left": 91, "top": 90, "width": 351, "textAlign": "center", "fill": "#FFD800", "fontFamily": "Arial", "fontSize": 14 }
]
</code>

Any property of a canvasField can be modified in a child canvasField : ''text'', ''left'', ''top'', ''fontFamily'', ... Feel free to have a look at existing templates to discover how inheritance works.

==== Ignoring a Parent field ====

Following the completion of [[http://www.github.com/gulix/geckos/issues/102|Issue #102]], you can use the property ''ignored'' in a field (//editable// or //canvas// field) and set it to ''true'' in order to ignore it in the generated style (it will not be inserted in the arrays).

This property follows all the rules of inheritance. If a parent style set it to ''true'', a child could still reset it to ''false''.
Geckos Documentation

User Tools

Site Tools

Page Tools
