Guides

YAML

Hub client YAML configuration

Suggest Edits

YAML

The YAML used in Target Builder is a standard YAML that has been extended with some specific YAML tags.

For initial acquaintance with the YAML read this article: Learn X in Y minutes (Where X=yaml)

Reserved fields

In the YAML files, there are three "reserved" fields in the root:

~private

  • It can be used to store data, which will be omited in build time, and will not be in target configuration. This field is processed by target-builder.
Example
~private:
  yourSecretKey: "secret value"

List of supported tags

Compile-time tags

Run-time tags

Deprecated tags

!include compile-time tag

  • This tag is used to import/include any type of file into this place of YAML.
  • This tag supports properties, which correspond to the parameters of this file.
  • This tag internally opens any file as string, then processes by EJS (https://ejs.co), and then it passes the contents as a string (for other types) — or processes it by compiler if it is a supported file type (YAML, MD, HTML, LESS).
  • You can use EJS for any kind of modifing file that depends on properties, such as—for example-generating some repeating parts of a document or setting values for some of the properties.
  • The tag is always processed immediately when is used, except when it is used in the components field in root of YAML file (see !ref).
  • The tag is used for including any type of file—not only for YAML but also for LESS, CSS, MD, HTML, etc.
  • When you attempt to include a directory, the Target builder will look in this directory for the index.yaml or index.yml file. It will include this file if it is found. Keep in mind that you can include components like !include ./components/button instead of !include ./components/button/index.yml).
Syntax

Short version (without properties):

!include ./path/file.ext

Long version (with properties):

!include file: ./path/file.ext
property1: 'some'
property2: 123
Examples
list:
  - !include ./info.md
  - !include file: ./more_info.yml
    title: 'Hello'
    withoutHeader: true

something: !include ./something.yml

!ref compile-time tag

  • This tag is used to reference some component into this place
  • The source for the components is the components field in the root of YAML file.
  • This tag can have properties that the same as the !include tag
  • The !ref tag properties have higher priority than !include properties in components field
  • You can make multiple references to a component, with different properties for each reference.
Syntax
!ref components: component_name
Examples
components:
  header: !include file: ./components/header.yml
    title: "Default title"
  bodyItem: !include ./components/body-item.yml
  footer: !include ./components/footer.yml

...

items:
  - !ref components: header
    title: 'Welcome'
  - !ref components: bodyItem
    name: 'First one'
  - !ref components: bodyItem
    name: 'Second one'
  - !ref components: footer

