ACtl.expand

Replaces all placeholder expressions in a given string with their corresponding values.

See the full list of supported placeholders and syntax at Placeholders.

ACtl.expand(template[,tabSpec][,returnType]) template Type: string String containing zero or more Placeholders. tabSpec Type: TabSpec Default: undefined If template contains placeholders that access tab properties (such as <title> or <url>), this argument must specify the tabs from which to get those properties. Otherwise, this argument is ignored.

It can be either a tab ID, a filter object, a tab-selection name or an array combining all that. Full details at Tab Specifier.

It can be omitted even if returnType is not omitted. It defaults to the tab in which the script is running. returnType Type: string Default: 'string' Either the string 'string' or 'array' for whether to return the result as a string or as an Array of strings.

See Multiple expansion below for full details. Returns Type: Promise Resolves to: string | Array Returns immediately. The Promise will resolve with the string or array of strings (as indicated by returnType) that results from replacing all placeholders with their corresponding values. Throws Type: string Error description if template is not a string or if tabSpec is not a valid Tab Specifier.

Multiple expansion

A string can be expanded to multiple strings if it contains placeholders of these types:

1. Placeholders that return an Array.

2. Placeholders that access tab properties when the tabSpec argument specifies more than one tab.

Example for case 1:

If the omnibox contained the text John Paul Peter, then the <omnibox.words> placeholder will return an array with 3 elements. Therefore, the following string:

"http://google.com/search?q=<omnibox.words>"

will be expanded to these 3 strings:

http://google.com/search?q=John
http://google.com/search?q=Paul
http://google.com/search?q=Peter

The way these 3 strings are returned by ACtl.expand() depends on its returnType argument.

If returnType is 'array', then the strings are returned as a 3-element array.

If returnType is 'string', the 3 strings are joined into a single string separated by a newline character.

Example for case 2:

If the current Chrome window had 3 tabs with the following titles:

Title of first tab, Title of second tab, Title of third tab

then this call: ACtl.expand("(<index>) <title>", "#currWinTabs", "array")

will return this array:


	[
		"(1) Title of first tab",
		"(2) Title of second tab",
		"(3) Title of third tab"
	]

Since the <index> and <title> placeholders are tab properties, they will expand to multiple values because the tabSpec argument specifies more than one tab ("#currWinTabs" in this example).

Example for cases 1 and 2 combined:

When a string contains more than one multi-expansion placeholders, the resulting expansion will be the cartesian product of all those multi-expansions.

For instance, if the current Chrome window had the following 2 tabs:

http://google.com/search?q=hi
http://bing.com/search?q=bye

and the clipboard content was:

Shirts
Sweaters
Trousers

then this call:
ACtl.expand("<url.protocol>//<domain><path>?q=<clipboard.lines>", "#currWinTabs")

will return this string:

http://google.com/search?q=Shirts
http://google.com/search?q=Sweaters
http://google.com/search?q=Trousers
http://bing.com/search?q=Shirts
http://bing.com/search?q=Sweaters
http://bing.com/search?q=Trousers

Examples

Get the current text in the omnibox of the current Chrome window.

let omniboxText = await ACtl.expand('<omnibox>') ;

Get the URL of all currently open pages as a single string, one URL per line.

let allOpenUrls = await ACtl.expand('<url>', '#allTabs') ;

Get the clipboard content followed by a space and the current date in parentheses.

let clpbrdWithDate = await ACtl.expand('<clipboard> (<date>)') ;

Get an array with all selected words in quotes.

let quotedWords = await ACtl.expand('"<selection.words>"', 'array') ;

Get an array with the tab title and URL of all tabs in the current window.

let titleAndUrl = await ACtl.expand('<title>\n<url>', '#currWinTabs', 'array') ;

Get a single string with the tab position, width, height and title of all tabs in MRU order.

let mruTabs = await ACtl.expand('(<index>) [<width>x<height>] <title>', '#mruTabs') ;

Get the current text selection with all ocurrences of "John" replaced with the clipboard content.

let newText = await ACtl.expand('<selection.replace(/\\bJohn\\b/i, clipboard)>') ;

Observe the use of double-backslash characters above. Inside a string, a double-backslash becomes a single backslash, so the RegExp ends up being /\bJohn\b/i. Scripting API Script Isolation Asynchronicity Backgrnd Scripts GUI vs API ACtl.include ACtl.import ACtl.getFile ACtl.saveFile ACtl.saveURL ACtl.openURL ACtl.closeTab ACtl.runInTab ACtl.runInFrames ACtl.runInPageCtx ACtl.getTabInfo ACtl.getTabIds ACtl.TAB_ID ACtl.setTabState ACtl.captureTab ACtl.execAction ACtl.runCommand ACtl.getClipboard ACtl.setClipboard ACtl.expand ACtl.switchState ACtl.var ACtl.pubVar ACtl.on ACtl.off ACtl.sleep ACtl.STOP_CHAIN ACtl.STOP_FULL_SEQ