_ref

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.

Resolver

A resolver is a JavaScript function that overwrites the default way configuration files are read from the filesystem. It does not need to read from the filesystem, it could generate a value to return programmatically, or it could fetch the configuration using HTTP (from Github for example). The resolver argument should be the file path (relative to the root of the project) to a JavaScript file that exports a resolver function.

The resolver function receives the path, vars, and a context object as arguments. If a resolver function is specified, the path argument to the _ref operator is optional, and does not need to correspond to a path to a file. If path ends with .yaml, .yml, .json, .njk, .yaml.njk, .yml.njk, or .json.njk, the returned result will be parsed as YAML/JSON/Nunjucks template.

A default _ref resolver can be specified in the lowdefy.yaml cli section (as refResolver), or as a command-line option when running the CLI (as --ref-resolver). This resolver will then be used for all references in the app, unless another resolver is specified.

Transformer

A transformer is a JavaScript function that receives the result of the _ref operator, and its vars as arguments. 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.

Arguments

string

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

object

• path: string: The file path to the referenced file, from the root of the project directory. If no resolver is specified, path is required.
• resolver: string: The file path to a JavaScript file, from the root of the project directory, that exports a resolver function.
• transformer: string: The file path to a JavaScript file, from the root of the project directory, that exports a transformer function.
• 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.

Examples

Reference pages:

# lowdefy.yaml
lowdefy: '3.23.3'
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.23.3'
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'

Returns:

blocks:
  - id: name
    type: TextInput
    properties:
      label:
        title: Name
        extra: Your name and surname.
        span: 8
        colon: false
        extraStyle:
          color: '#546358'
  - id: age
    type: NumberInput
    properties:
      label:
        title: Age
        extra: Your age.
        span: 8
        colon: false
        extraStyle:
          color: '#546358'

Local or shared resolver:

This resolver function will first look for the configuration file in the current working directory, but if the file is not found it will be read from an adjacent "shared" directory. This pattern can be used to build apps that mostly use a shared configuration, with a few components that are customised per app.

// resolvers/useLocalOrSharedConfig.js
const fs = require('fs')
const path = require('path')
const { promisify } = require('util');

const readFilePromise = promisify(fs.readFile);

async function useLocalOrSharedConfig(refPath, vars, context) {
  let fileContent
  try {
    fileContent =  await readFilePromise(path.resolve(refPath), 'utf8');
    return fileContent;
  } catch (error) {
    if (error.code === 'ENOENT') {
      fileContent = readFilePromise(path.resolve('../shared', refPath), 'utf8');
      return fileContent;
    }
    throw error;
  }


}

module.exports = useLocalOrSharedConfig;

// lowdefy.yaml
lowdefy: 3.23.3

cli:
  refResolver: resolvers/useLocalOrSharedConfig.js

pages:
  - _ref: pages/local-page.yaml
  - _ref: pages/shared-page.yaml

This transformer adds a standard footer to each page:

//  transformers/addFooter.js

function addFooter(page, vars) {
  const footer = {
    // ...
  };
  page.areas.footer = footer;
  return page;
}
module.exports = addFooter;

// lowdefy.yaml
lowdefy: 3.23.3

pages:
  - _ref:
      path: pages/page1.yaml
      transformer: transformers/addFooter.js