Skip to main content
This page describes how the shop templates must be adapted when Strapi components or content are changed or new. This documentation is aimed primarily at template managers and assumes knowledge of HTML, CSS, JSON, and the WEBSALE template engine.

​
Accessing the shop templates

Strapi defines structure and content (content types, components, fields). The shop templates define how this content is displayed in the shop. When something changes in Strapi (new component, new field, field renamed), the corresponding shop template must be adapted, since otherwise nothing, only part, or the wrong thing is displayed in the shop. To be able to adapt templates, you need access to the corresponding shop template repository in GitLab. You can find more information here. There are usually two use cases for adapting templates:
  • Modifying existing components (field added/renamed/removed)
  • Adding new components (component did not exist in the template before)

​
An existing component has been changed

An existing Strapi component is considered changed when, for example, a field has been added, renamed, or removed. For the change to be visible in the shop, the rendering in the corresponding template must be extended or adapted.

​
Determine the template

We recommend a pragmatic approach using the search in GitLab to determine the template in which the adjustment must be made. For example, search for:
  • Component name (for example slider, imageLink, promoBanner)
  • Field name (for example autoplayDelay, linkUrl, headline)
  • Component identifier from the JSON data, if available (often for example __component or a type/slug specification)
The hits will usually lead you to a file in which the component is rendered (partial/component template), included (view template), or assigned (mapping/dispatcher). Then open the file in your editor to continue with the adjustment.

​
Determine the JSON file

So that you can later specifically load or download the component, you must identify the specific JSON file in which the component data is stored. Since the component is already in use in the shop, the corresponding JSON file is usually already loaded somewhere in the template. Recommended procedure:
  • Via the template (fastest way): Search in the relevant template for places where data is loaded – typically via $wsExternalData.load(...) (a file) or $wsExternalData.read(...) (directory). The path used there indicates which JSON file(s) are used in the rendering.
  • Via S3/object storage: Download the file(s) from the relevant directory and search them for the component identifier (for example content.imageLink or __component). This way you can find out in which file the component is actually contained.

​
Publishing in test mode

If content from Strapi should initially only be visible in test mode, the JSON can be placed in a separate subfolder (for example /test). In the template, the path to the JSON file is then switched depending on the test mode. Example:
The JSON file is additionally placed in a /test subfolder for test content. When test mode is active ($wsTestMode.active), the template automatically loads the test JSON from this subfolder. This way, adjustments in the template or new / adapted Strapi components can be tested without affecting the live output. 
{{ var $cCMSLoadOptions = {"source": "system", "type": "json", "maxDepth": 20} }}
{{ var $cCMSFile = ["json/Deutsch/ws_start.json"] | join }}

{{ if $wsTestMode.active }}
  {{ $cCMSFile = ["json/Deutsch/test/ws_start.json"] | join }}
{{ /if }}

{{ var $cCMSData = $wsExternalData.load($cCMSFile, $cCMSLoadOptions) }}

​
Check the JSON

Before you change the template code, you should check how the component is actually delivered as data. This helps in particular to avoid typos and incorrect assumptions about field names. Depending on the setup, there are two common ways:
  • Output/debug in the template, for example at the place where the data is processed via $wsExternalData.load(...).
  • Download from the object/file storage (for example S3), provided that the generated files are stored there and you have access.
The goal is to clearly determine the component name and the field names before you extend the rendering in the template. Further information:

​
Example: component “Image with link” gets a new field

In Strapi, a component named imageLink exists. This component initially has the fields image and linkUrl. Data transfer JSON before the component change 
{
  "__component": "content.imageLink",
  "image": { "url": "/media/banner.jpg", "alt": "Banner" },
  "linkUrl": "https://example.tld"
}
In the template, the component is rendered accordingly by outputting the image and link: Template output before the component change 
{{ var $myVariable = $wsExternalData.load(["my-component.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}

<a href="{{ $myVariable.linkUrl }}">
  <img src="{{ $myVariable.image.url }}" alt="$myVariable.image.alt">
</a>
Now the Strapi imageLink component is extended with another input field, for example text. As a result, the data structure additionally contains the new value: Data transfer JSON after the component change 
{
  "__component": "content.imageLink",
  "image": { "url": "/media/banner.jpg", "alt": "Banner" },
  "linkUrl": "https://example.tld",
  "text": "Discover now"
}
For the text to be displayed in the shop, the template must be extended to output this field: Template output after the component change 
{{ var $myVariable = $wsExternalData.load(["my-component.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}

<a href="{{ $myVariable.linkUrl }}">
  <img src="{{ $myVariable.image.url }}" alt="$myVariable.image.alt">
  <span>{{ $myVariable.text }}</span>
</a>
If content already exists that was saved without the new field, the template should be adapted so that the content and the field are only output when present. This way, you avoid older content unexpectedly causing problems during rendering. If you do not want to integrate the change directly in the live view, first make the change in test mode.

​
A new component has been created

​
Choose a template or create a template

When a new component has been created in Strapi, there are two typical target scenarios:
  • The new component should be displayed on an existing page
    Open the template of this page and select the place where content/components are rendered (for example the area where content blocks are output).
  • The new component should be displayed on a new page
    Create a new view template and implement the loading and rendering of the data there.

​
Determine the JSON file

To output the contents of the component in the template, you must load the JSON file in which the component data is stored. For this, the file name must be known. Recommended ways to determine the file name:
  • Via $wsExternalData.read(...):
    If the theme reads in a directory via read, a file list can be output via this. This way, the relevant file name can be found and then specifically loaded via load.
  • Via S3/object storage:
    If you have access to S3, the relevant directory can be opened and the file(s) identified by name/structure or by searching for the component identifier (for example __component).

​
Check the JSON data

Before the rendering is implemented, the JSON should be checked so that the following are clear:
  • what the component is called (for example content.promoBanner)
  • which fields are delivered (for example image, linkUrl, text)
  • what nested structures look like (for example image object, lists)
This prevents typos and incorrect assumptions in the template.

​
Example: integrate a new component

You have identified the JSON file that contains the data of your new component (for example my-new-component.json) and already looked at the structure: Data transfer JSON before the component change 
{
  "__component": "content.promoBanner",
  "image": { "url": "/media/banner.jpg", "alt": "Banner" },
  "linkUrl": "https://example.tld"
}
To be able to access the data from my-new-component.json, you must first load the file: 
{{ var $myVariable = $wsExternalData.load(["my-new-component.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}
At the place in the template where the data should be displayed, you output the content (simplified): 
<a href="{{ $myVariable.linkUrl }}">
  <img src="{{ $myVariable.image.url }}" alt="{{ $myVariable.image.alt }}">
</a>
If you do not want to integrate the output directly in the live view, first make the change in test mode.

​
Define image formats

If the layout is to be strictly maintained, images should be specifically cropped and optimized to the desired dimensions in an image editing program (for example Photoshop) before being uploaded to Strapi. The image converter in the shop’s Admin Interface (under Templates & Content → Image converter) then ensures that the image is compressed and optimized. For compression and optimization in the image converter, corresponding profiles can be created under Image converter → Image formats so that the images are processed according to the individual wishes of the user. To ensure that an image is also displayed correctly when the optimization does not deliver the desired result, you can set up a fallback via fixed specifications in the template code. For adjustments to the source code, we refer here to GitLab.

​
Further information