📖
PixieBrix Documentation
🎨

Page Editor Guide

👋
Welcome to the PixieBrix Page Editor Guide! This is where you can learn about the Page Editor, the easiest way to add actions and enhancements to any site!

Page Editor Overview

The Page Editor is a point-and-click interface to add actions and enhancements to any web site without writing code. The Page Editor is included with the PixieBrix Browser Extension.

Learning to use the Page Editor enables you to automate your work, and customize the tools you use most.

Opening the Page Editor

ℹ️
Full instructions for opening the Page Editor are available here:
📃
Open the Page Editor (2 min)

As a reminder, you can open the Page Editor on a page by right-clicking the page and selecting “Inspect” from the context menu.

Alternatively, you can use a keyboard shortcut:

  • Windows: Control + Shift + I, or F12
  • Mac: Command + Option + J, or F12

In the Chrome DevTools pane that opens, select the “PixieBrix” tab.

Page Editor Layout

The Page Editor consists of 4 panels:

  • Blueprints Panel: a list of activated blueprints. By default, the Page Editor only shows the blueprints that are available on the current page
  • Blueprint Outline Panel: the outline of the bricks in currently selected blueprint
  • Brick Configuration Panel: the configuration for the currently brick currently selected in the outline pane.
  • Data Panel: A pane with multiple tabs showing you the data available to the selected brick and produced by the brick

The 4 panels of the Page Editor: the Blueprints Pane, Blueprint Outline Panel, Brick Configuration Panel, and Data Panel.
The 4 panels of the Page Editor: the Blueprints Pane, Blueprint Outline Panel, Brick Configuration Panel, and Data Panel.

Blueprints Panel

What is a Blueprint?

A Blueprint is a grouping of one or more actions and enhancements that can run on a web page. Blueprints are created by combining any number of mix-and-match steps called ✨ Bricks ✨.

Types of Actions and Enhancements

There are 5 kinds of actions and enhancements you can create with PixieBrix:

  • Button: a customizable button to the webpage that runs an action
  • Context Menu: a right-click menu that runs an action on the selected text or element
  • Quick Bar: an menu item in the PixieBrix Quick Bar that runs an action. Learn how to setup your Quick Bar here:
    🏍️
    Quick Bar Setup
  • Sidebar: a custom panel displayed in the PixieBrix Sidebar. You can open the sidebar by clicking the PixieBrix icon in Chrome toolbar
  • Trigger: an automatic trigger that runs an action. Example of triggers are page loads, elements appearing on the screen, and more.

Blueprints Panel Layout

At the top of the Blueprints Panel, there are three buttons:

The Blueprints Panel
The Blueprints Panel
  • PixieBrix Logo Button: clicking the logo will open the Extension Console in a new tab
  • Add Button: This is where it all begins! Click Add to add an action or enhancement to the page
  • Collapse/Expand Button: click to collapse the Blueprints Panel. You can re-expand the panel by clicking the button again.

Each panel entry has the following information and actions:

  • Icon: indicates the type of action or enhancement
  • Name: the name of entry
  • Save Indicator/Button: click the button to save changes. The button will only be enabled if there are unsaved changes
  • Action Menu (three dots menu): a dropdown menu with the following actions:
    • Reset: resets any unsaved changes
    • Remove: remove a blueprint from your computer. The blueprint still is still available from your PixieBrix account
    • Add to Blueprint: add the action/enhancement to a new or existing blueprint
    • Remove from Blueprint: remove an action/enhancement from a blueprint
    • Make a Copy: create a copy of the blueprint

Available vs. Unavailable Blueprints

Actions and enhancements can be configured to run a specific URL, subdomain, or domain.

By default, the Blueprints Panel hides blueprints that are not configured to run on the current page. To instead view all blueprints, check the “Show X unavailable” checkbox.

Check the Show X unavailable checkbox to view blueprints that aren’t configured to un on the page.
Check the Show X unavailable checkbox to view blueprints that aren’t configured to un on the page.

Blueprint Outline Panel

The Blueprint Outline Panel displays an outline of an action/enhancement:

Example Blueprint Outline Panel displaying a Trigger
Example Blueprint Outline Panel displaying a Trigger

The first item in the outline is always the Button, Context Menu, Quick Bar, Sidebar Panel, or Trigger.

Brick Actions

Adding a Brick

To add a brick, click the + icon in the location to add the brick

Configuring a Brick

To configure a brick, select the brick in the Blueprint Outline Panel

Moving a Brick

To move a brick, click the up or down arrow for that brick

Brick Actions Toolbar

The Blueprint Outline toolbar includes two action buttons:

  • Copy (Copy Icon): copies the selected brick. You can paste the brick into the same blueprint, or another blueprint
  • Delete (Trashcan): deletes the selected brick

Brick Summary Information

Each brick displays a summary of it’s information:

  • Icon: indicates the type of brick
  • Label: the brick name, or custom label
  • Output Variable Name: the variable name of the brick output
  • Brick Status Indicator: the status from the blueprint’s latest run

The Blueprint Outline Panel showing status indicators for each brick.
The Blueprint Outline Panel showing status indicators for each brick.

Brick Label

The Blueprint Outline Panel displays either:

  • The name of the brick (default)
  • The custom label name, if configured via the Brick Configuration Panel

Brick Output Variable

Each brick that produces an output will display its output variable key. In the example screenshot above, the “Show a modal or sidebar form” above has the output key @form.

