Snippets¶

A snippet is a separate part of the template that can be used in multiple templates.

The best examples of snippets are a header and a footer that are included in every email notification. Snippets don’t have their own context and variables; they inherit the context and variables from the template that calls the snippet.

Snippets are available both for email and document templates.

Here’s the example of including a snippet into the template:

{{ snippet("header") }}

And here’s the example of including a snippet with additional variables into the template:

{{ snippet("header", {"title": product.name}) }}

Types of Snippets¶

All snippets are separated into types. This allows to restrict access to snippets for different types of documents. For example, snippets of the mail type are available for all email notifications and unavailable for documents.

Data Structure¶

The cscart_template_snippets table stores the general information about snippets. The table contains the following columns:

Name	Type	Description
snippet_id	id	Auto incremented id
code	varchar(128)	Character code
type	varchar(32)	Type
template	text	Template
default_template	text	Default template
status	char(1)	Status
handler	text	Name of the function that processes a snippet
params	text	Extra parameters
addon	varchar	Identifier of the add-on to which the snippet belongs
updated	int	UNIX timestamp of the update
created	int	UNIX timestamp of creation

The name of the snippet is language-dependent and is stored in a separate table called cscart_template_snippet_descriptions .

Programming Interface¶

The following classes were implemented to manage snippets:

\Tygh\Template\Snippet\Snippet—the model of the snippet. It’s a programming representation of the snippet structure.
\Tygh\Template\Snippet\Repository—the snippet repository. The class implements the low-level methods of receiving/adding/updating/deleting snippets from the database. An instance of the class is available from the Tygh::$app['template.snippet.repository'] container.
\Tygh\Template\Snippet\Service—the service. This class implements higher-level methods of snippet management. An instance of the class is available from the Tygh::$app['template.snippet.service'] container.
\Tygh\Template\Snippet\Exim—this class implements the logic of import and export of snippets. An instance of the class is available from the Tygh::$app['template.snippet.exim'] container.

The Schema of the Snippet Rendering¶

Defining the snippet type from the template.

Each template, that calls a snippet, knows what snippets are available for it. On the software level, a template is a class that implements the ITemplate interface.
Receiving the template snippet by the type and character identifier with the aid of the \Tygh\Template\Snippet\Repository class.
Calling the 'template_snippet_render_pre' pre-hook.
Calling the template engine to render the snippet.
Calling the 'template_snippet_render_post' post-hook.
Returning the result.

Adding Snippets¶

Add-ons can add their own snippets of any type. Snippets are meant to be added during the add-on installation and deleted when the add-on is uninstalled. To add snippets, you may use the methods of the \Tygh\Template\Snippet\Service or describe snippets right in the add-on schema. For example:

<?xml version="1.0"?>
<addon scheme="3.0">
    <id>my_changes</id>
    <snippet_templates>
        <item>
            <type>order_invoice</type>
            <code><![CDATA[some_snippet]]></code>
            <default_template><![CDATA[Content]]></default_template>
            <status><![CDATA[A]]></status>
            <name>
                <en><![CDATA[Order invoice snippet]]></en>
            </name>
            <addon><![CDATA[my_changes]]></addon>
        </item>
    </snippet_templates>
</addon>

Extending Snippets¶

Sometimes you can’t create a template you’d like with the default visual editor. It might be ineffective, or you might want some additional structured data.

For example, to print the list of the products in an order.invoice document you will need a table that can easily be expanded. Obviously, the visual editor is not the best tool in this case. To solve the tasks like this, we added the hooks that can influence the snippet rendering and extend the interface of the editor.

PHP Hooks¶

'template_snippet_render_pre'—it’s executed before snippet rendering. This hook can add necessary variables that can later be used in the snippet template:
```
fn_set_hook('template_snippet_render_pre', $snippet, $context, $variable_collection)
```

'template_snippet_render_post'—it’s executed after snippet rendering:

