- Use Cases
- YAML Configuration Basics
- Opening a tab
- The window directive
- The permissions directive
- Common Design Pattern
- TLO Vehicle Report Example
Use Cases
PixieBrix supports multi-page automation. Common use cases include:
- Opening a tab, and manually running a search
- Opening a tab, filling out a form, and then submitting the form
- On a search results page, add a button to send data to a form back on the opening tab
YAML Configuration Basics
Opening a tab
To open a new tab, use the @pixiebrix/browser/open-tab
effect (see )
- id: "@pixiebrix/browser/open-tab"
config:
url: https://www.pixiebrix.com
The window
directive
In a blueprint or composite block, you can provide the window
to control which tab the action is performed on:
- self: the tab the extension point is running on
- opener: the tab that opened the tab
- target: the tab that this tab opened
- id: "@pixiebrix/browser/activate-tab"
# One of "self", "opener", or "target"
window: "self"
config: {}
permissions
blueprint directive (see below)The permissions
directive
The permissions directive in blueprints requests additional permissions when the blueprint is installed. Use this when the foundations in the blueprint don't already require the necessary permissions
- id: "@example/my-extension-point"
label: Blueprint with additional permission requirements
permissions:
# A match pattern or array of match patterns to require the
# user to grant additional permissions
origins: https://www.pixiebrix.com/*
config: {}
Common Design Pattern
When designing multi-page flows, it's common to use a pair of extension points:
- Start Page: a button extension point, configured to open a new tab and perform an action using
window: target
- Opened Page: a button extension point, configured to send data to the opener, and close the opened tab. Uses
window: opener
TLO Vehicle Report Example
Blueprint for Start Page
Here's a blueprint that runs a vehicle search in TransUnion TLO. Note the use of window: target
in the configuration for the @pixiebrix/form-fill
brick
- id: "tutorial/vehichle-form-action"
label: Search Vehicle in TLO
permissions:
# Required because our other blueprint only has access to to the
# results URL, not the search.php URL used in open-tab below
origins: https://tloxp.tlo.com/*
config:
caption: Search TLO
action:
- id: "@pixiebrix/browser/open-tab"
# outputKey so we we keep the context before it
outputKey: ignore
config:
url: "https://tloxp.tlo.com/search.php?type=VehicleSearch2&mode=advanced"
- id: "@pixiebrix/form-fill"
window: target
config:
formSelector: "#searchform"
submit: "input[value='SEARCH']"
fieldNames:
LicensePlate: vehiclePlate
LicensePlateState: vehicleState
Blueprint for the Search Results Page
We then configure a button extension on the vehicle report page to 1) fill out a form on the opening tab, 2) activate the opening tab, 3) close the vehicle report tab
Note the use of window: opener
for the @pixiebrix/form-fill
and @pixiebrix/browser/activate-tab
bricks.
- id: "tutorial/vehicle-report-action"
label: Send TLO owner information to opener
config:
- id: "@pixiebrix/form-fill"
window: opener
config:
formSelector: "form"
submit: true
fieldNames:
ownerName: owners
- id: "@pixiebrix/browser/activate-tab"
window: opener
config: {}
- id: "@pixiebrix/browser/close-tab"
# don't need window: self because it's the default
# window: self
config: {}