đź“–
PixieBrix Documentation
🎒

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:

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 release
  • v2: made data flow between bricks explicit. Bricks had to reference data from previous bricks using the @outputKey for that brick
  • v3 (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.

⚠️
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 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: {}

Twitter