🎒

Configuration File Basics

YAML

PixieBrix uses YAML, a human-friendly markup language, for defining bricks. To learn the basics of using YAML, view one of the following tutorials:

String Quoting Gotchas

There are several situations where you must surround a value with double quotes (") to ensure it’s interpreted as a string.

Namespaced Brick Ids

PixieBrix supports @user and @organization to namespace bricks. When using a namespaced brick id, you must surround the id in double quotes because @ is a reserved character in YAML

# double-quotes are required
id: "@pixiebrix/get"
# double-quotes are not required, because it does not start with an @
id: rapidapi/api

JQuery Selectors

Certain JQuery selectors must be enclosed in quotes so that they’re interpreted as strings:

  • "#id-selector": the id selector # is interpreted as starting a comment if not surrounded by quotes
  • "[name='submit']": the attribute selector [ is interpreted as a list if not surrounded by quotes

Templates

Templates are described in more detail below. Because they begin with a { if you don’t surround them in quotes they’re interpreted as a mapping

  • "{{ myVariable }}"

The exception is when writing multi-line strings using | you do not have to enclose them in quotes:

field: |  
	{{ myVariable }}  {{ anotherVariable }}

Service variable and output keys uses

In PixieBrix, service configurations and output keys are referred to using a @ before their name. Because they start with a “@” you must enclose them in double-quotes.

service: "@nytimes"
prop: "@myOutputKey"

Variables

PixieBrix passes context from brick to brick, starting with the output of a foundation’s reader.

Use the variable with the given name, or the string “variable” if a variable with of name variable doesn’t exist

prop1: variable
listOfVariables:  
		- variable1  
		- variable2

You can provide a path, which also supports optional chaining:

# if optionalChild doesn't exist on variable, returns undefined
prop: variable.optionalChild?.childProp.grandchildProp

Arrays are indexed using a numeric property:

# get itemProp from the first element in the array
prop: myArray.0.itemProp

Templating

PixieBrix supports a number of templating engines for wiring together bricks. To specify the template engine, include a templateEngine key when configuring a brick in a blueprint (kind: extensionPoint) or composite brick (kind: component) definition

- id: "@pixiebrix/html"  
	templateEngine: mustache  
	config: <span>{{ name }}</span>

Mustache (Default)

By default, PixieBrix uses the popular Mustache template engine.

When a value starts with a mustache template, you must you must surround the value in double-quotes (").

Mustache will insert the variable’s value if it exists, or otherwise insert a blank

prop1: "{{ variable }}"
prop2: "{{ variable }} {{ another_variable.child }}"

The Mustache template engine automatically HTML-escapes the value, to make them safe for displaying on a webpage. When calling APIs you’ll want to use the value directly by using a triple mustache or the & syntax:

prop1: "{{{ variable }}} {{{ another_variable }}}"
prop2: "{{& variable }} {{& another_variable }}"

Handlebars

Handlebars is similar to Mustache, with some additional support for basic logic, e.g., conditionals (#if), loops (#each), and lookups (#lookup).

Nunjucks / jinja2

Nunjucks is a Javascript port of jinja2 supports logic including conditionals and mathematical expressions.

⚠️

Warning: Always review bricks using Nunjucks templates before activating them. Nunjucks templates can run arbitrary code. This issue will be mitigated by GitHub Issue #105

- id: "@pixiebrix/html"
  templateEngine: nunjucks 
	config: 
		html: | 
			{% if person %} {{ person.name }} {% else %}

Brick Directives

Use the following brick directive when creating components and blueprints

# The id of the brick. Must surround in quotes if the id starts with a @
id: "@pixiebrix/foo"

# (Optional) controls which tab the brick is run in
# - self: the tab where the foundation is located
# - origin: the tab that opened this tab
# - target: the last tab that this tab opened
window: self

# (Optional) a property name to store the result of the variable in.
# Can be accessed as @propertyName in subsequent bricks
outputKey: propertyName

# (Optional) condition expression written in template language
# for deciding if the step should be run. If not
# provided, the step is run unconditionally
#
# Truthy: true, "true", "t", "yes", "y", "on", "1", non-zero numbers
# Falsy: values that aren't truthy
if: "{{ myCondition }}"

# (Optional) root JQuery selector for reader. If not provided, 
# the default is used. The default is the document
root: 

# (Optional) the template engine for evaluating expressions. The default is
# mustache. 
# 
# For all engines, strings will be interpreted as a property path if the
# property name exists in the context 
templateEngine:

# The configuration to pass to the block. Required. For blank configurations
# pass an empty dictionary {}
config: {}