Introduction & Installation

Attribute Renderer is a utility addon for Statamic that helps create HTML attribute strings from arrays.

At a high level, it allows you to convert something like this:

1<?php
2 
3use function Stillat\StatamicAttributeRenderer\attributes;
4 
5attributes([
6    'name' => 'author',
7    'content' => 'John Doe'
8]);

to the following HTML attribute string:

1name="author" content="John Doe"

The attributes renderer is also context aware, and can do things like this:

 1<?php
 2 
 3use function Stillat\StatamicAttributeRenderer\attributes;
 4 
 5attributes([
 6    'name' => 'author',
 7    'content' => '$author'
 8], [
 9    'author' => 'John Doe'
10]);

These examples are basic, and Attribute Renderer supports even more complex scenarios.

#Installation

Attribute Renderer can be installed by running the following command from the root of your project:

1composer require stillat/statamic-attribute-renderer

#Converting Arrays to Attribute Strings

The simplest way to convert a key/value array of attribute details to a string is using the attributes utility function:

1<?php
2 
3use function Stillat\StatamicAttributeRenderer\attributes;
4 
5attributes([
6    'name' => 'author',
7    'content' => 'John Doe'
8]);

which produces the following result:

1name="author" content="John Doe"

#Resolving Variable Values

We can resolve variables from contextual data, which is supplied as the second argument to the attributes function. When specifying variable names, we simply prefix them with the $ symbol:

 1<?php
 2 
 3use function Stillat\StatamicAttributeRenderer\attributes;
 4 
 5attributes([
 6    'name' => 'author',
 7    'content' => '$author'
 8], [
 9    'author' => 'John Doe'
10]);

We can use $$ to escape the beginning of a variable string to emit string beginning with a single $:

 1<?php
 2 
 3use function Stillat\StatamicAttributeRenderer\attributes;
 4 
 5attributes([
 6    'name' => 'author',
 7    'content' => '$author',
 8    'content_two' => '$$author',
 9    'content_three' => '$$$author',
10], [
11    'author' => 'John Doe'
12]);

which produces the following output:

1name="author" content="John Doe" content_two="$author" content_three="$$author"

Attribute Renderer does not support more complicated variable paths, such as nested properties, or array indices. If you need something more complicated, consider using a closure based variable resolver.

#Closure Based Variable Resolvers

We can supply a Closure as the value of our attribute in order to resolve more complicated values. We will receive the context array as the first argument:

 1<?php
 2 
 3use function Stillat\StatamicAttributeRenderer\attributes;
 4 
 5attributes([
 6    'name' => 'author',
 7    'content' => function (array $context) {
 8        return 'Hello, '.$context['author'];
 9    },
10], [
11    'author' => 'John Doe'
12]);

which produces:

1name="author" content="Hello, John Doe"

#Skippable/Ignorable Properties

By default, Attribute Renderer will emit empty strings if a value returns null:

1<?php
2 
3use function Stillat\StatamicAttributeRenderer\attributes;
4 
5attributes([
6    'name' => 'author',
7    'content' => '$name'
8]);

produces:

1name="author" content=""

we can let Attribute Renderer know its okay to ignore a property when producing the final result:

1<?php
2 
3use function Stillat\StatamicAttributeRenderer\attributes;
4use function Stillat\StatamicAttributeRenderer\isIgnorable;
5 
6attributes([
7    'name' => 'author',
8    'content' => isIgnorable('$name')
9]);

would now produce:

1name="author"

However, if the value did exist within the context:

 1<?php
 2 
 3use function Stillat\StatamicAttributeRenderer\attributes;
 4use function Stillat\StatamicAttributeRenderer\isIgnorable;
 5 
 6attributes([
 7    'name' => 'author',
 8    'content' => isIgnorable('$name')
 9], [
10    'name' => 'John Doe'
11]);

the ignorable property is added to the output:

1name="author" content="John Doe"

#Rejectable Properties

Rejectable properties are similar to ignorable properties. However, if a null or empty string value is resolved for one of these values, an empty attribute string is returned, regardless of if other property values were matched:

 1<?php
 2 
 3use function Stillat\StatamicAttributeRenderer\attributes;
 4use function Stillat\StatamicAttributeRenderer\rejectsOnEmpty;
 5 
 6attributes([
 7    'name' => 'author',
 8    'content' => rejectsOnEmpty('$name'),
 9    'first_name' => '$first_name'
10], [
11    'first_name' => 'John Doe'
12]);