📘 This article explains how to create a List of values variable to extract every matching element on a page into a single variable in PageWorkers. PageWorkers is part of Botify's Activation Suite, available as an option with all Botify plans.

Overview

A standard extracted variable returns one value from your page: the first element that matches its CSS selector. A “List of values” variable returns every element that matches its CSS selector, as a list you can loop over in your template.

Because the variable collects the number of elements the page contains, the same optimization works on a page with two breadcrumbs and on a page with twenty. You do not need to create one variable per element.

List of values variables are useful for building content from repeated page elements, such as:

A Breadcrumb list structured data block built from the breadcrumb trail on the page.
A list of images in Product structured data, built from a product image carousel.
An Item list structured data block built from the product tiles on a product listing page.
FAQ content built from question-and-answer elements on the page.

List types

When you create a List of values variable, you choose what PageWorkers extracts from each matching element:

Single value: PageWorkers extracts one value from each matching element and returns a list of values. For example, the src attribute of every image in a carousel.
Multiple values: PageWorkers extracts several named fields from each matching element and returns a list of items, each containing those fields. For example, the name, link, and price of every product tile on a listing page.

Single value example

A List of values variable named images that extracts the src attribute of each carousel image returns:

[
  "https://www.example.com/images/product_01.jpg",
  "https://www.example.com/images/product_02.jpg",
  "https://www.example.com/images/product_03.jpg"
]

Multiple values example

A List of values variable named products with the fields title, url, and price returns:

[
  { "title": "Linen Halter Top", "url": "/product/linen-halter-top.html", "price": "139.00" },
  { "title": "Lace Bralette", "url": "/product/lace-bralette.html", "price": "139.00" }
]

Creating a List of values variable

While defining a template in a Page Editor optimization, click Create new in the “Define your variables” section.
Select the “List of values” option.
In the Name field, enter a name to identify the variable (e.g., breadcrumbs). You use this name to reference the variable in your template.
Select Extract from page.
Select List of values as the variable type.
In the "CSS Selector" field, enter a CSS selector that matches each element to extract. For a breadcrumb trail, use the selector that matches the individual breadcrumb items, not the element that wraps the whole trail.
Choose single value or multiple values, then define the extraction rules:
1. Single value: Select an extraction strategy. If you select the attribute strategy, identify the attribute name (e.g., src).
2. Multiple values: For each field, identify a name (e.g., title), a CSS selector, and an extraction strategy. PageWorkers evaluates each field's CSS selector within each element matched in Step 5.
Click Preview to confirm the variable returns the expected list.
Click Save.

Using a List of values variable in a template

A List of values variable contains a list, so you loop over it in your template rather than inserting it directly.

Single value: Each item in the loop is the extracted value.

{% for image in images %}
  <img src="{{ image }}">
{% endfor %}

Multiple values: Each item in the loop contains the fields you defined. Reference a field with dot notation: the item name, a period, then the field name.

{% for product in products %}

  <li><a href="{{ product.url }}">{{ product.title }}</a></li>

{% endfor %}

The examples above use Nunjucks syntax. For conditions, loop variables, and filters, see Using Advanced Functionality in PageWorkers Templates.

Example: creating BreadcrumbList structured data

This example builds BreadcrumbList structured data from a breadcrumb trail already on the page.

Create a List of values variable named breadcrumbs with multiple values:
1. CSS Selector: The selector that matches each breadcrumb item.
2. Field name: The breadcrumb text, using the text content strategy.
3. Field link: The href attribute of the breadcrumb link, using the attribute strategy.

Add a new structured data block with the following template:

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {% for crumb in breadcrumbs %}
    {
      "@type": "ListItem",
      "position": {{ loop.index }},
      "name": "{{ crumb.name }}",
      "item": "{% if crumb.link %}{{ _currentProtocol + "//" + _currentHost + crumb.link }}{% else %}{{ _currentUrl }}{% endif %}"
    }{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}

In this template:
- loop.index numbers each item's position, starting at 1.
- {% if not loop.last %},{% endif %} adds a comma after every item except the last, so the JSON-LD stays valid.
- The last breadcrumb is usually the current page and often has no link. The {% if crumb.link %} condition uses the current URL when a link is missing.
- If your breadcrumb links are relative (e.g., /category/shoes), _currentProtocol and _currentHost turn them into absolute URLs.
Validate the result with Google's Rich Results Test before deploying.

Read next:

Extracting Lists of Values in PageWorkers