Note
This functionality is available starting with CS-Cart/Multi-Vendor 4.4.1.
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}) }}
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.
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
.
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.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.
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>
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.
'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)
{hook name="snippets:tabs_extra"}{/hook}
(design/backend/templates/views/snippets/update.tpl)—it allows to add new tabs to the snippet editing popup.We use the Twig library (version 1.24) as a template engine. The standard extensions are included:
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).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.
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.