Custom Metadata Tags

While the metadata manager provides numerous builder methods, they do not cover all possible metadata tags. The metadata manager allows us to queue, or add, additional metadata relatively easily.

#Adding Custom Metadata

The most common place to queue custom metadata is within the site's app/Providers/AppServiceProvider.php file using the Metadata facade. To add a new <meta ...> tag, we can use the queue method and supply an array containing the attributes we want to render:

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Support\ServiceProvider;
 6use Stillat\StatamicSiteEssentials\Support\Facades\Metadata;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    public function boot()
11    {
12        // ...
13 
14        Metadata::queue([
15            'robots' => 'index,follow',
16        ]);
17    }
18}

Likewise, to add a custom <link... > tag we can use the queueLink method:

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Support\ServiceProvider;
 6use Stillat\StatamicSiteEssentials\Support\Facades\Metadata;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    public function boot()
11    {
12        // ...
13 
14        Metadata::queueLink([
15            'rel' => 'icon',
16            'href' => url('/favicon.ico'),
17        ]);
18    }
19}

You may notice that we often refer to this action as queueing links or meta tags instead of simply "adding" them. This is because the metadata manager will work to eliminate duplicate tags before rendering the final output.

#Temporary/Ephemeral Links

There are some scenarios where it is beneficial to add link/metadata tags from tags or some other application code. When doing so, it is very important to note that any queued link/metadata tags will persist across requests when serving multiple requests from a single process, such as when using Statamic' static site generator. If we were to use the default queue and queueLink tags, our custom metadata tags would be continuously added to the metadata manager and likely cause unexpected results.

To help with these scenarios, the metadata manager supports the concept of temporary or ephemeral metadata. This metadata will only persist for the current request, even when using the static site generator. A common example of ephemeral data is when using the se_meta:paginate tag.

To queue custom, ephemeral, metadata, we can use the ephemeral method. When using this method, we will receive access to a metadata builder object as the first argument, allowing us to queue our custom metadata.

As an example, we can look at how the se_meta:paginate tag is implemented:

 1<?php
 2 
 3namespace Stillat\StatamicSiteEssentials\Tags\Metadata;
 4 
 5use Statamic\Tags\Tags;
 6use Stillat\StatamicSiteEssentials\Metadata\MetaBuilder;
 7use Stillat\StatamicSiteEssentials\Support\Facades\Metadata;
 8 
 9class SeMeta extends Tags
10{
11    // ...
12 
13    public function paginate(): void
14    {
15        $paginate = $this->context->get('paginate', null);
16 
17        if (! is_array($paginate)) {
18            return;
19        }
20 
21        Metadata::ephemeral(function (MetaBuilder $meta) use ($paginate) {
22            $meta->general()->pagination($paginate);
23        });
24    }
25}

We may also call the regular queue and queueLink methods when using ephemeral metadata:

 1<?php
 2 
 3namespace App\Tags;
 4 
 5use Statamic\Tags\Tags;
 6use Stillat\StatamicSiteEssentials\Metadata\MetaBuilder;
 7use Stillat\StatamicSiteEssentials\Support\Facades\Metadata;
 8 
 9class CustomTag extends Tags
10{
11    // ...
12 
13    public function index()
14    {
15        Metadata::ephemeral(function (MetaBuilder $meta) use ($paginate) {
16            $meta->queue([
17                'robots' => 'index,follow',
18            ]);
19 
20            $meta->queueLink([
21                'rel' => 'icon',
22                'href' => url('/favicon.ico'),
23            ]);
24        });
25    }
26}

#Adding Custom Metadata from Templates

We can easily add custom metadata from our front-end templates using the se_meta:append tag. For example, on a search page we might add the following:

1{{ se_meta:append }}
2    <meta name="robots" content="noindex">
3{{ /se_meta:append }}

The metadata manager will process all metadata provided by the se_meta:append tag to help prevent duplicates like normal. Metadata tags supplied by the append tag will override conflicting metadata from other sources.

The append tag may be called multiple times, and is safe to use with Statamic's static site generator.