đź“–
PixieBrix Documentation
⛲

Page Editor Guide

🤖

Welcome to the PixieBrix Page Editor Guide! This is where you can learn about the Page Editor, the core of the PixieBrix extension and platform!

Presentation of the Page Editor

What is the Page Editor?

The Page Editor is the core of the PixieBrix extension.

It is a point-and-click interface that lets you modify any webpage without writing code. In the Page Editor you can create workflows to automate things and rapidly customize websites in your browser.

Understanding how the Page Editor works, is the fastest way to start building amazing things with PixieBrix.

The Page Editor is composed of 4 areas:

image

👉 Extensions List: A list of your active and inactive extensions

👉 Extension Overview Panel: A list showing you which bricks are part of your currently selected extension

👉 Extension Configuration Panel: A console where you can configure the behavior of a brick

👉 Data Panel: A data console with different tabs showing you the data available before, during and after execution of the brick

ℹ️

How to open the Page Editor

A quick reminder that to open the Page editor you have to hit the following keys on your keyboard depending on your platform:

  • Windows: Control + Shift + I
  • Mac: Command + Option + J
  • Or: right-click and select "Inspect" from the context menu and then click PixieBrix in the window that opens

Page Editor: Extension List

What is an extension?

In PixieBrix an extension is a way to enable you to customize the browsing experience.

An extension is a workflow that allows you to automate, customize, change - rapidly - things in your browser.

In PixieBrix extensions are useful when they are built from assembling one or more components together: We call these components ✨Bricks✨

Therefore, by combining multiple bricks together, using our Page editor, you create an extension.

You can easily turn extensions on or off by removing them altogether from the Page Editor or by changing their scope: this means you can tell the extension whether it can or cannot run on a website(s).

Active and Inactive extensions

In PixieBrix, you can configure any extension to run on a specific page, domain, subdomain, sub-set of pages or to run on ANY page.

When you set an extension to not run on a certain page, they automatically become inactive.

That’s why in the extension list you can see your active and inactive extensions.

Inactive extensions: are the ones that aren’t currently running on the page that you’ve opened PixieBrix on. They’re “hidden” by default but you can unhide them using the checkbox control if you want to.

Active Extensions: these are the other type of extensions listed here. They are the ones that can run on the page you’re on. Each of the active extensions can be triggered by an action.

Let’s learn about the types of extensions you can run through PixieBrix.

Types of extensions

  • Trigger: This can be triggered by a page-load event, a click, mouse-over - depending on the value selected to trigger the extension, which can be customized. Related information available
  • Quickbar: This trigger allows your extension to appear by using a bar that appears in the middle of your browser. This bar is visually and operationally similar to Alfred or the Spotlight Search Bar in Mac OS. This bar can be triggered with a keyboard shortcut - which can itself be set by the user in the browser options
  • Context-Menu: This allows the user to trigger an extension by right-clicking anywhere on a browser tab and seeing a contextual menu. If you have multiple extensions on a page set up to use the context-menu, a sub-menu appears.
  • Sidebar: This allows you to view the result of your extension in a sidebar. The sidebar is triggered by clicking the PixieBrix extension icon in your browser, or by programmatically showing the sidebar through another extension using the “Show/Hide sidebar brick”
  • Button: This allows you to run an extension by the way of adding a customizable button into a webpage that you can press to trigger.
  • Panel: Allows you to trigger a panel that, similarly to the Sidebar, can be used to show the result of an extension

Blueprints

If you look at the icons in the extension list you will notice there are a couple of icons above it.

  • The PixieBrix logo: Clicking it will take you to the PixieBrix options page in a new tab
  • Add button: This is where it all begins, click it to select from one of the many PixieBrix trigger bricks to build your extension
  • Add extension to blueprint button: A blueprint is like a folder or a container that keeps all your extensions grouped together. With an extension selected, click this button to create a new blueprint or move extensions from outside a blueprint, to inside one.
    • To create a blueprint, select an extension, click the “Add extension to blueprint” button then from the dropdown select Create a new blueprint.
    • To move an extension inside a blueprint, select the extension and then click the “Add extension to blueprint”
  • Remove extension from blueprint: If you want to remove an extension from the blueprint use this option.
    • Open a blueprint, select the extension you want to remove from a blueprint, and click the Remove extension from blueprint button.
    • You can decide whether to remove it from the blueprint or remove it completely from the page editor at this point.

Adding an extension

đź’ˇ

After you’ve read this guide, this is where your journey begins - find the blue Add button and get started!

Page Editor: Extension Overview Panel

Overview of your select extension

Inside the Extension Overview Panel, you can see the structure of what the extension does. All extensions have a trigger brick, which initiates the execution.

