🧱

Built-in Bricks

Readers

@pixiebrix/document-context

Read information about the current document

url:
  type: string
  format: uri
  description: The current URL
timestamp:
	type: string
	format: date-time
	description: The current time in ISO format

@pixiebrix/session

Read information about the current tab session

sessionId:
  type: string
  format: uuid
  description: A unique website session id
sessionTimestamp:
  type: string
  format: date-time
	description: Timestamp when the session started
navigationId:
	type: string
	description: A unique navigation id
	format: uuid
email:
	type: string
	format: email
  description: The email address for the account

@pixiebrix/profile

Read email and other profile information from PixieBrix app

email:
	type: string
	format: email
	description: The email address for the account

@pixiebrix/html/element

Read all attributes and JQuery data from an HTML element. Typically used with triggers (e.g., click) which run the reader in the context of the element that triggered the event

tagName:
	type: string
	description: The HTML element tag
data:
	type: object
	description: The data-* attrs from the element
attrs:
	type: object
text:
	type: string
	description: The combined text contents of element, including its descendants

@pixiebrix/timestamp

timestamp:
	type: string
	format: date-time
	description: Current ISO date-time

Effects

@pixiebrix/clipboard/copy

Copies text to the clipboard. Most helpful when using a template for the text argument

id: "@pixiebrix/clipboard/copy"
config:
  text: |
    {{streetNumber}} {{route}}
    {{city}}, {{state}} {{postalCode}}

@pixiebrix/browser/location

Navigate the current tab to the given URL

id: "@pixiebrix/browser/location"
config:
  url: https://www.google.com/search

  # URL parameters passed here will be automatically 
  # URI encoded. In general you should provide params here 
  # instead of using a template for the URL
  params:
    q: query
🧚

Pro-tip: If you want to template parts of the URL set templateEngine: nunjucks on the brick and use its urlencode filter {{ expression | urlencode}} . URL-encoding the value will ensure the resulting URL is syntactically valid

@pixiebrix/browser/open-tab

Opens a new tab with the given URL

id: "@pixiebrix/browser/open-tab"
config:
  url: https://www.google.com/search

  # URL parameters passed here will be automatically 
  # URI encoded. In general you should provide params here 
  # instead of using a template for the URL
  params:
    q: query
🧚

Pro-tip: If you want to template parts of the URL set templateEngine: nunjucks on the brick and use its urlencode filter {{ expression | urlencode}} . URL-encoding the value will ensure the resulting URL is syntactically valid

@pixiebrix/dom/trigger-event

Simulate a DOM element event, e.g., a click.

⚠️

Events triggered by this brick are not "trusted" as being a user action. See MDN's Event.isTrusted for more information. Certain front-end frameworks only respond to trusted events

Additional resources:

id: "@pixiebrix/form-fill"
config:
  # A JQuery selector matching a single element
	selector: 'button:contains("Submit")'

	# The DOM event, e.g., click, dblclick, hover
	event: click

@pixiebrix/forms/set

Set the value of an input field, and trigger the "change" event

id: "@pixiebrix/forms/set"
config:
  inputs:
		- selector: 'input[name="firstName"]'
      value: "{{ firstName }}"

@pixiebrix/form-fill

The form-fill effect fills out an HTML form on a page, and optionally submits the form

id: "@pixiebrix/form-fill"
config:
  # JQuery selector targeting the form. Doesn't currently 
  # have to be a form element. fieldNames and fieldSelectors 
  # are relative to this element. This must match exactly 
  # one form, so you may want to constrain the selector, e.g., 
  # based on the action URL of the form
  formSelector: form[action="/example/url"]

  # (Optional) By default, the form will not be submitted. 
  # You can add add the submit property to submit the form after 
  # filling in the values as specified.
  # submit: true

  # (Optional) You can _alternatively_ pass a JQuery selector. 
  # PixieBrix will click the element after filling in the values. 
  # Use this for forms that don't have an submit handler, e.g., 
  # because the submit button has an onclick handler.
  # submit: "[type='submit']"

  # input element names and the values to enter. Matched via 
  # "[name='']" JQuery selector
  fieldNames: 
    username: username
    name: "{{firstName}} {{lastName}}# 

  # input element names matched using a JQuery selector. 
  # Use when form fields don't have a name property,
  # or when you need to set the input field that underlies a 
  # custom widget, e.g., auto-complete/dropdown. When using an 
  # id selector (#), you must enclose the selector in quote marks 
  # so that the line is not interpreted as a comment
  fieldSelectors: 
    "#username": username
    "#country input": country

@pixiebrix/highlight

The highlight effect changes the background color of one or more elements on the page. This is commonly used by a Trigger to highlight certain fields on page load

