DocsWorkflowsComponentsMachinemachine:extension:list

machine:extension:list

Reads a page's repeated items as rows. It is the read half of paging through a listing. The repetition itself is never here, because a fragment is a flat list of steps and a browser that owns the loop is a browser deciding when to stop. This reads the page it is pointed at and hands the rows back, and the workflow document decides whether there is another page.

Options

Name	Type	Description
`url`	`string`	The page to open before reading; empty reads whatever the matched tab already shows
`match_url`	`string`	A substring an open tab's URL must contain for the read to reuse that tab
`client_id`	`string`	The extension client to read through, a hint the host may honour; empty leaves the choice of browser to the host
`selector`	`string`	The CSS selector matching the repeated item container, one match per row
`fields`	`ExtractField`	The named columns read out of each item, each selector resolved inside that item
`limit`	`int`	Caps how many items one read returns, leaving the extension's own bound in place at zero
`into`	`[]map[string]any`	The rows collected before this page, which this read appends to
`key`	`string`	The column whose value identifies a row, which is what tells a page of rows the run already has from a page of new ones; empty reads every page the budget allows
`known`	`[]string`	The key values the caller already holds, so a re-read stops where the listing reaches what is stored rather than paging to the budget
`next`	`ObservedPagination`	The control that reaches the following page, which is what machine:extension:observe reports, and which turns this read into a collecting loop
↳ `kind`	`string`	Is the shape the page uses to reach its next batch, one of link, numbered, more, or infinite.
↳ `selector`	`string`	Targets the control that advances the listing.
↳ `label`	`string`	Is the control's visible text.
↳ `url`	`string`	Is the next page's href when the control is a link.
↳ `pages`	`int`	Counts the numbered page links a pager prints, when it prints any.
`settle`	`string`	The CSS selector to wait for after reaching a page, defaulting to the item container
`budget`	`int`	How many pages the collecting loop may read, this call included
`pages`	`int`	How many pages have been read before this one
`timeout_ms`	`int`	How long to wait for the browser before failing the read

Outputs

Name	Type	Description
`rows`	`[]map[string]any`	Every row collected so far, this page's appended to whatever arrived in Into
`page`	`[]map[string]any`	Just this page's rows, in the order the listing carried them
`count`	`int`	How many rows are collected in total
`added`	`int`	How many rows this page contributed, zero meaning the selector matched nothing
`fields`	`[]string`	The column names every row carries
`empty`	`bool`	Whether this page contributed no rows at all, which is what a listing whose markup changed looks like when nothing errors
`unseen`	`int`	How many of this page's rows carried a key neither the caller nor an earlier page of this run already had. It equals Added wherever no key is named, because a run that cannot identify a row cannot claim to have seen it
`pages`	`int`	How many pages have now been read, this one included
`budget`	`int`	How many pages are left after this one
`more`	`bool`	Whether reading another page is worth it, meaning this one carried rows the run did not already have and the budget is not spent. A page that contributed nothing ends the loop, because a listing that keeps answering with an empty page pages forever, and so does a page of rows already held, which is both where an incremental re-read stops and what a pager linking to its own page looks like

Edit or read the source on GitHub