Advanced: Workshop
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
# quotes are required
id: "@pixiebrix/get"
# 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: !nunjucks |
{{ myVariable }} {{ anotherVariable }}
Variable references
In PixieBrix, variables and integration configurations referred to using a @
before their name. Because they start with a “@” you must enclose them in quotes.
service: !var "@nytimes"
prop: !var "@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: "v3"
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: !var "@variable"
listOfVariables:
- !var "@variable1"
- !var "@variable2"
You can provide a path, which also supports optional chaining:
# if optionalChild doesn't exist on variable, returns undefined
prop: !var "@variable.optionalChild?.childProp.grandchildProp"
Arrays are indexed using a numeric property:
# get itemProp from the first element in the array
prop: !var "@myArray.0.itemProp"
Templating
PixieBrix supports a number of templating engines for wiring together bricks.
Nunjucks / jinja2
Nunjucks is a Javascript port of jinja2 supports logic including conditionals and mathematical expressions.
- id: "@pixiebrix/html"
templateEngine: nunjucks
config:
html: !nunjucks "{% 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: !nunjucks "{{ 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:
# The configuration to pass to the block. Required. For blank configurations
# pass an empty dictionary {}
config: {}
Package Browser Extension Range
To set a minimum browser extension version, or allowed range, set the extensionVersion
directive in the package metadata.
The extensionVersion
directive supports a semantic version (SemVer) range:
metadata:
id: "@docs/my-modern-mod"
name: Mod with minimum version number
description: Blueprint exported from PixieBrix
extensionVersion: ">=2.2.1"
When used with Mod Deployments, if the user's browser version does not meet the extension range, PixieBrix will prompt the user to update their extension. See Deploying Mods
Last updated
Was this helpful?