Skip to main content

DSL per Template Page Element

I template per i page element in Hydra sono definiti in un domain-specific language (DSL) custom. I template definiscono quali campi (di contenuto e configurazione) saranno esposti dal page element e per ciascuno quale tipo di dato .

I template sono caricati da file tramite un Template Repository.

Basi​

Ogni template segue questa struttura:

template {{name}} in group {{groupname}} with importance {{importance}}

config: {
    {{field1}}: {{typedefinition}},
    {{field1}}: {{typedefinition}},
    ...
}

content: {{contentdefinition}}

Dove config è di tipo oggetto e content può essere qualunque definizione di tipo

Tipi di nodo​

Le proprietà possono essere configurate per avere un tipo tra i seguenti:

Object​

Dichiarare un campo come oggetto significa che il content element accetterà oggetti JSON (adeguatamente formati) come valore per la proprietà. Gli oggetti sono definiti come segue:

{
    foo: string,
    bar: {          //Gli oggetti possono essere innestati
        xyz: int
    }
}

come lista di coppie chiave: tipo senza virgolette attorno alla chiave, separate da virgola, tra parentesi graffe.

La definizione qui sopra accetterà dati come:

{
    "foo": "lorem ipsum",
    "bar": {
        "xyz": 5
    }
}

Se il campo non è presente, verranno utilizzati i valori di default.

Array​

Definizione di un array di oggetti di tipo stringa:

{
    foo: array of (string);
}

Tra le parentesi può risiedere qualunque tipo di dato, anche oggetti o altri array. Questa definizione accetterà elementi compatibili con il tipo dichiarato (stringa in questo caso). Se un elemento non è compatibile, non comparirà tra gli elementi dell'array dopo il (un)packing.

es.:

{
    foo: ["abc", "", "XYZ", 5, {}]
}

Dopo essere packed tramite lo schema qui sopra diventerà:

{
    foo: ["abc", "", "XYZ"]
}

OneOf​

Questo costrutto è utile quando si vogliono specificare tipi di dato alternativi (ADT).

{
    foo: (string | int | "foobar"), //Notazione breve
    bar: one of (string, int, "foobar")      //Notazione completa
}

Se il valore passato a 'oneOf' è compatibile con uno dei tipi dichiarati, il valore verrà risolto attraverso il primo tipo di dato compatibile trovato. Se non ci sono tipi compatibili, verrà restituito il valore di default del primo tipo dichiarato, se nessun default è configurato.

Dato questo input:

{
    "foo": 5,
    "bar": []
}

Un packing darebbe origine a:

{
    "foo": 5,
    "bar": "" //default value of the first type (string)
}

Responsive​

A volte è necessario poter inserire valori diversi in un campo in base alla dimensione del viewport.

Definizione:

{
    foo: responsive(string) with default {
        xs: "abc",
        sm: "def",
        md: "xyz",
        lg: "xyz",
        xl: "def",
        xxl: "xyz",
    }
}

Il valore di default è opzionale e può essere specificato direttamente per il tipo interno (string in questo caso). Responsive accetta un oggetto JSON avente come chiavi le dimensioni schermo nell'esempio, oppure un valore compatibile con il tipo interno (verrà assegnato a tutte le dimensioni). Il valore (un)packed manterrà la stessa forma.

Tipi Primitivi​

These types are the tree leaves, not containers like the previous ones.

Bool - bool, boolean​

Binary boolean value (true/false).

Options​
  • allowsTrue: If set to false, the prop will not accept the input value "true".
  • allowsFalse: If set to false, the prop will not accept the input value "false".

Color - color, colour​

