Documentation for webmasters

This guide covers basic changes to SOTESHOP 8 themes: editing CSS, modifying HTML templates and adding content that can be edited in the administration panel. You will need a basic knowledge of HTML and CSS, a text editor and access to the store files.

Before editing files, check the options available under Theme editing in the administration panel. You can change the logo, colours, text and many layout settings without editing templates. The available options depend on the selected theme.

Custom themes and inheritance

Create a custom theme based on your chosen theme. In the examples, its name is mytheme. Replace this with the directory name of your own theme. Back up the files before editing them; test larger changes on a test copy of the store first.

The base theme for SOTESHOP 8 is bianco. It inherits some templates from responsive, which contains the complete set of templates. Individual themes may inherit through several parent themes, for example:

mytheme → argento8 → bianco → responsive

When looking for a file to modify, check your own theme first, followed by each of its parent themes in order. Copy the first version you find to the corresponding directory in your own theme. Do not skip the other parents and go straight to responsive.

• HTML: your file replaces the entire parent template. Copy only the files you actually modify, and preserve existing conditions, components and slots.
• CSS: styles from parent themes are included automatically. Your stylesheet should contain only the changes you need.
• Images: the image_path function looks for an image in your theme first, then in each parent theme in order.

Do not modify standard theme files or the store’s PHP code when changing the appearance. Your copy of an HTML template also overrides future fixes to the base template, so compare your modified templates with the latest base versions after updates.

Where are the files?

Template paths beginning with /apps/ and /plugins/ are relative to the store’s application directory, which contains the symfony file. These are not URLs to open in a browser.

The /css/, /images/ and /js/ URLs are public asset paths. In the store’s development directory structure, they correspond to web/css/, web/images/ and web/js/. For example, the URL /css/frontend/theme/mytheme/mytheme.css corresponds to the file web/css/frontend/theme/mytheme/mytheme.css.

The files listed in the table do not have to exist in your theme: the store uses their parent versions if they are missing. The home page may combine homepage.html, main_index.html and the components they call. Before changing the HTML, check the home page layout and section settings in the administration panel.

Example 1: a simple CSS change

1. When you create a custom theme in the administration panel, the system creates its stylesheet. Open the file corresponding to the URL /css/frontend/theme/mytheme/mytheme.css.

2. To give the buttons in your theme rounded corners, add:

   /* Buttons */
   .btn {
       border-radius: 8px;
   }

3. Save the file and check a page that uses your custom theme. If you cannot see the change, use the troubleshooting checklist.

Check selectors using your browser’s developer tools. SOTESHOP 8 themes use Bootstrap 3. Use classes compatible with the version included in your store.

Example 2: a bar with text editable in the administration panel

We will add an information bar above the header. The store owner will be able to change its text later in the administration panel without editing HTML.

Add custom theme text

1. Open your custom theme in the developer backend: https://adres-sklepu/backend_dev.php/theme/edit/id/ID_TEMATU. Replace the domain with your store’s address and ID_TEMATU with the ID shown in the theme editing URL.
2. Go to Text configuration and select Add. New text entries can be added in the developer backend.

3. Complete the fields:

   • Id: pasek-informacyjny - the identifier used in the template.
   • Name: Information bar - the name displayed in the administration panel.
   • Content: for example, “Contact us: 61 800 00 00”.
4. Save the text. For a multilingual store, enter the content for each language you use.

The text belongs to a specific theme. Add it to the custom theme in which it should appear. Text entries are not automatically retrieved from parent themes. The Id must match in the administration panel and the template, and must be unique within that theme.

Display the text in the header

1. Look for _header.html in each parent theme in order. For example, if it is not present in argento8, check bianco.
2. Copy the file you find to /apps/frontend/templates/theme/mytheme/_header.html. If you already have your own version, edit that file.

3. Add the following before the existing header HTML:

   <div class="theme-info-bar">
       <div class="container">
           {theme_content id='pasek-informacyjny'}
       </div>
   </div>

4. Add the following to your stylesheet at /css/frontend/theme/mytheme/mytheme.css:

   /* Information bar */
   .theme-info-bar {
       padding: 8px 0;
       background: #ececec;
       color: #333;
       text-align: center;
       font-size: 1rem;
   }

5. Check the bar on a computer and a phone. Then change its content in the regular administration panel: Applications → Theme editing → your custom theme → Text configuration.