Most, if not all, extensions are composed of multiple bricks

Within the extension overview panel you can dig into the details of how each brick is connected to each other and - if needed - by selecting each brick you can see how it operates with the other bricks.

Output variables

In the overview panel, you can also see at a glance output variables - these are named variables. By default it’s PixieBrix that names these.

Variables are used to store valuable information after a brick in your extension has done its job.

Errors

Another important features in the overview panel is the ability to see which bricks are producing errors. For example, when you run an extension and it hits a snag - a red exclamation mark will point out which brick has produced the error.

Page Editor: Extension Configuration Panel

The Extension Configuration Panel is the heart of the page-editor. This is where you will be configuring the nuts and bolts of your bricks.

You will notice when configuring a brick in the page editor for the first time, are the output keys

image

Outputs Keys

  • Output Key — These are used to pass data from one brick to another. You enter a name, but use it as @name in the next brick. This variable will hold the output of the brick.
  • Keep in mind that most bricks produce an object as an output. So you would not use @name directly but you would use a property name such as @name.bar
  • Not all bricks have inputs or outputs. Some bricks, such as the confetti brick, are executed solely for their side effect. These kinds of bricks don’t support an input or output key variable
  • You can use the same output key for two bricks. The only time you’d generally want to do this is when you’re conditionally executing bricks. (See Advanced Option: Condition)

Inside the brick’s configuration you will notice that each field has a dropdown

Fields

Example of fields
Example of fields

Most input fields in the Extension Configuration Panel can take different types of inputs

  • Select: Fields have pre-defined options for you to select from
  • Text: Text fields that accept any type of text, and supports templating languages
    • The template syntax is Nunjucks. Nunjucks is nearly identical to Jinja2 which is used by Python projects and other projects
    • It’s set up to not require escape values
  • Variable:
    • Pro-tip, if your in text mode and start typing “@” it switches to variable mode
  • 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
  • Toggle: Fields of this type are values of boolean type. They are represented as a true/false toggle
  • Array: This input accepts multiple values, usually comma separated
  • Object(K:V): This type of field allows for passing on data in the Key:Values pairs.

Advanced Options

This section of the configuration panel contains, as the name implies, advanced options for each brick. These options vary based on the brick - however the most common options available under this advanced section are:

Condition option

  • If a condition is applied, the brick only runs if the condition evaluates to a truthy value. The description lists which string values are considered truthy for each brick.
    • đź’ˇ

    Here’s an example: You have two bricks A and B Brick A returns a value in a variable called @output.data The value of @output.data is set to “John Doe” after brick A is executed In brick B we use the value of @output.data We set the value of the Condition field under Advanced Options for brick B to the following string: {{ true if @output.data == “John Doe” }} Because @output.data was set to have the value “John Doe”, the condition string returns true...and thus, Brick B executes. If brick A returned “Alice Doe” instead, then the condition statement would NOT return true, and therefore brick B would execute.

In these conditional fields you can pass different values, such as the expression shown in the example above or:

  • Toggle (boolean literal): Setting truthy or falsy explicitly is useful for temporally skipping a brick during development.
  • Using the data held in a variable - such as the value of a variable output from another brick @data.foo
  • truthy or falsy as a result of using text template:
    • Using nunjucks, the shortest way to write an expression is using their conditional expression syntax: {{ true if <expr> }}
  • For more complicated business logic, you can use a jq brick to the pipeline. Then using the output of such brick you can evaluate the condition

Window/Target option

Some bricks have a Target option, this allows to set a context for the brick to run in.

This context can be one of:

  • Opener
  • Target: Run the brick in the most recent tab that was opened

đź’ˇ

Here’s an example: If during the execution of your extension you open a new tab, you might want and you want the brick to run in the context of the new tab you should set Target to “opener”. If you open a new tab and you want to fill a form, you would use the Set Input Value brick, and under advanced option select Target

Root option

Some bricks are “root-aware”, they take the context of the clicked element. Typically this is either to base a selector off of (to find a sub element, or to determine which data to return about an element)

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

Page Editor: Data Panel

The last part of the Page Editor is the Data Panel. In the Data Panel you can find input, contextual, and output data. By leveraging this data you can understand how to create or edit the configuration of your brick(s).

Data Panel

The data panel is divided in 4 tabs

  • Context: the input context available to this brick (All the output keys and service keys)
  • 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: for bricks that are “pure” — i.e., that are safe to run automatically because they don’t have side-effects — PixieBrix will update this preview of the output as you update the brick configuration. This is very helpful for JQ/regex/etc. bricks where you’re tweaking business logic

...and that’s all for the Page editor guide! Thanks for reading this far - if you have any questions big or small - join us on Slack or post in the community forums.