Outputs produced by a brick can be used by subsequent bricks. The Brick Configuration Panel section covers how to configure the output variable for a brick.

Brick Status Indicator

When you run an action or enhancement from the Page Editor, the Brick Overview Panel will show the status of each brick:

  • Green Check: the brick succeeded
  • Red Exclamation Mark: the brick raised an error
  • Grey Dash: the brick was skipped due to a condition
  • Blue Clock: the brick is currently running

Brick Configuration Panel

The Brick Configuration Panel is the heart of the Page Editor. This is where you will configure the nuts and bolts of your bricks.

Brick Configuration Panel Layout

The Brick Configuration Panel showing the configuration for the Window Alert Brick
The Brick Configuration Panel showing the configuration for the Window Alert Brick

Step Name

A custom step name to display in the Blueprint Outline Panel and in error telemetry. If you do not provide a name, it defaults to the name of the Brick

Output Key

The output variable name. The field will appears as disabled if the brick does not produce an output. For example, the Window Alert brick in the screenshot above does not produce an output.

Output Key Tips:

  • If you enter name, it will be available to other bricks as @name . (The field add the @ prefix for you automatically.
  • Two bricks can have the same output key. The second brick’s output will replace the output of the first brick. For readability, the best practice is to use unique output keys. The exception is when the bricks are configured to conditionally run (See Advanced Option: Condition)

Brick Input Card

The Input Card contains the primary brick-specific configuration for the brick. The configuration options vary by brick.

Brick Documentation Link

If the brick is from the PixieBrix Marketplace, you can view its documentation by clicking the View Documentation link in the Input Card Header

Input Entry Modes

To the right of each input field, there’s a toggle for controlling the input entry mode for the field.

Example of fields
Example of fields

Entry mode availability is based on the brick. Here are all the available entry modes:

  • Select: a dropdown of pre-defined options to select from
  • Text: text fields that accept any text, and supports templates. See the
    📘
    Text Template Guide
  • Variable: a variable from a preceding brick
    • ℹ️
    Pro-tip: if the you are in the text entry mode and type @, the field will automatically switch to variable entry mode
  • Toggle: pass true/false by toggling on or off
  • Array: provide zero of more values to the field
  • Object(K:V): passing key:value pairs of data
  • Exclude: don’t pass a value for the field
    • ℹ️
    Pro-tip: when the field is in exclude mode you can just click on the field. You can then start typing

Advanced Options Card

As the name implies, the Advance Options card includes advanced options.

Condition Field

If you provide a condition, the brick will only run if the condition evaluates to a truthy value. For convenience, PixieBrix considers some text as truthy: true, yes, y, on, and 1

You can provide a condition as one of the following:

  • Text: either a hard-coded value or a text template
    • ℹ️
    Using a text template, the shortest way to write an expression is using their conditional expression syntax: {{ true if <expr> }}. Learn more at
    📘
    Text Template Guide
  • Number: non-zero numbers are considered truthy
  • Toggle: toggling the brick on/off using a toggle
  • Variable: a variable from a preceding brick

For complicated business logic, you can use the jq - JSON processor brick, and pass the output to the condition using the variable entry mode.

Target Field

The Target Field controls where the brick executes. This most frequently used targets are:

  • Current Tab: the current tab/frame (default)
  • Opener: the tab that opened this tab
  • Target: the most recent tab that this tab opened. For example, when using the Open a Tab brick
💡
Example of using Target: Target Tab to automate form fill If you want to open a tab and fill out a form on the tab 1. Add the Open a Tab brick with Target: Current Tab (self) 2. Add the Form Fill brick with Target: Target Tab

Root Field

Some bricks are “root-aware”. The operate using the context of an element on the page. For example, when creating a Trigger that runs on an element, the bricks attached to the trigger run in the context of the element that caused the trigger to run.

Root-aware bricks use the element to base selector evaluation on (to find a sub element), or to determine which data to return about an element.

The Root Field has two options:

  • Inherit: use the current root element
  • Document: force using the document as the root element

Data Panel

The right-most panel in the Page Editor is the Data Panel. As the name suggests, the Data Panel displays information about a bricks inputs and output data.

The Render Tab of the data panel displaying inputs passed to the Window Alert Brick
The Render Tab of the data panel displaying inputs passed to the Window Alert Brick

The Data Panel has 4 tabs:

  • Context: the input context available to this brick. All of the variables available to the brick from the previous bricks and blueprint options
  • Rendered: the values that were passed into the brick on the last run.
    • Here “Rendered” refers to filling the context into text templates
  • Output: the output of the brick on the last run
  • Preview:
    • General: shows a preview of the bricks output, using the input context from the last run, and the current configuration. PixieBrix updates this tab in real-time as you update the brick configuration
      • ℹ️
      Pro-tip: the preview panel is extremely valuable when using the Regex and JQ bricks to transform data
    • When configuring the Show a modal or sidebar form brick: displays the form outline
    • When configuring the Render Document brick: displays the document preview

Frequently Asked Questions (FAQs)

I’m getting Insufficient browser permissions to make request…

Question: I am seeing this error “Insufficient browser permissions to make request. Specify an integration to access the API or add an Extra Permissions rule to the extensions.” How can I fix it?

image

Answer: Navigate to the first brick in your extension, if you scroll down the configuration panel you will find a blue button that says: Extra Permissions

image

Extra Permissions just records that PixieBrix needs permissions to make calls to the API provider even though the extension is not running on that page

Twitter