id: "@pixiebrix/highlight"
config:
  # Optionally set the default background color for elements highlighted
  # by this brick.
 	# backgroundColor: "#FFFF00"

  # Optionally provide a root element selector for the other highlighting
  # rules to be relative to
  rootSelector: ".record"

  elements:
    # You can provide an element as a selector
		- ".field"

		# Or as an object
		- selector: ".otherField"
      
      # Whether or not to apply the highlighting rule
      condition: "{{ expression }}"
      
			# A hex color pattern to override the default
      backgroundColor: "#FFFF00"

@pixiebrix/wait/element

Wait for a DOM element to be on the page

id: "@pixiebrix/wait/element"
config:
  # JQuery selector for the element to await
	selector: ".field"

	# Selector can alternatively be provided with an array. 
  # PixieBrix will wait in order for the elements to appear.
	# selector:
	#   - ".section"
  #   - ".field"

@pixiebrix/browser/activate-tab

Activate the tab. Use in conjunction with the target directive in multi-page flows

id: "@pixiebrix/browser/activate-tab"
# One of "self", "opener", or "target"
window: "self"
config: {}

@pixiebrix/browser/close-tab

Close the tab. Use in conjunction with the target directive in multi-page flows

id: "@pixiebrix/browser/close-tab"
# One of "self", "opener", or "target"
window: "self"
config: {}

@pixiebrix/state/set

Updates the page state. You can use page state to persist information across actions. For example, using triggers to update the page state.

  • replace: replaces the page state with the data
  • shallow: replaces top-level properties in the page state
  • deep: follows Lodash's merge behavior to recursively merge objects and arrays

Returns the resulting state

id: "@pixiebrix/state/set"
config:
	# one of "shallow", "replace", or "deep"
	mergeStrategy: "deep"
	# the data to merge
	data: 
		foo: bar

Use the @pixiebrix/state/get brick to retrieve page state

Transforms

@pixiebrix/get

Make an HTTP GET request to an API. You can optionally specify a service to authenticate the request.

id: "@pixiebrix/get"
config:
  url: https://hn.algolia.com/api/v1/search

  # (Optional) a configured service to use to authenticate the request
  # service: @hackernews
 
  # (Optional) URL query parameters. These are automatically URI encoded. 
  # Any authentication configured by the service will override parameters
  # you set here
  params:
     query: query

  # (Optional) request headers. An authentication configured by the service
  # will override any headers you set here
  # headers: 
  #   x-my-custom-header:  

@pixiebrix/jq

jq allows you to extract, filter, and transform JSON data

Additional resources:

id: "@pixiebrix/jq"
config:
   # parsing search results from the NYTimes API
   # https://developer.nytimes.com/docs/articlesearch-product/1/routes/articlesearch.json/get
   filter: "[.response.docs[] | {url: .web_url, title: .headline.main, source: .source}]"

   # (Optional) specify the data. If not provided, the filter will 
   # be applied to the entire output of the the last block 
   # (or the reader, if the this block is the first block)
   # data: inputVariable

JQ Recipes:

{businesses: [.. | select(.["@type"]? == "Organization" or .["@type"]? == "LocalBusiness")]}
  • Splitting a field into a list (trimming surrounding white-space)
.foo // "" | split(",") | map(gsub("^\\s+|\\s+$";""))
  • Totaling numbers in an array of objects
.transactions | map(.amount | tonumber) | add
  • Grouping array items and summing the amounts
.transactions | group_by(.category) | map({category: .[0].category, amount: map(.amount) | add })

@pixiebrix/jsonpath

JSONPath is an expression language for transforming and selectively extracting data from JSON documents

Additional resources:

id: "@pixiebrix/jsonpath"
config: 
	path: "$.store.book[0].title"

@pixiebrix/regex

The regex extracts text by matching a regular expression with named capture groups. Any matched groups will be returned by name in the output.

Additional resources:

id: "@pixiebrix/regex"
config:
  input: propertyYearBuilt
  # matches a 4-digit number as output prop year
  regex: "Built in (?<year>\\d\\d\\d\\d)"

@pixiebrix/mapping

Perform a case-sensitive lookup in a mapping. Keys are converted to strings

id: "@pixiebrix/mapping"
config:
   key: query

   # (Optional) behavior when the value is not in the mapping
   # - null: return null (is the default)
   # - ignore: return the original value
   # - error: throw an error
   missing: null

   # The key-value mapping
   mapping: 
      Alabama: AL
      Alaska: AK

@pixiebrix/forms/data

Read data from all inputs on a form as an object with the input names as keys

id: "@pixiebrix/mapping"
config:

	# JQuery selector for the form. Can match multiple forms
	selector: "form"

@pixiebrix/state/get

Retrieves the page state that has been set using the @pixiebrix/state/set brick

 id: "@pixiebrix/state/get"
config: {}