๐Ÿคนโ€โ™€๏ธ

Multi-Page Automation

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:

  1. Start Page: a button extension point, configured to open a new tab and perform an action using window: target
  2. 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: {}