Skip to content

Items Overview#

Items are the fundamental building blocks of Miva Merchant templates, enabling developers to add specialized functionality and dynamic content to pages. Whether built-in or third-party, items serve as powerful tools for creating engaging and interactive e-commerce experiences.

This guide provides an in-depth understanding of items, their types, usage, and best practices for integrating them into Miva Merchant templates.

What Are Items?#

In Miva templates, items are references to compiled module files (.mvc files) that encapsulate specific functionality. For example:

  • The Store item references the stdstorefields module and provides store-specific information like the name and address.
  • Product list items manage the layout of product listings on category and search pages.

Items can take various forms within templates:

  • Self-closing tags: For example, <mvt:item name="store" />.
  • Tags with parameters: For example, <mvt:item name="customfields" param="Read_Product_ID()" />.

Types of Items#

Miva distinguishes between two primary types of items:

Built-In Items#

These are core components of Miva Merchant, providing essential functionalities like store settings, product data, and user management. Examples include:

  • store: For accessing store details.
  • basket: For managing basket data.
  • category_listing: For rendering products assigned to a category.

Third-Party Items#

Developed by external contributors, third-party items expand Miva’s capabilities beyond the default offerings. They are often used to integrate custom features or third-party tools.

Assignment and Functionality#

To use an item within a template, it must first be assigned to the corresponding page. This process is managed through the Miva admin interface under User Interface > Templates.

Assigning Items#

  1. Navigate to the desired page, fragment or layout in the admin interface.
  2. Open the Items tab.
  3. Select and assign the required item from the list.

Branch-Specific Assignments#

Starting with Miva Version 10.08.00, item assignments are branch-specific. This means changes to items in one branch do not affect the primary branch, enabling safe experimentation and testing.

Item Tags#

Item tags are used within templates to access and leverage the functionality provided by assigned items.

Example Rendering Product Listings#

<mvt:item name="category_listing" />
<mvt:foreach iterator="product" array="category_listing:products">
    <p>Product Name: &mvt:product:name;</p>
    <p>Price: &mvt:product:price;</p>
</mvt:foreach>

In this example:

  • The category_listing item manages the data array for products in a category.
  • A <mvt:foreach> loop iterates through the products to render their details.

Best Practices#

  1. Plan Item Assignments:

    • Only assign items to pages where they are needed to avoid unnecessary overhead.

  2. Leverage Global and Local Items:

    • Use global items for shared components like headers and footers.
    • Use local items for page-specific functionality.

  3. Document Item Usage:

    • Add comments to templates to explain why items are assigned and how they are used.

  4. Test in Branches:

    • Use Miva’s branching feature to test new item configurations without affecting the live site.

Summary#

Items are a cornerstone of Miva Merchant’s template architecture, providing the functionality needed to create dynamic and user-friendly storefronts. By understanding the types, assignments, and best practices for items, developers can fully leverage their potential to enhance e-commerce experiences.

Ready to dive deeper? Learn more about Global vs. Local Items → or explore Product List Items → for detailed use cases.