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: {}

ℹ️

When using the "target" window, you must ensure the PixieBrix has access to that tab. You can ensure this with the 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: {}

Multi-Page Automation