Snippets

Introduction

A snippet in Venddor IO refers to a distinct section of a template that can be recurrently integrated across multiple templates.

Think of snippets as reusable components, akin to headers and footers, which you can find in nearly all email notifications. Unlike individual templates, snippets don't possess their own exclusive context and variables. Instead, they derive these elements from the primary template they're a part of.

Snippets prove useful for both email and document templates in Venddor IO.

Using Snippets

If you want to incorporate a snippet into a template, it would look something like this:

{{ snippet("header") }}

If you're aiming to embed a snippet but with some added variables, the representation would be:

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

Snippet Categorization in Venddor IO

In Venddor IO, snippets are organized based on distinct types. This classification system ensures that only relevant snippets are accessible for specific document types. For instance, 'mail' type snippets are accessible for email notifications, but are not for other documents.

Data Composition

The table cscart_template_snippets maintains a comprehensive record of snippets. The details within this table encompass:

Name - A designated column name.
Type - The data type of the column.
Description:
snippet_id (id): A unique auto-incremented identifier for the snippet.
code (varchar(128)): A character-based code representing the snippet.
type (varchar(32)): Denotes the snippet type.
template (text): The specific template used.
default_template (text): The fallback or standard template.
status (char(1)): Indicates the snippet's status.
handler (text): Refers to the function handling the snippet.
params (text): Contains any additional parameters.
addon (varchar): Identifies the associated add-on module.
updated (int): Timestamp indicating the last update.
created (int): Timestamp indicating when the snippet was created.

Moreover, the multilingual name of the snippet resides in a separate table, venddor_template_snippet_descriptions.

Developmental Interface

Venddor IO incorporates several specialized classes to streamline snippet management:

\Tygh\Template\Snippet\Snippet: This acts as the model for snippets, offering a programming perspective of the snippet's structure.
\Tygh\Template\Snippet\Repository: Termed as the repository for snippets, this class furnishes fundamental methods for database operations like retrieval, addition, updating, and deletion of snippets. It's accessible through the Tygh::$app['template.snippet.repository'] container.
\Tygh\Template\Snippet\Service: This service-oriented class furnishes more advanced methods for managing snippets. It's initiated via the Tygh::$app['template.snippet.service'] container.
\Tygh\Template\Snippet\Exim: Dedicated to the task of importing and exporting snippets, this class is integral for data mobility. Its instance can be fetched using the Tygh::$app['template.snippet.exim'] container.

Decoding the Snippet Rendering Process in Venddor IO

Identification of the Snippet Type:
Within the template, the snippet type gets distinguished. This enables each template that invokes a snippet to recognize its accessible snippets. Technically speaking, a template is a class that adheres to the ITemplate interface.
Snippet Retrieval:
The snippet associated with the specified type and its unique character identifier is procured using the \Tygh\Template\Snippet\Repository class.
Pre-render Hook Invocation:
Prior to the actual rendering, the 'template_snippet_render_pre' hook is triggered.
Template Engine Rendering:
Venddor IO calls upon its built-in template engine to execute the snippet rendering.
Post-render Hook Invocation:
Following the rendering, the 'template_snippet_render_post' hook is activated.
Result Delivery:
The finalized output is then returned to the user or relevant module.

Snippet Inclusion

Modules within Venddor IO have the capability to introduce custom snippets of any kind. Generally, snippets get incorporated during module installation and are expunged when the module is removed. To incorporate snippets, developers can employ methods from the \Tygh\Template\Snippet\Service or even define snippets directly within the module's schema. A simple illustration is as follows:

<?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>

Enhancing Snippets

There are instances where the default visual editor might not be sufficient to create the desired template. Certain situations may demand a more dynamic structure or advanced data manipulation.

Let's consider an example. To display a product list in an 'order.invoice' document, an expandable table might be needed, which isn't effortlessly crafted via the visual editor. To cater to such challenges, Venddor IO incorporates hooks that can modify snippet rendering and enrich the editor's interface.

Understanding the Snippet Rendering Mechanism in Venddor IO

1. PHP Hook Pre-Rendering

The 'template_snippet_render_pre' hook triggers before a snippet gets rendered. This hook is instrumental in introducing essential variables, which can subsequently be employed within the snippet template:

fn_set_hook('template_snippet_render_pre', $snippet, $context, $variable_collection)

2. PHP Hook Post-Rendering

Post the rendering process, the 'template_snippet_render_post' hook activates:

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

3. Deletion Hook

Once a snippet is deleted, the 'template_snippet_remove_post' hook gets called:

fn_set_hook('template_snippet_remove_post', $this, $snippet)

4. Database Saving Hook

After saving a snippet to the database, 'template_snippet_save_post' is invoked:

fn_set_hook('template_snippet_save_post', $this, $snippet, $lang_code)

Template Enhancements

The template permits the addition of new tabs to the snippet editing interface through the {hook name="snippets:tabs_extra"}{/hook} located in (design/backend/templates/views/snippets/update.tpl).

Diving Deep into Venddor IO's Template Engine

Venddor IO harnesses the power of the Twig library for its template engine. Standard extensions incorporated include:

Twig_Extensions_Extension_Text
Twig_Extensions_Extension_Array
Twig_Extension_Debug (exclusively in developer mode).

Moreover, some bespoke filters and functions enrich the system:

Date Filter

It formats values into dates. For users, specifying the date format is essential. As an illustration:

{{ o.raw.timestamp }}

would render as a Unix timestamp like 1127988066.

{{ o.raw.timestamp|date("%d/%m/%Y") }}

would manifest as a human-readable date such as 29/09/2005.

Notably, there's no obligation to determine the date format. If the filter is used without specifying the format, for instance, {{ o.raw.timestamp|date }}, it would default to the date format selected under the Settings → Appearance page in Venddor IO.

1. Price Filter

This filter streamlines the presentation of numerical values into currency format. For instance, {{ o.raw.total }} might render as 917.99. Yet, with the filter, {{ o.raw.total|price }}, it gets beautified to $917.99. Interestingly, users can customize the currency representation. Thus, {{ o.raw.total|price("EUR") }} would display the total in Euro, adhering to the store's set conversion rate. By default, when no currency is defined, the primary store currency CART_PRIMARY_CURRENCY will be used.

2. Filesize Filter

This filter elegantly displays file sizes in terms of kilobytes. An apt instance can be observed in the email template about accessing downloadable products, exhibited as {{ file.file_size|filesize }}.

3. Puny Decode Filter

This nifty filter decodes PunyCode URLs into a more globally recognized format. Often spotted in email templates with URLs; for example, in password recovery emails, it's represented as {{ url|puny_decode }}.

4. Translation Function (__)

This function avails translated text. For illustration, {{__("change_order_status_c_text")}} in the English rendition of a document might manifest as: "Your order has been completed. Thank you for choosing us."

5. Snippet Function

Facilitates the embedding of code snippets into templates. For instance, in the Invoice document, {{ snippet("ship_to") }} fetches the corresponding code from the 'Code snippets' tab and integrates it into the document.

6. Include_doc Function

An essential function that permits the inclusion of documents directly into email notifications. For example, email notifications about order statuses might contain: {{ include_doc("order.summary", order_info.order_id) }}. This line seamlessly integrates the 'order.summary' document, offering detailed information about the order, into the email content.