AutoControl Control your browser your way Forum               Install now from theChrome Web Store

Placeholders


A placeholder is a text expression between the characters < > that marks the place where to insert a piece of data into a larger text.
For example, <clipboard> is a placeholder for the clipboard content.
Therefore, this text snippet: Hi <clipboard>, how are you?
would be expanded to: Hi John, how are you?
if the clipboard contained the word John.
Placeholders are automatically expanded when used in actions such as Open URL, Save URL, Extract URLs, Text to URL, Insert text, Clipbrd put, and a few others.
AutoControl scripts can also expand placeholders in a given piece of text by using the ACtl.expand function.
A placeholder can be a simple expression such as <selection>, <clipboard.lines> or <url.domain>, or it can be a very complex expression such as:
<selection.replace('John', clipboard).split(/\s*\n\s*/)[2]>

Below is the complete list of simple expressions supported. Further down is the explanation and syntax of complex expressions.

Simple expressions

In addition to the tables below, all properties of the TabInfo object are valid placeholders as well. e.g. <title>, <url>, <window.type>, <window.width>, etc.

<clipboard> Text content of the system clipboard
<clipboard(n)> Text content of clipboard n, where n=0 is the system clipboard and 1-5 are the extra clipboards supported by AutoControl.
<selection> Cursor selection in the focused window, given as a string or Array of strings depending on the type of window.
For example, in a browser window the cursor selection is the selected text minus any non-textual elements such as images.
In a spreadsheet window (such as MS Excel), it'll be all selected cells in text form.
In a file explorer window, it'll be an Array containing the selected file/folder paths.
An empty string is returned if no supported selection type is found.
Not all kinds of windows are supported. e.g. text selection in a command prompt window cannot be obtained.
<omnibox> Text currently visible in the omnibox of the current Chrome window. i.e. either the URL of the active tab or any other text that was typed into the omnibox.
See this page for a few examples of using this placeholder.
<date> The current date with format Y-M-D. It accepts a custom format string as an optional argument. e.g. <date('M/D/Y H:I:S')>
Y: Year       M: Month       D: Day       H: Hours       I: Minutes       S: Seconds

URL components
These placeholders return subcomponents of a tab's URL.
<url.protocol> A tab's protocol
<url.user> A tab's username
<domain>
<url.domain>
A tab's full host name
<mainDomain>
<url.mainDomain>
A tab's host name minus all subdomains at the left end (like www and others)
<url.port> A tab's port
<path>
<url.path>
A tab's path
<dirPath>
<url.dirPath>
A tab's path without the filename, i.e. everything upto the last slash character
<url.query> A tab's query string
<url.fragment> A tab's fragment

System directories
<dir.desktop>The current user's desktop folder
<dir.documents>The current user's "My Documents" folder
<dir.profile>The current user's profile folder. e.g. C:\Users\John
<dir.appdata>The current user's Appplication data folder. e.g. C:\Users\John\AppData\Local
<dir.windir>The OS's installation directory. e.g. C:\Windows
<dir.progFilesX86>The Program Files folder for 32-bit programs. e.g. C:\Program Files (x86)
<dir.startup>The current user's startup folder
<dir.recent>The current user's "Recent items" folder

User variables
<var.var_name> var_name must be any variable created with the ACtl.pubVar function.
<env.var_name> var_name can be any of the OS's environment variables as well as any variable defined at Control Panel > User Accounts > Change my environment variables

Complex expressions


Placeholders can also be expressions of any complexity by using any combination of the following syntaxes:
SyntaxExample
dot notation<clipboard.lines>
bracket notation<clipboard.lines[2]>
Function call<clipboard.split(';')>
number literal<clipboard.charAt(123)>
string literal<clipboard.concat('hello')>
RegExp literal<clipboard.split(/[\n\r]+/)>
Nested placeholders<clipboard.replace('John', clipboard(1))>

This allows placeholders to access all standard Javascript properties and methods of all data types (string, Array, etc.).
However, the argument types that can be passed in a function call are limited to those in the above table.
Example:   <clipboard.replace('John', clipboard(1)).split(/\s*\n\s*/)[2]>
The above placeholder gets the clipboard content and replaces all ocurrences of "John" with the content of the Extra clipboard 1. Then it splits the resulting string by the RegExp /\s*\n\s*/ and then it gets the third element in the resulting Array (array indexes are zero-based).

Non-standard string properties and methods

AutoControl also supports the following non-standard properties and methods for the string data type:
.linesGives an array with each text line in the string. Empty lines are discarded.
.wordsGives an array with each word in the string. Blank characters act as word separators.
.escapeSame result as the encodeURIComponent standard function.
.unescapeSame result as the unescape standard function.
.match(regex)Similar to the standard match function, but returns only the first match or an empty string if no match is found.
.matches(regex)Same as the standard match function, but returns an empty array if no match is found.
.replace(search, replcmt)Same as the standard replace function, but replaces all ocurrences of search whether it's a string or RegExp.

Example:   <url.path.unescape.replace('/',' ').words>
The above placeholder gets the path component of a tab's URL, then it decodes percent-encoded chracters, then replaces all slash characters with spaces and finally it separates the resulting string into an array of words.
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