_ref

Environment: Build Only

(path: string): any
(arguments: {
  path: string,
  vars?: object,
  transformer?: string,
}): any

The _ref operator can be used to reference a configuration file, in order to split the Lowdefy configuration into multiple files. More information on references and the Lowdefy configuration schema can be found here.

The _ref operator is a build time operator: it is evaluated when the app configuration is being built. This means it is not evaluated dynamically as the app is running, and can be used anywhere in the configuration as long as the resulting configuration files are valid YAML.

The _ref operator requires a file path to the file to be referenced, relative to the root directory of the project.

If this file is a YAML or JSON file, and has file extension .yaml, .yml, or .json, the file is parsed as YAML/JSON, and the parsed result is included in the configuration.

If this file is a Nunjucks template file, with file extension .njk, the file is parsed as a Nunjucks template, using any variables provided in the vars argument. If the file extension is .yaml.njk, .yml.njk or .json.njk, the template output is also parsed as YAML/JSON.

If the file is not parsed (for example has an extension like .txt, .md, or .html), the file contents are included in the configuration as a string.

Variables

Variables defined in the vars argument can be accessed in the referenced file using the _var, and as template variables in Nunjucks files.

Transformer

A transformer is a JavaScript function that receives the result of the _ref operator, and its vars. The value returned by this function will be included in the configuration as the final result of the _ref operator. The transformer argument should be the file path (relative to the root of the project) to a JavaScript file that exports a transformer function. For example:

// transformer.js
function transformer(input, vars) {
  // Do something with input
  return result
}
module.exports = transformer;

Evaluating JavaScript

JavaScript can be evaluated during build time by referencing a JavaScript file to the eval argument. The result of _ref operator will be the exported result of the evaluated JavaScript using eval. If the exported result is a function, function.toString() will be returned, useful for loading code for the _js operator. The eval argument should be the file path (relative to the root of the project) to a JavaScript file that exports the a JSON serializable result or function when evaluated.

For example:

// fooHelpers/fooFn.js
function fooFn(value) {
  return { foo: value };
}
module.exports = fooFn(10);

This will evaluate to an object: { foo: 10 }.

And when returning a function will provide the exported function, for example:

// fooHelpers/makePrimes.js
function a() {
  // some other js function
};
function fooFn(value) {
  return { foo: value };
}
module.exports = fooFn;

This will evaluate to the exported function as a string:

"function fooFn(value) {
  return { foo: value };
}"

Arguments

string

The file path to the referenced file, from the root of the project directory.

object

path: string: Required - The file path to the referenced file, from the root of the project directory.
vars: object: An object to be used as variables for the _var operator in the referenced file, and as template variables in Nunjucks template files.
transformer: string: The file path to a JavaScript file, from the root of the project directory, that exports a transformer function.
eval: string: The file path to a JavaScript file which to evaluate, from the root of the project directory.

Examples

Reference pages:

# lowdefy.yaml
lowdefy: '3.17.2'
pages:
  - _ref: pages/page1.yaml
  - _ref: pages/page2.yaml

# pages/page1.yaml
id: page1
type: PageHeaderMenu
blocks:
  # ...

# pages/page2.yaml
id: page2
type: PageHeaderMenu
blocks:
  # ...

Returns:

lowdefy: '3.17.2'
pages:
  - id: page1
    type: PageHeaderMenu
    blocks:
      # ...
  - id: page2
    type: PageHeaderMenu
    blocks:
      # ...

Using a standardized input label template:

blocks:
  - id: name
    type: TextInput
    properties:
      label:
        _ref:
          path: label.yaml
          vars:
            title: Name
            description: Your name and surname.
  - id: age
    type: NumberInput
    properties:
      label:
        _ref:
          path: label.yaml
          vars:
            title: Age
            description: Your age.

# label.yaml
title:
  _var: title
extra:
  _var: description
span: 8
colon: false
extraStyle:
  color: '#546358'