Skip to content

Using Custom Fields in Templates#

Custom fields in Miva Merchant allow you to extend the platform’s data capabilities and tailor content to your business needs. Once custom fields are created, they can be integrated into templates to display dynamic information, capture user input, and optimize workflows.

Accessing Custom Fields in Templates#

Custom fields are accessible via the customfield_values structure in templates when the custom field is assigned to the template. The format varies depending on the entity the field is associated with.

Syntax#

l.settings:[entity]:customfield_values:customfields:[field_code]

Examples:#

  • Product Field: l.settings:product:customfield_values:customfields:field_code
  • Category Field: l.settings:category:customfield_values:customfields:field_code
  • Customer Field: l.settings:customer:customfield_values:customfields:field_code
  • Order Field: l.settings:order:customfield_values:customfields:field_code

Displaying Custom Field Data#

Example 1: Displaying a Custom Product Field#

Add this snippet to the Product Display template to show a custom field for material after the custom field has been assigned to the template:

<p>Material: &mvt:product:customfield_values:customfields:product_material;</p>

Example 2: Displaying a Custom Category Field#

To display a custom category description after the custom field has been assigned to the template:

<p>Category Description: &mvt:category:customfield_values:customfields:category_description;</p>

Example 3: Displaying Custom Order Notes#

To display custom order notes in the INVC (Invoice) template after the custom field has been assigned to the template:

<p>Order Notes: &mvt:order:customfield_values:customfields:order_notes;</p>

Capturing Custom Field Data#

Custom fields can also capture user input, such as additional information during the checkout process.

Example: Capturing Order Notes During Checkout#

  1. Add a Text Area to the Checkout Page: 

    <label for="order_notes">Order Notes:</label>
<textarea name="order_notes" id="order_notes"></textarea>

  2. Store the Data in a Basket Field: On the OPAY (Payment Information) page: 

    <mvt:if expr="NOT ISNULL g.order_notes">
    <mvt:item name="customfields" param="Write_Basket( 'order_notes', g.order_notes )" />
</mvt:if>

  3. Automatically Transfer to the Order Field: Miva will automatically transfer basket data to the corresponding order field upon order placement if the field codes match.

Using Custom Fields with Facets#

Custom fields with the Facet option enabled can be used as filters on the frontend. For example, a custom product field for material can appear as a filter on category pages if configured as a facet.

Steps to Enable Facet Filtering:

  1. Ensure the custom field is created with the Facet checkbox enabled.
  2. Configure the field in the Miva admin under Catalog > Facet Rules.

Using Public Fields with the JSON API#

Custom fields with the Public option enabled can be accessed via the Miva JSON API. This is useful for integrating custom data with third-party tools or frontend applications.

Advanced Techniques#

Using Loops to Display Multiple Custom Fields#

If a template has several custom fields, use a loop to dynamically display all fields: 

<mvt:foreach iterator="field" array="l.settings:product:customfield_values:customfields">
    <p>&mvte:field:name;: &mvte:field:value;</p>
</mvt:foreach>

Conditional Logic with Custom Fields#

Use conditional logic to display or act upon custom field values.

Example: Display a message if a product is made of wood: 

<mvt:if expr="l.settings:product:customfield_values:customfields:product_material EQ 'Wood'">
    <p>This product is crafted from premium wood.</p>
</mvt:if>

Best Practices#

  1. Plan Field Usage:
    • Assign custom fields to templates only when necessary to minimize complexity.
  2. Use Meaningful Field Codes:
    • Ensure field codes are intuitive and descriptive for easier integration.
  3. Test Changes in Branches:
    • Use Miva’s branching feature to test field integration safely before applying changes to the live site.
  4. Leverage Facets and Public Options:
    • Enable facets for frontend filtering and public fields for API integration as needed.

Summary#

Custom fields are a powerful tool for tailoring Miva Merchant templates to specific business needs. Whether displaying dynamic product information, capturing user input, or integrating with the JSON API, custom fields provide flexibility and scalability for e-commerce operations.

Ready to explore more advanced options? Dive into Custom Field Functions → for programmatic management of custom field data.