attr API Parameter

With the attr parameter, you would set one or more different attributes that you want to filter the API response by. 

The attr parameter accepts two or more arguments. The first argument is always the layout key for the attribute.  The second parameter is the value to match.

For example, to filter a blog post filter API by a specific post id you could do the following:

{{ _api.blog.posts.template('template-name').attr('id', 3) }}

Passing multiple values for an attribute

Below are different examples of passing multiple values for a single attribute. When multiple values are passed they are treated as OR conditions. Only one value needs to match.

Pass each value as an additional arguments

{{ _api.blog.posts.template('template-name').attr('id', 2, 4, 10) }}

{{ _api.gallery.items.template('template-name').attr('animal', 'Bird', 'Baboon', 'Elephant') }}

The first argument is the attribute layout key. The remaining arguments would be the attribute values to use for the filter.

Pass the values as an array in the second argument

{{ _api.blog.posts.template('template-name').attr('id', [2, 4, 10]) }}

{{ _api.gallery.items.template('template-name').attr('animal', ['Bird', 'Baboon', 'Elephant']) }}

The first argument is the attribute layout key. The second argument is the array of attribute values to use for the filter.

You can save the attribute values in another variable and pass that variable in the API call.

{% set animals = ['Bird', 'Baboon', 'Elephant'] %}
{{ _api.gallery.items.template('template-name').attr('animal', animals) }}

You could pass a variable that holds the attribute value to any of the methods listed on this page.

Pass the values as a string with || separating the values

|| stands for OR. It is another way of telling the system to match any of the values.

While it's easier to read if there is a space before and after || the spaces are not required.

{{ _api.gallery.items.template('template-name').attr('animal', 'Bird || Baboon || Elephant') }}

Pass the values as a string with && separating the values

&& stands for AND. It is another way of telling the system to match all of the values. The only situations where this would be used is if the attribute is a Multi-Select or Multiple Checkboxes field where multiple values can be assigned.

While it's easier to read if there is a space before and after && the spaces are not required.

{{ _api.gallery.items.template('template-name').attr('colors', 'blue && red && yellow') }}

Pass the values as a string with && and || separating the values

You can mix && and || for attribute values. The only situations where this would be used is if the attribute is a Multi-Select or Multiple Checkboxes field where multiple values can be assigned.

For example, to match gallery items that have "blue" OR "red" and "yellow" as values you could do the following.

{{ _api.gallery.items.template('template-name').attr('colors', 'blue || red && yellow') }}

Pass the values as a comma separated string

This only works with the id attribute.

{{ _api.blog.posts.template('template-name').attr('id', '2, 4, 10') }}

ID attribute values

The id attribute is a little special. It should always be set in one of the following formats.

Single value

{{ _api.blog.posts.template('template-name').attr('id', 46) }}

Pass each value as an additional parameter after the layout key

{{ _api.blog.posts.template('template-name').attr('id', 2, 4, 10) }}

Pass the values as a comma separated string

{{ _api.blog.posts.template('template-name').attr('id', '2, 4, 10') }}

Separating values by || or && will not work for the id attribute.

Multiple attributes

If you use multiple attributes in the filter then they are all used to filter the results. All of the passed attributes must be matched.

For example, say that your gallery items had an attribute called "Animal" with a layout key of "animal", and an attribute called "Mountain" with a layout key of "mountain". To match all gallery items that have "Bear" as the Animal attribute value and "Denali" as the Mountain attribute value the API call could be as follows:

{{ _api.gallery.items.template('template-name').attr('animal', 'Bear').attr('mountain', 'Denali') }}

This will not match items that have "Bear" but do not have "Denali".

You can also pass a hash of attribute values to a single attr parameter. The following would produce the same results as the above API call.

{{ _api.gallery.items.template('template-name').attr({'animal': 'Bear', 'mountain': 'Denali'}) }}

While it's not recommended for consistency sake, you can make have multiple attr parameters with hash values.

{{ _api.gallery.items.template('template-name').attr('animal', 'Bear').attr({'mountain': 'Denali', 'color': 'blue'}).attr({'photographer': 'Bob'}) }}

The following would be better

{{ _api.gallery.items.template('template-name').attr({'animal': 'Bear', 'mountain': 'Denali', 'color': 'blue', 'photographer': 'Bob'}) }}

Note, though, that if multiple attr parameters have the same attribute layout key, the last one will overwrite the others.