Template Syntax

Template Syntax lets a Workflow use data that is available when it runs. You can read a variable, calculate a value, format extracted text, or build a URL from a search term.

If you are new to entering expressions in the editor, start with Use Variables. For help creating the variables used in your expressions, see Variables.

Start with an Expression

Write an expression between {{ and }}. For example, to read a variable named searchTerm, use:

{{$vars.searchTerm}}

Here, $vars tells Tapicker to look in the Workflow's variables, and searchTerm identifies the value to read. If that variable holds headphones, the expression returns headphones.

Spaces just inside the braces are optional:
{{$vars.searchTerm}} and {{ $vars.searchTerm }} mean the same thing.

Enter expressions in fields that accept variables. Some fields require you to turn on Use Variables first; others accept expressions directly. The field still determines how the result is used: an Input Text field needs text, while a Loop can use an Array.

Available Namespaces

A namespace groups related Workflow data. Choose the namespace for the kind of data you want to read:

$args — arguments supplied to the Workflow.
$vars — variables saved during the run.
$cols — other columns in the row currently being extracted.
$loops — the current index and value of a Loop.
$tables — tables created by Extract Data.
$runtime — execution state, such as the current tab or previous Block's result.

Data becomes available when the relevant Block runs. For example, read a variable after the Block that sets it, and read a table after its Extract Data Block has run.

$args

Arguments defined by Set Arguments are available under $args. Use them for values supplied when starting the Workflow.

If an argument is named Link, read it with:

{{$args.Link}}

$vars

Variables created by Set Variables, or saved by other Blocks, are available under $vars.

If a variable is named isAvailable, read it with:

{{$vars.isAvailable}}

$cols

Use $cols in Extract Data column definitions to read another column's value in the same row. The referenced column needs to be resolved before the column that uses it.

For example, if earlier columns named Price and Quantity contain numbers, a Dynamic column can calculate their total:

{{ $cols.Price * $cols.Quantity }}

Extract Data column settings for referencing values in the same row

Use $tables when you need to read extracted rows outside the column definitions.

$loops

Each Loop has a name. Inside that Loop, use its name under $loops to read the current iteration's index or value.

Suppose a Loop named L300 processes this list:

["headphones", "keyboard", "mouse"]

Read the current index, starting at 0:

{{$loops.L300.index}}

This returns 0, 1, then 2 as the Loop progresses.

Read the current item:

{{$loops.L300.value}}

This returns headphones, keyboard, then mouse.

$tables

Each Extract Data Block saves its table under the table's name in $tables.

Suppose a table named T900 contains these rows:

[
  { "Name": "Headphones", "Price": 29.99 },
  { "Name": "Keyboard", "Price": 49.99 },
  { "Name": "Mouse", "Price": 19.99 }
]

Read the number of rows:

{{$tables.T900.size}}

The result is 3.

Read all rows, for example to pass them to a Loop:

{{$tables.T900.rows}}

Read the first row, or just its product name:

{{$tables.T900.rows[0]}}
{{$tables.T900.rows[0].Name}}

The first expression returns the row Object. The second returns Headphones.

$runtime

$runtime holds values associated with the current execution. It is separate from $vars, so a user variable with the same field name does not conflict with it.

Read the previous Block's result status:

{{$runtime.prevResult.status}}

Read the ID of the tab currently used by the Workflow:

{{$runtime.currentTab.id}}

Some runtime fields are available only in specific settings. While resolving an Extract Data row, currentRow contains its zero-based index and row selector:

{{$runtime.currentRow.index}}
{{$runtime.currentRow.selector}}

While resolving a Download File filename template, filename contains the source filename without its extension, and extension contains the source extension:

{{$runtime.filename}}
{{$runtime.extension}}

Read Object Fields and Array Items

Use a dot to read an Object field and square brackets to read an Array item. Array positions start at 0.

Suppose a variable named products contains:

[
  { "name": "Headphones", "price": 29.99 },
  { "name": "Keyboard", "price": 49.99 }
]

