Skip to content

Entities & Encoding#

Entities are variables used within Miva Merchant templates to display dynamic values directly on the screen. Depending on the items assigned to a page, different entities become accessible, allowing developers to output data such as store names, product prices, or category details.

Miva Merchant also provides encoding options to ensure secure and proper handling of these variables. Encoding prevents issues such as cross-site scripting (XSS) and ensures compatibility with various output formats, including HTML, URLs, and JSON.

Entity Basics#

Entities follow a consistent format:

  • Begin with an ampersand (&)
  • End with a semicolon (;)
  • Include a structured path to identify the data source

Examples:#

  • &mvt:store:name; — Prints the store name.
  • &mvte:category:name; — Prints the current category name with entity encoding.
  • &mvt:product:formatted_price; — Prints the product’s formatted price.

The structure:

  • &mvt: Indicates this is a Miva Merchant template entity.
  • Middle Part: Specifies the item being referenced (e.g., store, category, or product).
  • Final Part: Defines the specific field to output (e.g., name, formatted_price).

Encoding Options#

Miva Merchant offers several encoding methods, each serving a distinct purpose:

No Encoding (&mvt:)#

Prints the value directly to the screen without applying any encoding. Use with caution, as it may expose vulnerabilities if user input is displayed.

Example: No Encoding#

<mvt:assign name="g.no_encoding" value="'This is not encoded'" />
&mvt:global:no_encoding;

Output in HTML: 

This is not encoded

Entity Encoding (&mvte:)#

Encodes special characters into their HTML entity equivalents. This is essential for preventing XSS attacks and ensuring that HTML reserved characters, such as < and >, are displayed as intended.

Example: Entity Encoding#

<mvt:assign name="g.myvariable" value="'<script>alert(\"oh no\")</script>'" />
&mvte:global:myvariable;

Output in HTML: 

<script>alert("oh no")</script>

Attribute Encoding (&mvta:)#

Converts characters into formats suitable for use in attributes, particularly in URLs. For example, spaces are replaced with %20 to ensure valid and functional links.

Example: Attribute Encoding#

<mvt:assign name="g.attribute_encoded" value="'This is attribute, encoded'" />
&mvta:global:attribute_encoded;

Output in HTML: 

This+is+attribute%2C+encoded

JSON Encoding (&mvtj:)#

JSON Encoding ensures that characters are properly formatted for use within a JSON object. This is particularly useful when passing variables to JavaScript or integrating with APIs.

Example: Embedding JSON Data#

<mvt:capture variable="g.product_name">
    O'Reilly's Special Product
</mvt:capture>
<mvt:assign name="g.product_price" value="19.99" />

<script>
    const product = {
        name: "&mvtj:global:product_name;",
        price: &mvtj:global:product_price;
    };
    console.log(product);
</script>

Output in JavaScript: 

const product = {
    name: "O\u0027Reilly\u0027s Special Product\r",
    price: 19.99
};

JSON Encoding ensures that special characters in g.product_name, such as the apostrophe, are properly escaped, preventing syntax errors in the JavaScript object.

Slug Encoding (&mvts:)#

Slug Encoding transforms a string into a URL-friendly format by replacing spaces with dashes, removing special characters, and normalizing the text. This is useful for generating SEO-friendly URLs or identifiers.

Example: Generating a Slug for a Product Name#

<mvt:assign name="g.product_name" value="'New Arrival: Winter Coats!'" />

<p>Product Slug: &mvts:global:product_name;</p>

Output in HTML: 

<p>Product Slug: New-Arrival-Winter-Coats</p>

In this example:

  • Spaces are replaced with dashes.
  • Special characters (: and !) are removed.

Importance of Encoding#

Security#

Encoding protects your templates from vulnerabilities like XSS by neutralizing malicious code injected into user inputs.

Compatibility#

It ensures that variables work correctly in different output contexts, such as:

  • HTML (entity encoding)
  • URLs (attribute encoding)
  • JSON (JSON encoding)

Readability#

Encodings like slug formatting make variables more readable and user-friendly in specific use cases.