Skip to content

Styles

Jump to bottom
Nicolas Ronvel edited this page Aug 3, 2016 · 4 revisions

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.

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.

The Style object

Look below how is defined a Style object :

"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
  }
]

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 :

"fields": [
    { "name": "name", "label": "Name :", "default": "Default name", "isNameField": false }
]

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 List of cards.

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 :

The Card / Canvas

The canvas fields are processed through the FabricsJS engine to be then displayed as a card. You can play with this engine in the Kitchensink, and get the associated JSON. Then, copy the objects values into the canvasFields of your template : you 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) :

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 :

"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"
  }
]

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 :

"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"
  }
]

Editable fields and Inheritance

Canvas fields and Inheritance

Feel free to post your questions via Issues if something is unclear or missing in the wiki. Better documentation = Better templates !

Clone this wiki locally