- YAML
- Dictionaries/Records
- Lists/Arrays
- String Quoting Gotchas
- Namespaced Brick Ids
- JQuery Selectors
- Templates
- Service variable and output keys uses
- Runtime API Version
- Variables
- Templating
- Mustache (Default)
- Nunjucks / jinja2
- Brick Directives
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:
Dictionaries/Records
exampleProperty:
hello: 42
world: "this is a string!"
Lists/Arrays
To create a list, use -
below the parent entry:
exampleProperty:
- hello
- world
You can also create a list of dictionaries. Note the indentation!
exampleProperty:
- propA: hello
propB: world
- propA: hello
propB: world
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"
Runtime API Version
The apiVersion
directive controls how PixieBrix's runtime interprets the brick.
Whenever backward incompatible changes are introduced, we increment the apiVersion. If you do not specify the apiVersion, it defaults to v1
apiVersion: "v2"
v1
: our initial releasev2
: made data flow between bricks explicit. Bricks had to reference data from previous bricks using the@outputKey
for that brickv3
(supported in the runtime, but not yet supported in the Page Editor). Uses explicit tags for!var
,!mustache
, and!nunjucks
Variables
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 mod (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 }}"
Nunjucks / jinja2
Nunjucks is a Javascript port of jinja2 supports logic including conditionals and mathematical expressions.
- id: "@pixiebrix/html"
templateEngine: nunjucks
config:
html: |
{% if person %} {{ person.name }} {% else %}
Brick Directives
Use the following brick directive when creating components and mods
# 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
# - broadcast: runs the brick in all the available tabs, returning the result as
# an array
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)
# - inherit (default): inherit the root from the foundation. For triggers/context
# menus, this is the eventTarget
# - document: use the document as the root for the element
rootMode:
# (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
# - mustache
# - nunjucks
templateEngine:
# The configuration to pass to the block. Required. For blank configurations
# pass an empty dictionary {}
config: {}