Documentation · ViewHelper reference

XSD schema file | vhs 2.1.3

Iterator / ExtractViewHelper

Iterator / Extract VieWHelper

Loop through the iterator and extract a key, optionally join the results if more than one value is found.

Extract values from an array by key

The extbase version of indexed_search returns an array of the previous search, which cannot easily be shown in the input field of the result page. This can be solved.

Input from extbase version of indexed_search">

      0 => array(
        'sword' => 'firstWord',
        'oper' => 'AND'
    1 => array(
        'sword' => 'secondWord',
        'oper' => 'AND'
    3 => array(
        'sword' => 'thirdWord',
        'oper' => 'AND'

Show the previous search words in the search form of the result page:


<f:form.textfield name="search[sword]"
    value="{v:iterator.extract(key:'sword', content: searchWords) -> v:iterator.implode(glue: ' ')}"
    class="tx-indexedsearch-searchbox-sword" />

Get the names of several users

Provided we have a bunch of FrontendUsers and we need to show their firstname combined into a string:

<v:iterator.implode glue=", "><v:iterator.extract key="firstname" content="frontendUsers" /></v:iterator.implode>
<!-- alternative: -->
{frontendUsers -> v:iterator.extract(key: 'firstname') -> v:iterator.implode(glue: ', ')}


<h2>Welcome Peter, Paul, Marry</h2>

Complex example

{anArray->v:iterator.extract(path: 'childProperty.secondNestedChildObject')->v:iterator.sort(direction: 'DESC', sortBy: 'propertyOnSecondChild')->v:iterator.slice(length: 10)->v:iterator.extract(key: 'uid')}

Single return value

Outputs the "uid" value of the first record in variable $someRecords without caring if there are more than
one records. Always extracts the first value and then stops. Equivalent of chaning -> v:iterator.first().
{someRecords -> v:iterator.extract(key: 'uid', single: TRUE)}
  • Tag usage example

    <v:iterator.extract key="NULL" content="[mixed]" recursive="1" single="1">
    	<!-- tag content - may be ignored! -->
  • Inline usage example

    {v:iterator.extract(key: 'NULL', content: [mixed], recursive: 1, single: 1)}


Argument Description Type

The array or Iterator that contains either the value or arrays of values


The name of the key from which you wish to extract the value


If TRUE, attempts to extract the key from deep nested arrays


If TRUE, returns only one value - always the first one - instead of an array of values

Required attribute

Revision history

commit 2c6a5deceb04dd4073b90ef96e85b27a4e3f3593
Author: Andreas Lappe <*****>
Date:   Thu Dec 20 14:09:12 2012 +0100

    [FEATURE] Add ExtractViewHelper
    ViewHelper to extract values by key from a nested array structure.

commit b056eaaa9eb0bba84946f38f0d9a8aa4b7d76271
Author: Andreas Lappe <*****>
Date:   Sat Feb 16 12:57:12 2013 +0100

    [TASK] Change the internals of the extraction

commit e2dbb85bdd8aca8a1a4423f2e880eb5d03c99319
Author: Claus Due <*****>
Date:   Fri Feb 22 11:29:40 2013 +0100

    [TASK] CGL cleanups in Iterator / Extract ViewHelper

commit dc3f0f4b0220f02d60adcafebd3c84d7a398cbfb
Author: Claus Due <*****>
Date:   Fri Feb 22 11:33:53 2013 +0100

    [TASK] Remove glue capability from Iterator / Extract ViewHelper
    This particular operation, along with any other advanced array post processing, is handled by chaining other v:iterator ViewHelpers.

commit 16312dad20853c976fc3b4687a086decf201d95d
Author: Claus Due <*****>
Date:   Fri Feb 22 11:36:19 2013 +0100

    [TASK] Improve error handling in Iterator / Extract ViewHelper

commit 351a5f8dacce9271826dd4add056be0671cb2766
Author: Claus Due <*****>
Date:   Fri Feb 22 11:41:17 2013 +0100

    [DOC] Made doc comment for Iterator / Extract ViewHelper markdown format

commit 812925e3b1be49d9c8b7a75bab5fbc815c00601d
Author: Claus Due <*****>
Date:   Wed May 22 00:06:43 2013 +0200

    [TASK] Cleanup as required by coding standards
    Excuse the not-using-PR-direct-to-master commit approach but this one is merely cosmetic in nature and the Travis build is failing because of it.

commit f765ef95a41f77a591f08830631d8a31049304e9
Author: Björn Fromme <*****>
Date:   Sun May 26 16:04:13 2013 +0200

    [TASK] C*****@param annotations

commit da31bad1d9bb058c072ddb5591e8ed907a1ae8e1
Author: Claus Due <*****>
Date:   Tue Dec 31 23:08:37 2013 +0100

    [TASK] Happy new year!

commit d2e531da034976e6db1478eef5a8478595fd16fe
Author: Claus Due <*****>
Date:   Sun Jan 5 00:45:10 2014 +0100

    [TASK] Migrate to using namespace core class names

commit 52bd6e41ccfef3d8193b350153912a9716e6a087
Author: Benjamin Rau <*****>
Date:   Tue Apr 1 21:09:00 2014 +0200

    [TASK] CGL compliance

commit da7677bc74f14e9a9300e4ba4487e52c3cb97642
Author: Claus Due <*****>
Date:   Sun Apr 20 01:13:33 2014 +0200

    [TASK] Switch to namespaces

commit 97861f3d441092a4d9b202516a617478765ad792
Author: Claus Due <*****>
Date:   Mon Sep 8 13:20:17 2014 +0200

    [FEATURE] Argument $single on Iterator / Extract ViewHelper
    When used, returns the first value instead of always returning all values. Use when result is expected to contain only one value, and avoid having to chain -> v:iterator.first() after .extract() to get to the actual value.

commit 8bb2fc5ee124ba19b0a0ab8e061c9a153fc4651f
Author: Xaver Maierhofer <*****>
Date:   Sun Jan 18 17:56:13 2015 +0100

    [TASK] Reference Copyright to file