Read the first product's name:

{{$vars.products[0].name}}

The result is Headphones. Use [0] for the first item; numeric dot notation such as .0 is not supported.

For a field whose name contains spaces, use quotes inside square brackets, such as {{$vars.product['Product Name']}}.

Choose a Path Dynamically

Square brackets can also contain an expression. If a Number variable named index holds 1, this reads the second product's price:

{{$vars.products[$vars.index].price}}

The result is 49.99. Keep the whole path inside one pair of {{ ... }}; do not nest another expression's braces inside the path.

You can choose an Object field in the same way. If fieldName holds price, use {{$vars.products[0][$vars.fieldName]}} to read the first product's price.

Write Literal Values

A literal is a value written directly in an expression. Use literals for fixed text, numbers, or other values you want to combine with Workflow data.

Text, Numbers, and Booleans

Put text in single or double quotes. Write numbers and Boolean values without quotes:

{{ 'Hello, Tapicker!' }}
{{ "Hello, Tapicker!" }}
{{ -123 }}
{{ 29.99 }}
{{ true }}
{{ false }}

The text 'false' is a String; false is a Boolean. Template Syntax also recognizes the special Number constants Infinity and NaN, though individual fields may require a finite number.

Arrays and Objects

You can create an Array or Object directly in an expression, including values read from variables:

{{ ['headphones', 'keyboard'] }}
{{ { name: $vars.productName, price: $vars.price } }}

See Data Types for help choosing the type you need.

Regular Expressions

Write a regular expression between slashes, with any flags after the closing slash. For example, this matches one or more digits:

{{ /\d+/g }}

Regular expressions are useful as arguments to pipeline functions such as replace, extract, and match. See Regular Expressions for help writing a pattern.

Null and Undefined

null represents an explicit empty value. undefined represents a missing or unavailable value. Write either without quotes:

{{ null }}
{{ undefined }}

The field receiving the result determines how these values are handled. For example, a variable or column may use its configured default value.

Calculate and Compare Values

Expressions can combine values with operators. Use Number values for arithmetic; + also joins text when an operand is a String.

Perform a Calculation

Use +, -, *, /, or % to add, subtract, multiply, divide, or find the remainder:

{{ $vars.price * $vars.quantity }}
{{ $vars.pageNumber + 1 }}
{{ $vars.total / $vars.itemCount }}
{{ $vars.index % 2 }}

Use parentheses to group a calculation:

{{ ($vars.price - $vars.discount) * $vars.quantity }}

Check a Condition

Use >, >=, <, or <= to compare numbers. Use === or !== to check whether values have the same type and value, or differ:

{{ $vars.stockCount > 0 }}
{{ $vars.status === 'ready' }}
{{ $vars.status !== 'sold out' }}

Combine conditions with && for “and,” || for “or,” and ! for “not”:

{{ $vars.stockCount > 0 && $vars.isAvailable }}
{{ $vars.isFeatured || $vars.isOnSale }}
{{ !$vars.isAvailable }}

These results can be used in a Condition Block.

Choose Between Two Values

Use condition ? valueIfTrue : valueIfFalse to choose a result:

{{ $vars.stockCount > 0 ? 'In stock' : 'Sold out' }}

You can also use || to provide a fallback:

{{ $vars.name || 'Anonymous' }}

This returns Anonymous when name is missing or has a value such as an empty String, 0, or false. If you need different fallback rules, see the default function in Pipeline Functions.

Call a Helper Function

Helper functions get or generate a value. Call a helper by its name, followed by parentheses:

{{ getPageURL() }}
{{ getPageTitle() }}
{{ getDate() }}

These return the current page URL, page title, and current date and time, respectively.

If a helper accepts arguments, put them inside the parentheses. Arguments can be literals, variable references, or calculations:

{{ getDate($vars.publishedAt) }}
{{ getRandomNum(1, $vars.maxPage) }}