A color, in RGB hex format (#rgb, #rgba, #rrggbb, #rrggbbaa). Also accepts primary, secondary, accent, with reference to the colors defined in the site props.

Code - code​

Represents a piece of code, similar to string, useful for letting the front-end know what kind of code we're dealing with.

Options​
  • language: The coding language used, CSS by default.

Decimal - decimal, float, double​

Floating point number

Options​
  • min: Minimum value.
  • max: Maximum value

File - file​

A refrence to one of the files associated with the current page. This data type accepts a full file definition (from which will extract the ID), or the string identifier of a file. On page retrieval, the full file definition will be shown as value.

Fixed​

A fixed, constant string value. Rarely used by itself, it's usually employed as an option in the oneOf data type.

To define a fixed type

Options​
  • value: The constant value

FixedPropertyReference​

Accepts as parameter the name of a site property. The resolved value of this data type will be the property of the current site having the specified name, or null if the property is not specified for the site.

Options:​
  • property: The property to retrieve.
{
  "type": "fixedPropertyReference",
  "property": "primaryColor"
}

Form​

A refrence to one of the form templates defined within the site. This data type accepts the ID of the form template (as string). On page retrieval, the full form template definition will be shown as value.

Html​

Represents a piece of HTML code, similar to string, but does not offer extra options.

Image​

Represents an image, in the following format:

{
    "id": "...",
    "url": "https://....",
    "alt": "Image description", //Optional
    "width": 123,
    "height": 456,
    "size": 16384,  //Bytes
    "blurPreviewBase64": "data:..." //Data URL, small blurred preview
}

During insertion, it's possible to specify a data url in the "url" field: the image will be uploaded to the configured image repository, and the data url will be replaced with a regular link pointing to the new remote file.

Integer (or Int)​

Integer number

Options​
  • min: Minimum value.
  • max: Maximum value.
  • step: Difference between an allowed value and the next: If min is set to 1, and step is set to 2, only odd numbers will be allowed.

A reference to one of the logos specified in the site configuration. Please refer to the Logo documentation for further info about its json format. The value of this data type is a string, the logo's ID.

PageReference​

Accepts as input an object in this form:

{
  "id": "66d18ee4-43ea-4248-8b93-ad7538a09ce8",
  "culture": "fr"
}

Upon resolution, this type will return, if found, details about the localization specified by culture of the page specified by id. Fields returned by the resolved field include:

page, culture, url, fullUrl, title, inboundTitle, inboundToolTip, cta, tooltip, ancestors, image, description.

PropertyReference​

Upon resolution, this data type returns the value of the site-property passed as value.

{
  "type": "propertyReference"
}

Example:

//input data (string)
"primaryColor"

//resolved data
"#45FE12"

If the site has no such property, null is returned.

String​

Represents a plaintext string:

Options​
  • regex: allows to restrict the accepted data based on a regular expression: If the input does not satify the regex, the default value will be applied (or null, if nullable).

Macros​

Macros can be used to define new data types by combining existing ones, the macro can be later used in templates as a type definition.

Example:

macro video as {
    src: string,
    width: int(min=1),
    height: int(min=1)
}

This macro can then be used as a normal data type:

template foo in group bar with importance 5 {
    config: {
        ...
    }

    content: array of (video)
}

Macros are defined in *.hym files, located in the macro directory of the Resources project.

Additional attributes​

A type definition can be decorated with a number of attributes:

Nullable​

By prepending nullable, the type definition will accept null as a valid value, and use it as a default.

{
    foo: string,            //Does not accept null, default: ""
    bar: nullable string    //Does accept null, default: null
}
note

The default value of a nullable field is null, but that might be subject to change in the future.

Default Value​

To set a custom value for a type definition, the with default {{value}} directive can be used:

{
    foo: string with default "Lorem Ipsum",
    bar: { abc: int } with default { abc: 0 }
}

Depends On​

It's possible to specify when a property depends on another property being not null or having a specific value:

{
    foo: nullable string,

    //Depends on foo not being null
    bar: int depends on foo,

    //Depends on foo having a specific value
    xyz: int depends on foo being "Lorem Ipsum" or "Iprem Losum"
}

This has no effect on the behaviour of the backend, but it's used by the frontend to determine which fields to show or hide in the editor.