Statamic Tags¶

When you are making a custom component for the pre-rendering system, you might need some data from Statamic.

Since Statamic is running headless, you don't have the existing Statamic tooling available, our alternative for this is Statamic tags. They should make it easy to fetch data from Statamic, without having to think about how know how it talks to Statamic.

Where can Statamic tags be found?¶

The Statamic tags are stored in app/Services/Statamic/Tags and implement the ITag interface.

Statamic tags will be moved soon

As we are soon going to switch to the packaged variant of the pre-rendering system, the location and namespace of the tags will change. Functionally they will stay the same.

New namespace: Flooris\PrerenderedSectionsStatamicIntegration\Tags

New path: packages/flooris/prerendered-sections-statamic-integration/src/Tags

Which tags currently exist?¶

This list is a best-effort

While we try to keep this list up to date with the actual source code, it might be possible for this to become slightly outdated at some point.

The most up-to-date list can be found by checking the tags directory, as seen at Where can Statamic tags be found?.

GlideTag¶

Tag for fetching images and manipulating images.

// Simply fetch the asset as-is
GlideTag::instance()
    ->resolve('asset::main::cms-paginas/kitten-gezond.jpg')
    ->getUrl(); // Returns the URL to the image

// Modify the image
GlideTag::instance()
    ->resolve('asset::main::cms-paginas/kitten-gezond.jpg')
    ->fit(GlideFitmentEnum::CONTAIN) // Changes how it's resized, contain or fit for example
    ->height(300) // Changes the height of the image
    ->width(300) // Changes the width of the image
    ->format(GlideImageFormatEnum::WEBP) // Changes the output format of the image
    ->quality(80) // Sets the quality percentage of the image
    ->getUrl(); // Returns the URL to the modified image

GlobalSetTag¶

Tag for fetching global sets and their values.

// Fetch an entire global set by its handle
GlobalSetTag::instance()
    ->get('header_usps'); // Returns the entire global set as an array, or null if it doesn't exist

// Fetch a single value from a global set
GlobalSetTag::instance()
    ->get('header_usps', 'usps'); // Returns the value of the field, or null if it doesn't exist

// Fetch all global sets
GlobalSetTag::instance()
    ->all(); // Returns all global sets, keyed by their handle

LinkTag¶

Tag for turning links from Statamic (URIs, entry IDs, category IDs etc.) into URLs.

// Let the tag figure out what kind of link it is (URI, entry ID or asset ID)
LinkTag::instance()
    ->attemptAutomaticParse($attrs['link'] ?? null) ?? '#'; // Returns the URL, or null if it can't be resolved

// Resolve a specific kind of link
LinkTag::instance()
    ->getUrlByUri('/winkelwagen'); // Full URLs, relative URLs, tel:, mailto: and # anchors
LinkTag::instance()
    ->getUrlByEntryId('statamic://entry::e3b0c442-98fc-1c14-9afb-f4c8996fb924'); // Statamic entry ID, prefixes are optional
LinkTag::instance()
    ->getUrlByCategoryId(123); // PrestaShop category ID
LinkTag::instance()
    ->getUrlByProductId(456); // PrestaShop product ID
LinkTag::instance()
    ->getUrlByLinkRewrite('kattenvoer'); // Link rewrite (URI slug) of a category or product

// Check whether a category has subcategories
LinkTag::instance()
    ->categoryHasChildren(123); // Returns true or false

Asset links are not supported

Asset IDs (asset::...) are recognized, but not resolved. They will always return #asset-url-unsupported.

Use the GlideTag if you need the URL of an image, as this is a better alternative.

PlaceholderTag¶

Tag for replacing placeholders like {some_placeholder} in a (string based) text with the values from the text_placeholders global set.

PlaceholderTag::instance()
    ->replacePlaceholders('Order for more than {SHIP_BARRIER} at {SHOP_NAME} and profit from free shipping!'); // Returns the text with all known placeholders replaced, returns "Order for more than 35,- at Brekz and profit from free shipping!"

Unknown placeholders are left untouched

Placeholder keys are matched case-insensitively and may only contain letters and underscores.

If a placeholder doesn't exist in the text_placeholders global set, it stays in the text as-is.

Only accepts strings

This function only accepts strings, no other structure!

You can't just feed it like a bard structure and expect it to resolve it, that is outside the scope of this tag.

If you need to render a bard structure, you can use @load_component and then ask for the bard component. This will render the bard structure for you, and also automatically calls the PlaceholderTag for you if it sees text.