See Helper Functions for available functions and their arguments.

Apply Pipeline Functions

Pipeline functions process an existing value. Write | after the value, followed by the function name. Chain functions to process the result from left to right.

For example, if name holds Tapicker , this removes the surrounding spaces and converts the text to uppercase:

{{ $vars.name | trim | toUpper }}

The result is TAPICKER.

If a function needs arguments, put them in parentheses. For example, to join a list with a comma and a space:

{{ $vars.items | join(', ') }}

The value on the left is passed into the function automatically; you only write the additional arguments. Parentheses are optional when there are no additional arguments, so trim and trim() are equivalent.

You can also combine helpers and pipelines. This formats the current date:

{{ getDate() | format('YYYY-MM-DD') }}

See Pipeline Functions for the full reference, or Data Transformation to apply transformations through the editor's settings.

Combine Expressions with Text

A field can contain a single expression or a template that combines expressions with text. This difference matters when you need to keep a Number, Array, Object, or Date.

Keep a Value's Type

In fields that accept these types, a complete expression can pass the value through without converting it to text:

{{$vars.items}}

If items is an Array, you can use this expression as a Loop's input. Text fields still convert their results to text, and Set Variables applies its selected data type.

Build Text from Values

When you add text around an expression, the result is a String:

Product: {{$vars.productName}}
Total: {{$vars.price * $vars.quantity}}

You can include multiple expressions, spaces, and line breaks. Arrays and Objects inserted into ordinary text templates are serialized as JSON; Dates become ISO 8601 text. Values from page elements contribute their underlying data.

Build a URL

To include a search term in a URL, encode the value before inserting it into the query string:

https://www.google.com/search?q={{$vars.searchTerm | encode('url')}}

If searchTerm holds wireless headphones, the result is:

https://www.google.com/search?q=wireless%20headphones

Encoding keeps spaces and characters such as & inside the search term from changing the structure of the URL.

Duck Values

Variables extracted from page elements keep the extracted data and information about the source element together in a Duck wrapper. A complete expression such as {{$vars.title}} can preserve that wrapper, which lets a later Block reuse the original target.

Read the Extracted Value

In a text field, {{$vars.title}} inserts the extracted text. To explicitly read only the underlying data, use:

{{$vars.title.value}}

If the data is an Object, you can usually read its fields directly. For example, {{$vars.product.name}} is shorthand for {{$vars.product.value.name}} when product is a Duck containing an Object.

The names value and target refer to the wrapper's own fields. If the extracted Object also has a field named value or target, use .value first to reach the data, such as {{$vars.product.value.target}}.

Reuse the Source Element

In a Target Element field, a complete expression such as {{$vars.title}} uses the Duck's saved target to locate the source element. Using {{$vars.title.value}} reads the data instead, so it does not preserve that target reference.

You can explicitly read target information when needed. For example, this builds a selector for an item's children:

{{$vars.Parent.target.selector}} > li.item

See Use a Variable as the Target for examples of reusing elements and clicking items in a Loop.

FAQ

Why Does My Expression Return Undefined?

A missing variable, field, or Array item normally returns undefined. Check the spelling and capitalization of the reference, make sure the Block that produces the data has run, and check that an Array index is within range.

An ordinary text template may display the word undefined when a value is missing. You can provide a fallback with an expression such as {{ $vars.name || 'Anonymous' }}.

Can I Use JavaScript Methods in an Expression?

Template Syntax supports a limited set of expressions. Calls such as $vars.items.join(', ') or $vars.name.trim() are not supported. Use pipeline functions instead:

{{ $vars.items | join(', ') }}
{{ $vars.name | trim }}

To count Array items or String characters, use {{ $vars.items | size }} or {{ $vars.name | size }}. Reading .length is not supported in Template Syntax.

Can an Expression Change a Variable?

Expressions are read-only. Assignment operators such as =, +=, &&=, ||=, and ??=, as well as increments such as count++, are not supported. Use Set Variables to save or update a value.