Guide

Site Text Template Usage

This article is targeted at Digital Agencies and those making changes to the HTML of front-end pages.

The article will discuss how Site Text can be implemented from a technical perspective.

Suggest Edits

Site Text Overview

The Site Text feature is designed to return requested "Site Text" content for a given "Page" and "Part" - along with an optional "Language ID". Functionality is provided by way of a smarty function named "site_text". It can be called with several additional attributes, all of which are listed below:

  • page (required)
    Name of the page (category) of the piece of Site Text.
  • part (required)Name of the part of the piece of Site Text.
  • type (optional)Name of the HTML attribute for which content should be returned.
  • manageable (optional, defaulted to true)Optional manageable flag which states if returned content should be manageable or not.
    If content shouldn't be manageable, 0 should be passed as the value for this attribute.

❗️

In situations where the {site_text} function is called without a manageable attribute, or with the manageable attribute value equal to '1', the function will return additional content.

We don't recommend the use of manageable Site Text in the <head> section of HTML or in JavaScript. Such usage may cause errors.
  • default (optional)
    An attribute which can be used when content does not currently exist in the database.
    If the "default" attribute is not provided, and content does not currently exist in the database, the part after ": " from "part" attribute is used as default.
  • language_id (optional)
    An attribute which can force content to be shown in the provided language.
    Array, where value under key "0" should contain language id.
    If not provided, function will use the detected language.
  • any attribute with "var_" prefix
    These attributes can be used to pass additional information needed for rendering content.

❗️

Names must be valid smarty attribute names.

Examples of Site Text in Use

Simple usage based on only "page" and "part" attributes:

{site_text page="Homepage" part="Title: Latest Products"}

Usage with additional language_id attribute:

{site_text page="Homepage" part="Title: Latest Products" language_id=$language_array}

🚧

$language_array should be an array with "language id" under "0" key.

Usage as an HTML attribute:

<a href="#" {site_text page="Homepage" part="Title: Latest Products" type="title"}> ABC </a>

Usage where content should not be manageable:

{site_text page="Homepage" part="Meta: Title" manageable=0}

Usage with a default value:

{site_text page="Homepage" part="Meta: Title" default="Default Title"}

Usage with custom attributes:

{site_text page="Basket" part="Warning: Insufficient Stock" var_product=$error.product var_stock=$error.stock var_desired=$error.desired}

📘

User custom attributes that begin with "var_" are used to replace patterns inside content.

For example, if we assume the content for the above "page" and "part" was set as: "%(product)s only has %(stock)s available. You tried to add %(desired)s".

In this situation, the function would process all user custom attributes, and replace "%(xxxxx)s" patterns - where "xxxxx" matches the custom attribute name truncated by the "var_" prefix.

So, in our example, the "var_product" attribute affects the "%(product)s" pattern and replaces it with its value.

If we assume that the smarty variable values are set as follows: $error.product = "Product 1", $error.stock = 2, $error.desired = 5, the above {site_text} call would return: "Product 1 only has 2 available. You tried to add 5".

Changes to Previous Versions of Site Text:

  • The "manageable" attribute has now become optional (though every piece of Site Text is set as manageable by default).
  • HTML attributes can be managed with the "type" attribute.
  • {sprintf} blocks can be replaced by new syntax. Example below:

Previously, to use additional values inside content, the below syntax was used:

{sprintf var1=$error.product var2=$error.stock var3=$error.desired}{site_text page="Basket" part="Warning: Insufficient Stock" manageable=1}{/sprintf}

New syntax going forward:

{site_text page="Basket" part="Warning: Insufficient Stock" var_product=$error.product var_stock=$error.stock var_desired=$error.desired}

❗️

Database Site Text values must be altered at the same time as template changes, in case of {sprintf} block removal.

Updated over 2 years ago