- 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 mod or composite block, you can provide the window
to control which tab the action is performed on:
- self: the tab the mod 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
mod directive (see below)The permissions
directive
The permissions directive in mods requests additional permissions when the mod is installed. Use this when the foundations in the mod don't already require the necessary permissions
- id: "@example/my-extension-point"
label: Mod 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 mod points:
- Start Page: a button start brick, configured to open a new tab and perform an action using
window: target
- Opened Page: a button starter brick, configured to send data to the opener, and close the opened tab. Uses
window: opener
TLO Vehicle Report Example
Mod for Start Page
Here's a mod 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 mod 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
Mod for the Search Results Page
We then configure a button starter brick 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: {}