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.
Series 5: Sulu for developers Chapter 6 of 16
Snippets and snippet areas
In short
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>:
<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.
{% set heroArea = sulu_snippet_load_by_area('hero') %}
{% set snippet_hero = heroArea.content|default %}
{% set snippet_hero_id = heroArea.view.id|default(null) %}
A snippet in the area that is not yet published does not appear on the website. The banner of the example website then falls back to the default banner. The same applies in the admin preview.
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.
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:
<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.
php bin/adminconsole app:snippets:copy-areas --to=infinity --dry-run
php bin/adminconsole app:snippets:copy-areas --to=infinity