fn_set_hook('template_snippet_render_post', $snippet, $context, $variable_collection, $result)

'template_snippet_remove_post'—it’s executed after a snippet is deleted:
```
fn_set_hook('template_snippet_remove_post', $this, $snippet)
```
'template_snippet_save_post'—it’s executed after a snippet is saved to the database:
```
fn_set_hook('template_snippet_save_post', $this, $snippet, $lang_code)
```

Template Hooks¶

{hook name="snippets:tabs_extra"}{/hook} (design/backend/templates/views/snippets/update.tpl)—it allows to add new tabs to the snippet editing popup.

Template Engine¶

We use the Twig library (version 1.24) as a template engine. The standard extensions are included:

Twig_Extensions_Extension_Text
Twig_Extensions_Extension_Array
Twig_Extension_Debug — only in development mode.

Here are the additional filters and functions:

date (filter)—formats the value as a date.

If you use the this filter, make sure to specify the date format. For example:

{{ o.raw.timestamp }} will look like 1127988066 (Unix timestamp).
{{ o.raw.timestamp|date("%d/%m/%Y") }} will look like 29/09/2005 (human-readable time).

Starting with version 4.6.3, specifying the date format isn’t required. If you use the filter without the format like {{ o.raw.timestamp|date }}, then the date format selected on the Settings → Appearance page will be used.

Here are the formats available in CS-Cart/Multi-Vendor settings:

Date format	Displayed date	Description
`"%d/%m/%Y"`	29/09/2005	day/month/year
`"%d-%m-%Y"`	29-09-2005	day-month-year
`"%d.%m.%Y"`	29.09.2005	day.month.year
`"%m/%d/%Y"`	09/29/2005	month/day/year
`"%m-%d-%Y"`	09-29-2005	month-day-year
`"%m.%d.%Y"`	09.29.2005	month.day.year
`"%Y/%m/%d"`	2005/09/29	year/month/day
`"%Y-%m-%d"`	2005-09-29	year-month-day
`"%Y.%m.%d"`	2005.09.29	year.month.day
`"%b %e, %Y"`	Sep 29, 2005	month day, year
`"%d %b %Y"`	29 Sep 2005	day month year
`"%A, %B %e, %Y"`	Thursday, September 29, 2005	day of week, month day, year
`"%A, %e %B %Y"`	Thursday, 29 September 2005	day of week, day month year

price (filter)—formats the value as a price. For example, {{ o.raw.total }} will look like 917.99, and {{ o.raw.total|price }} will look like $917.99.

Starting with version 4.6.3, you can use this filter to choose in what currency you’d like to display the price. For example, {{ o.raw.total|price("EUR") }} will display the order total in Euro according to the conversion rate specified in your store. If no currency is specified for the filter, then CART_PRIMARY_CURRENCY will be used.
filesize (filter)—formats the value as a file size in kilobytes. For example, this filter is used in the email template about access to downloadable products: {{ file.file_size|filesize }}.
puny_decode (filter)—decodes the URLs from PunyCode to international format. This filter can be found in email templates that have URLs, for example, in password recovery emails: {{ url|puny_decode }}.
__ (function)—shows translations. For example, {{__("change_order_status_c_text")}} will be displayed in the English version of the document as the English value of the corresponding language variable: Your order has been completed. Thank you for choosing us.
snippet (function)—inserts a snippet. For example, {{ snippet("ship_to") }} in the Invoice document inserts the corresponding snippet from the Code snippets tab into the document.
include_doc (function)—includes documents into the body of email notification. For example, the email notifications about order statuses have the following line: {{ include_doc("order.summary", order_info.order_id) }}.

That line includes the order.summary document (information about the order) into the body of those emails.

Hint

Learn more about the template engine from the official Twig documentation.

Questions & Feedback

Have any questions that weren't answered here? Need help with solving a problem in your online store? Want to report a bug in our software? Find out how to contact us.