Snippets and snippet areas

Development
Applies to: every Sulu website As of Sulu 3.0

In short

Snippets belong to no webspace. A template defines areas with <areas>, the admin assigns them per webspace, and Twig reads them with sulu_snippet_load_by_area and only sees the published version. In the example website the project's own function webspace_config() merges the settings of the tabs.

Snippets are content that you maintain once and use in many places. The example website stores its organization data, the settings of the website, the banner and the profiles for formats, effects, collections and contacts this way. This chapter shows how that fits together technically.

Helpful first: 5.3 Page templates: XML and Twig

Templates

A snippet template lives in config/templates/snippets/ and is built like a page template. The example website has nine: collection, config, contact, effects, format, hero, link, organisation and social-media. Snippets belong to no webspace; every website of the project can use them.

Areas

An area (area) is a named place that a webspace fills with a snippet. The template defines it with the element <areas>:

From config/templates/snippets/config.xml html
<key>config</key>
<meta>
    <title lang="en">Configuration: Webspace</title>
    <title lang="de">Konfiguration: Webspace</title>
</meta>
<areas>
    <area key="config">
        <meta>
            <title lang="en">Configuration: Webspace</title>
            <title lang="de">Konfiguration: Webspace</title>
        </meta>
    </area>
</areas>

In the admin, editors decide which snippet a webspace uses in which area. This is stored in a row with the webspace key (webspaceKey), the area key (areaKey) and the snippet. Two consequences:

  • If no template has an area, the tab for the areas disappears from the admin altogether.
  • The permissions for it hang on the webspace: sulu.webspaces.<webspace>.snippet-areas.

Loading in Twig

With sulu_snippet_load_by_area(areaKey, properties, webspaceKey, locale) you fetch the snippet that the current webspace has in the area. The last three parameters are optional and default to the current webspace and the current language. The function returns null if the area is empty or the snippet does not exist in the language. It only reads the published version (STAGE_LIVE). A snippet that exists only as a draft therefore drops out.

From templates/layouts/page.html.twig, shortened html
{% set heroArea = sulu_snippet_load_by_area('hero') %}
{% set snippet_hero = heroArea.content|default %}
{% set snippet_hero_id = heroArea.view.id|default(null) %}

Settings with tabs

The configuration snippet of the example website has several tabs. They come from the SnippetTabsBundle and are defined in config/packages/sulu_snippet_tabs.yaml. The first tab is the template itself. The bundle writes the fields of the other tabs into the same data, but they are read under extension.tabs. Anyone who only reads content loses the fields of the tabs without any error. That is why webspace_config() exists: the function loads the snippet once per request and merges both parts.

From src/Twig/WebspaceConfigTwigExtension.php php
public static function merge(?array $snippet): array
{
    if (null === $snippet) {
        return [];
    }

    $content = $snippet['content'] ?? null;
    $tabs = $snippet['extension']['tabs'] ?? null;

    return array_merge(
        \is_array($content) ? $content : [],
        \is_array($tabs) ? $tabs : [],
    );
}

In Twig you then write {% set webspaceConfig = webspace_config() %}. The example website never reads the settings directly with sulu_snippet_load_by_area('config').

Choosing snippets in fields

In a template, editors choose a snippet with single_snippet_selection (one) or snippet_selection (several). The parameter templateKeys limits the choice to templates. Since Sulu 3.0.8 it is called that; before, it was called types. This is how the collection profile is chosen in a block:

From config/templates/includes/groups/config/collection-source.xml, shortened html
<property name="snippet_collection_profile" type="single_snippet_selection" colspan="4">
    <meta>
        <title lang="en">Collection profile</title>
        <title lang="de">Sammlungsprofil</title>
    </meta>
    <params>
        <param name="templateKeys" value="collection"/>
    </params>
</property>

A new webspace

A new webspace initially has no areas filled, and pages that expect a snippet stumble over empty values. The example website ships a command for this. It assigns the target webspace the same snippets as the source webspace, just as the admin does when you assign them. An area that is already filled stays, unless you pass --force.

Copy the areas of one webspace to another bash
php bin/adminconsole app:snippets:copy-areas --to=infinity --dry-run
php bin/adminconsole app:snippets:copy-areas --to=infinity

More on this

Official documentation