Jump to:

As discussed in #860082: BIKESHED: Token for a term or menu item's entire tree/hierarchy it would be useful if we can provide an array token type since it can be re-used by both a [menu-link:parents] token, a [term:parents] token, as well as [entity:field-name] tokens since fields are just an array of values. Plus this gives us implementations of a simple and complex use case.

Proposed tokens
[array:first] - first element of the array
[array:last] - last element of the array
[array:value:key] - dynamic token where 'key' is array[key]
[array:keys] - a chained 'array' token type of the keys of the array
[array:count] - the number of elements in the array
[array:join] - a comma-separated string of the values
[array:join:value] - this is a dynamic token, results of implode(value, array)

In hook_entity_property_info() of the entity API, arrays are treated via the special data type "list". They are represented via numerically indexed arrays, thus the keys are always just numeric. So they are really just a list of items, where the keys have no meaning it all.
I think it would make sense the same way for token too, as if you support arbitrary key:value pairs there is not really difference to all other data structures supported in token.

Then other useful tokens I could think of, would be [array:count] and perhaps a variant imploding all strings with commas.

Also in case you don't mind, calling the array type 'list' in token too, would probably help to streamline both data description worlds a bit.

Naming it list is also something I'm not sold on. It could possibly confuse/conflict with the list field module? Note that most people are not going to be seeing the [array:] part of the token. It will mainly be a token that is used for things like [node:menu-link:parents] and [term:parents] as an array 'type' token.

What about complex array types?
Let's suppose we've got a node reference field, set up as a multiple value field. How should we try to handle this using token module? Could we just allow chaining the token expression to apply to each array element?

Some examples:

[node:field-nref:join:title]

Join (using ', ') referenced node titles

[node:field-nref:first:url:alias]

Return alias path to first referenced node

[node:audience:first:manager]

Return the manager's user name of the first audience group (organic group related)

[node:field-nref:n(2):title]

Second referenced ndoe title... is this already implemented? Can parenthesis be used on tokens?

Ideally, we could have some sort of string/render fallback by default, but be able to treat arrays of values with a known corresponding token type definition. To handle this, we would need to add a "subtype" key to the tokens structure returned by hook_token_info, and get it on array type generate_token call.
If we had this, everything else would be a matter of ripping the array function (first,last,join,nth,etc.) off the token, mapping the array using the remaining token expression using the given subtype as token_generate's type, and applying the array function to the resulting list.

In the end, all that matters would be offering some token definitions for other modules like:

An idea to work around the array problem might be by creating additional token types on the fly, or maybe using hook_token_info_alter itself to allow "array-of-subtype" declarations, which seems like a neater idea.