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.
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:
will be expanded to these 3 strings:
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:
and the clipboard content was:
then this call:
will return this string:
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.
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.
let newText = await ACtl.expand('<selection.replace(/\\bJohn\\b/i, clipboard)>') ;