---
title: "Data sources"
manual: "Handlebars"
version: "1.1"
permalink: "https://docs.typo3.org/permalink/cpsit/typo3-handlebars:usage-data-sources@1.1"
source: "Usage/DataSources.rst"
rendered: "2026-10-07T10:14:00+00:00"
---

# Data sources {#usage-data-sources}

Data processors often need to work on data that was prepared earlier, for
example the files returned by TYPO3's `files` processor or an
object assigned by an Extbase controller. The data processors provided by this
extension can read such data from so-called *data sources*.

-   [Available data sources](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:available-data-sources@1.1)
-   [Referencing data](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:referencing-data@1.1)
-   [Using the current value](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:using-the-current-value@1.1)

## Available data sources {#usage-data-sources-overview}

| Data source identifier | Contains |
| --- | --- |
| `processorConfiguration` | This processor's own config block |
| `processedData` | Output of previous processors and variables |
| `contentObjectRenderer` | Current record's field values |
| `contentObjectConfiguration` | `HANDLEBARSTEMPLATE` configuration, or the configuration forwarded by a parent processor |

## Referencing data {#usage-data-sources-payload}

Processors such as [process-each](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-process-each@1.1) accept a
`dataSource` option that tells them which data to work on. Some
processors use a more specific option name for the same purpose, e.g.
`iterable` ([iterable-to-array](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-iterable-to-array@1.1)),
`object` ([object-access](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-object-access@1.1)) or
`file` ([media](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-media@1.1)).

A reference consists of the data source identifier, a colon and the key
within that data source. Nested keys are separated by `/`:

```typoscript
dataProcessing {
    10 = files
    10 {
        references.fieldName = image
        as = files
    }

    # All files
    20 = process-each
    20 {
        dataSource = processedData:files
        # ...
    }

    # The first file only
    30 = media
    30 {
        file = processedData:files/0
        as = image
    }
}
```

Instead of referencing existing data, inline data can be configured with
the `data` option:

```typoscript
20 = process-each
20 {
    data {
        10 = foo
        20 = bar
    }
}
```

If a reference cannot be resolved, a warning is logged and the processor
leaves the processed data unchanged.

> [!NOTE]
> **See also**
>
> [Data source resolution](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:developer-corner-data-sources@1.1) for the complete resolution rules,
> e.g. how multiple references are merged.

## Using the current value {#usage-data-sources-current}

Processors that run nested inside [process-each](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-process-each@1.1) or
[iterable-to-array](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-iterable-to-array@1.1) receive the item currently being
processed as the content object's *current value*. The same applies to
[process-variables](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-process-variables@1.1) if its resolved payload is not an
array. Set `current = 1`
as sub-property of the data source option to use it. This works for all
processors listed above, e.g. `dataSource.current`,
`object.current` or `iterable.current`:

```typoscript
20 = process-each
20 {
    dataSource = processedData:files
    as = processedFiles

    dataProcessing {
        10 = object-access
        10 {
            object.current = 1
            path = publicUrl
            as = url
        }
    }
}
```

Alternatively, the item can be referenced as
`contentObjectConfiguration:currentValue`.

### Wrapped current values {#usage-data-sources-current-wrapped}

`stdWrap` functions expect the current value to be a string.
Values which cannot be converted to strings, such as arrays or objects, would
therefore break TypoScript such as `current = 1` or
`if.isTrue.current = 1`. To prevent this, such values are wrapped
in a `\CPSIT\Typo3Handlebars\DataProcessing\DataSource\CurrentValue`
object before being provided as current value. Scalar values, `null` and
stringable objects (implementing `\Stringable`) are provided as-is.

For wrapped, non-stringable values, the following applies:

-   Within `stdWrap`, arrays resolve to a comma-separated list
    of their scalar values and stringable objects (e.g. `foo,bar`). Nested
    arrays, non-stringable objects and `null` values are skipped. All
    other values resolve to an empty string (so e.g. `ifEmpty`
    applies).
-   The `current = 1` sub-property of data source options (e.g.
    `object.current`) resolves to the original, unwrapped value.
-   Custom code reading the current value via
    `ContentObjectRenderer::getCurrentVal()` receives the wrapper and can
    access the original value via its `value` property, see
    [Accessing the current value](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:developer-corner-data-source-aware-processor-current-value@1.1).