The developer backend is used here to add the text entry and assign its identifier. Subsequent content changes do not require backend_dev.php.

CSS and images

Add your custom styles to /css/frontend/theme/mytheme/mytheme.css. Do not copy entire parent stylesheets. Files in the _editor directory are generated by the theme configuration; change the appearance through the administration panel or your theme’s stylesheet.

Place theme images in the directory corresponding to the URL /images/frontend/theme/mytheme/, for example phone.png. Use the following in the template:

<img src="{image_path image='phone.png'}" width="14" height="14" alt="" />

The function supports inheritance. Adding an image with the same name to your theme overrides the parent image. An icon accompanying text can have an empty alt attribute; an image that conveys information should have a description.

Useful template constructs

Including a file and calling a component

{include_file id="_footer"}

Includes _footer.html with support for theme inheritance. A component retrieves data and displays it using its own template, for example:

{st_get_component module="stProduct" component="productGroup" product_group="MAIN_PAGE"}

Displays the product group with the symbol MAIN_PAGE. The group must be created and populated with products in the administration panel.

A content box editable in the administration panel

Create an information box in the administration panel and set its webmaster identifier to moj_boks. Add the following at the desired location in the template:

{st_get_component module="stBoxFrontend" component="boxSingle" params="webmaster_id=moj_boks"}

A content box is useful for longer content. Short messages and headings can be created as theme text entries.

Variables and translations

Variables available in the product page template include {$name} - name, {$code} - code, {$description} - short description and {$description_long} - full description. Available variables depend on the view; check their usage in the current base template. Moving a variable to another file does not ensure that its data will be passed to that file.

Preserve existing conditions for displaying prices, availability and product options. Use the translation mechanism for fixed labels in templates, for example {__ text="Szukaj" langCatalogue="stSearchFrontend"}. You can find the langCatalogue value in the administration panel under Language definitions, in the Catalogue column for the relevant phrase. Content that the store owner needs to edit should be managed in the administration panel.

Custom JavaScript and fonts

Include theme scripts in _script_theme.html. If you need to modify it, copy the version from the nearest parent and preserve the existing scripts. Save larger scripts as separate files, for example at the public URL /js/mytheme.js, and add the following to _script_theme.html:

{use_javascript src="mytheme.js"}

The JS directory is shared by the store, so use a unique file name. The _fonts.html file includes fonts and calls _script_theme.html; preserve that call. Host fonts locally, using the store’s existing resources where possible.

Wrap JavaScript or CSS containing braces and embedded in HTML in a {literal}…{/literal} block so that Smarty does not interpret it as template instructions. Keep Smarty calls, such as {theme_content id='pasek-informacyjny'}, outside that block.

How do I add an extra product group type?

Create the file /apps/backend/modules/stProductGroup/config/user_product_group.yml. If it already exists, extend its product_group section, preserving the existing entries. For example:

product_group:
    MY: My group
    SEASON: Seasonal offer

Use spaces for indentation in YAML. These entries make new types available for selection in the administration panel; they do not automatically create groups or add products. Create a group in the administration panel, select its type and assign products. Then call it in the template:

{st_get_component module="stProduct" component="productGroup" product_group="SEASON"}

This configuration file is shared by the store and is not limited to a single theme.

Why can’t I see the change?

1. Theme: check that you are previewing the correct theme or that it is set as the default.
2. Path: check the theme directory and file names. In your browser’s developer tools, make sure the stylesheet or script loads without a 404 error.
3. Inheritance and layout: make sure you are editing the template used by the view. For the home page, also check the selected layout and section configuration.
4. CSS: check that the rule matches the element and is not overridden by another style, an administration panel setting or a rule for a different screen width.
5. Content: check the text or box identifier, the theme and the language. For product groups, check the assigned products and their visibility.
6. Cache: use developer mode while working. After making changes, clear the store cache and FastCache, then reload the page bypassing the browser cache.

When finished, check the modified views on a computer and a phone, including in the store’s normal mode. When changing shared elements, check the home page, product list, product page and shopping cart.

Theme setup guides

• Climb theme
• Watch theme
• Cutlery theme
• Giallo theme
• Argento theme
• Futura theme
• Ristorante theme
• Lazuli theme
• Moda theme
• Marrone theme
• Elegante theme
• Bianco theme