HTML Objects

HTML Objects allow you to access the attributes for HTML tags and manipulate the values of that attribute before outputting the tag.

There are two different types of HTML objects:

An object containing data for the entire HTML tag
An object containing the value for an individual attribute within the HTML tag.

HTML objects are available for the following types of HTML tags within your templates:

Example

An example scenario could be that you need to set that alt text for an image before displaying it. Previously you would need to manually build the image tag to set the alt text.

Now you can set the alt text and then simply output the code. In most cases, this results is less code and more readable code.

{% set image.alt = 'My Alt Text' %} {{ image.tag }}

Getting attribute values

You can access the attribute value just like you would with any other variable. For example, to get the src attribute value for an image you could use:

If, however, you wanted to get the full attribute then you can do the following:

<img{{ image.src.attr }}>

You can apply filters to attribute values like regular variables and use them in expressions like set or if.

{% set currentClass = image.class %}

{% if field.fieldType == 'text' %}
{% endif %}

Doing math with attribute values

If you are going to do any math with values the syntax is slightly different. The reason is that the value is often returned as an object and that doesn't always get converted to a number to do math with. To enforce that use the get() method.

Example:

WRONG: {% set ratio = image.width / image.height %}

Ratio won't be a correct value. Use get() to get the correct value.

RIGHT: {% set ratio = image.width.get() / image.height.get() %}

Set attribute values

You can set attribute values before outputting the tag. You can set existing attribute values or new valid HTML attribute values. There are a few ways to set an attribute value on an HTML object.

Use the normal 'set' tag

{% set image.class = 'className' %}

Use the HTML value object set method

{% do image.class.set('className') %}

Use the HTML object set method

If your attribute name has a dash in it (like a "data" attribute) then you would need to use the HTML object set method to prepend the value. This is because the dash would create a syntax error in Twig.

The syntax for the set method is:

{% do field.set('attribute-name', 'attribute-value') %}

Here is an example to set a value for a custom data attribute.

{% do field.set('data-custom', 'anotherValue') %}

Setting multiple values at one

You can pass an object to the set() method to set multiple values at once.

{% do image.set({
   alt: 'Image alt text',
   class: 'MyClass',
   id: 'imageId'
}) %}

Set data attributes

Data attributes allow you to create custom attributes to store extra information on an HTML tag in a semantic way. These custom attributes have no visual representation, but they can be used by Javascript when working with the DOM.

There are three ways that you can set data attributes. In this example we're going to set the data attributes for the image tag above.

1. Set it as an array

Each key is the part of the attribute name that comes after "data-". The value is the attribute value.

{% set image.data = {'type': 'jpg', 'source': 'user'} %}

2. Set them individually

{% set image.data.type = 'jpg' %}
{% set image.data.source = 'user' %}

If your attribute name contains any dashes in it then you should use method 1 or 3 to set the attribute.

3. Use the HTML object set method

{% do image.set('data-type', 'jpg') %}
{% do image.set('data-source', 'user') %}

You can use any combination of the methods above.

{% set image.data = {'type': 'jpg', 'source': 'user'} %}
{% set image.data.tag = 'animal' %}
{# override the source attribute #}
{% set image.data.source = 'me' %}

{% image.set('data-animal', 'tiger') %}

The above will end up with an image tag like this:

Set boolean attribute values

Certain attributes like "checked", "disabled" or "required" are boolean attributes where their existence represents a true value and their absence represents a false value. If set correctly then when the HTML tag is built then just the attribute name is outputted.

To set a boolean attribute simply set it's value to "true".

{% set field.required = true %}

This would output something like this:

Setting a boolean attribute to false will cause it to not be included in the attributes for the tag. Unless the attribute was previously set to "true" then there is no need to set it to false since by default boolean attributes aren't included. The exception would be form fields that are a required field. In those cases the "required" attribute is set to "true".

Remove attribute values

You can remove an attribute value by using the HTML object remove method.

{% do field.remove('data-custom') %}

Append attribute values

You can also append attribute values to the existing attribute value. This can be done even if there isn't an already existing value. When in doubt it's better to append a value then to set it to avoid overwriting an existing attribute value (unless you have reason to overwrite the value).

There are a few ways to append a value.

We will use the 'class' attribute for a form field tag as an example.

Use the concatenate operator with the 'set' tag

{% set field.class = field.class ~ ' anotherClass' %}

Use the HTML value object append method

{% do field.class.append('anotherClass') %}

Use the HTML object append method

If your attribute name has a dash in it (like a "data" attribute) then you would need to use the HTML object append method to append the value. This is because the dash would create a syntax error in Twig.

The syntax for the append method is:

{% do field.append('attribute-name', 'attribute-value') %}

Here is an example of appending a value to a custom data attribute.

{% do field.append('data-custom', 'anotherValue') %}

Prepend attribute values

You can also prepend attribute values to the existing attribute value. This can be done even if there isn't an already existing value.

There are a few ways to prepend a value.

We will use the 'class' attribute for a form field tag as an example.

Use the concatenate operator

{% set field.class = 'anotherClass ' ~ field.class %}

Use the HTML value object prepend method

{% do field.class.prepend('anotherClass') %}

Use the HTML object prepend method

If your attribute name has a dash in it (like a "data" attribute) then you would need to use the HTML object prepend method to prepend the value. This is because the dash would create a syntax error in Twig.

The syntax for the prepend method is:

{% do field.prepend('attribute-name', 'attribute-value') %}

Here is an example to prepend a value to a custom data attribute.

{% do field.prepend('data-custom', 'anotherValue') %}

Set a default value if the attribute doesn't have a value

Sometimes you need to set the value for an attribute if it doesn't already have one. This is pretty common with images and the alt attribute. You can set the alt attribute within the administration, but sometimes it's not set. If that's the case then you may want to set a default value.

There are a few ways to do this. We are going to use the image alt attribute in our examples, but you can do this with any HTML object attribute.

Test for the value with an "if" statement

{% if image.alt|length == 0 %}
    {% set image.alt = 'My Default Alt Text' %}
{% endif %}

Use a ternary operator to test for the value

The ternary operator is a shortened version of the "if" statement. Typically it follows an if/else format, but there is an abbreviated version with ?: that will use the tested value if it exists or the value you specify.

{% set image.alt = image.alt ?: 'My Default alt text' %}

{# The above is the same as: #}

{% set image.alt = image.alt ? image.alt : 'My Default alt text' %}

Use the default method on the attribute

Just like you can use the prepend() or append() methods on an attribute, you can use the default() method to set a value.

The default() method will set the passed value on the attribute if the attribute doesn't already have a value.

{% do image.alt.default('My default alt value') %}

Use the default() method on the object

This is similar to using the default() method on the object, but in this case, we have to pass the name of the attribute we are setting.

{% do image.default('alt', 'My default alt value') %}