!property compile-time tag

  • This tag is useful as a placeholder for the value of a propertys (in an !include of a YAML file.
  • While it is possible to use EJS for this, EJS only works with a string. It's not possible to pass some array or object using EJS, and this is the purpose of the !property tag.
    -This tag can have default value (only in the long version), which can contain any valid YAML value—including a string, number, array, or complex object.
  • This tag can have required: true mark (only in long version), which will throw an error message while build target, when value is not filled (default value don't have any impact if required: true is set).
  • If the property is not set, this tag is set to undefined, and field will not appear in the output JSON.
Syntax

Short version (without default):

!property some_prop

Long version (with default or required):

!property name: some_prop
default: 'Some default value'
required: true
Examples
items:
  - !property prop1
  - !property name: prop2
    default: 'Prop2 is not here :-)'
  - !property name: prop3
    required: true

!condition compile-time tag

  • This tag is for removing or including some parts of YAML structure (in an !include of a YAML file).
  • The first parameter (key) can be either include or omit. include leaves the bject in the structure if the expression is a genuine value. omit removes the object from the structure if the expression is a genuine truly value.
  • The second parameter (expression) is the expression in EJS format.
  • This tag is valid only for object types and include/omit object in which is contained. (It is not permissible to apply this tag to a string or number value; use EJS isntead.)
Syntax
!condition include: typeof some_prop === "boolean" && some_prop === true

!condition omit: typeof some_prop === "string" && some_prop !== "foo"
Examples
items:
  - name: 'this item is not here :-('
    !condition include: typeof some_falsy_prop === "boolean" && some_falsy_prop === true
  - name: 'this item is here :-)'
    !condition omit: typeof some_falsy_prop === "boolean" && some_falsy_prop === true

!component run time tag

  • This tag creates a component in hub-client-core. During execution, it is converted into a real React component in the HTML DOM.
  • Every element is created by React.createElement, and property items will be used as children.
  • The parameter is name of hub-client-core component, or any React Element such as div, span, h1, etc.
Syntax
!component as: some_component
property: 'foo'
Examples
items:
  - !component as: div
    items:
      - !component as: h1
        items: 'Hello'
      - !component as: HubClientMagicComponent
        doMagic: true

!repeat run time tag

  • This tag creates a repeat snippet in the hub-client-core. At execution, this is evaluated in React.
  • The parameter is any array (static or from !expression). For more information about the repeat snippet, see the hub-client-core documentation.
Syntax
!repeat some_item:
  - name: 'Some 1'
  - name: 'Some 2'
  - name: 'Some 3'
component:
  !component as: span
  items: !expression some_item.name
Examples
items:
  - !repeat car: !expression export.cars
    component:
      !component as: span
      items: !expression car.name
  - !repeat pair:
      - name: 'Some 1'
        value: 'Val 1'
      - name: 'Some 2'
        value: 'Val 2'
      - name: 'Some 3'
        value: 'Val 3'
    component:
      !component as: div
      items:
        - !component as: span
          items: !expression pair.name
        - !component as: span
          items: "!expression '(' + pair.value + ')'"

The !repeat expression provides a way to iterate on some collections and map components to it. You simply specify an array as the input collection (you can use an expression as well). Also specify a component that will be rendered n times (n is length of array).

Inside the component, you can access an item by expression that is stored in the key. In the expression, you can directly access an item of the array ([key].item) or its index ([key].index).

This is the format:

!repeat [key]: [array]
component: [some component]

Examples:

Here's an array from the api:

!repeat person: !expression flow.export.persons
component:
  !component as: span
  items: !expression person.item.name

Here's an array in yaml:

!repeat item:
  - Item 1
  - Item 2
component:
  !component as: span
  items: !expression item.item

!expression run time tag

  • this tag creates an expression in hub-client-core. At execution, this is evaluated in React.
  • The parameter is an expression. For more information about expressions, see the hub-client-core documentation.
Syntax

Short version (without parameters):

!expression 'some_expression'

Long version (with parameters):

!expression eval: 'some_expression'
parameter_one: 'Some parameter value'

Multiline:

property:
  !expression: |
    const variable = 1;
    // More lines of JavaScript
    console.log('Hello', variable);
Examples
items:
  - !component as: span
    items:
      - !expression 'exports.someExportField'
  - !component as: span
    max:
      !expression eval: 'parseInt(param1) - param2'
      param1: !expression 'exports.someExportField'
      param2: !property test1

!function run time tag

  • This tag creates a JS function in hub-client-core. At execution time, it evaluated in React and may be used as a paramater in the events of components.
  • The parameter is a function body. For more info about expressions, see the hub-client-core documentation.
Syntax

Short version (without parameters):

!function 'some_expression'

Long version (with parameters):

!function eval: 'some_expression'
parameter_one: 'Some parameter value'
Examples
items:
  - !component as: div
    onClick: !function 'setSomething(arg1 + "A")'
  - !component as: div
    onClick:
      !function eval: 'doSomething(parseInt(param1) - param2)'
      param1: !expression 'exports.someExportField'
      param2: !property test1
  - !component as: div
    onClick: !function |
      var a = "A";
      var b = "B";
      return a + b + " = done";

!t run time tag

  • This tag creates a translated string in hub-client-core. At execution time, it evaluated in React.
  • The long version of this tag provides parameters. The first parameter is replaced with the second parameter.
Syntax

Short version (without params):

!t Some text

Long version (with params):

!t text: Some text with {paramOne} and {paramTwo}
paramOne: 'Zenoo'
paramTwo: !expression 'exports.someExportField'
Examples
items:
  - !component as: span
    items:
      - !expression 'exports.someExportField'

!cx run time tag

  • This tag is shorcut for a cx(...) method call in hub-client-core expressions.
  • The parameter must be array of classnames (after args).
Syntax
!cx args:
  - 'classOne'
  - 'classTwo'
  - !expression 'exports.someClassName'
Examples
items:
  - !component as: span
    className:
      !cx args:
        - 'classOne'
        - 'classTwo'
        - !expression 'exports.someClassName'

Updated 4 months ago