Skip to content

Custom Field Functions#

Miva Merchant provides a robust set of custom field functions to read, write, and debug custom field data programmatically. These functions allow developers to interact with custom fields seamlessly across various entities, such as products, categories, customers, baskets, orders, and pages. By integrating these functions into templates, you can dynamically manage and display custom field data to enhance your store’s functionality.

Function Overview#

Custom field functions in Miva follow a consistent naming convention:
[Read/Write]_[Entity]_[Code/ID]

Below is a comprehensive list of all available functions:

Function Description
Read_Product_Code Reads a custom field value associated with a product by its code.
Write_Product_Code Writes a value to a custom field for a product by its code.
Read_Product_ID Reads a custom field value associated with a product by its ID.
Write_Product_ID Writes a value to a custom field for a product by its ID.
Read_Category_Code Reads a custom field value associated with a category by its code.
Write_Category_Code Writes a value to a custom field for a category by its code.
Read_Category_ID Reads a custom field value associated with a category by its ID.
Write_Category_ID Writes a value to a custom field for a category by its ID.
Read_Customer_Code Reads a custom field value associated with a customer by its code.
Write_Customer_Code Writes a value to a custom field for a customer by its code.
Read_Customer_ID Reads a custom field value associated with a customer by its ID.
Write_Customer_ID Writes a value to a custom field for a customer by its ID.
Read_Page_Code Reads a custom field value associated with a page by its code.
Write_Page_Code Writes a value to a custom field for a page by its code.
Read_Order Reads a custom field value associated with an order.
Write_Order Writes a value to a custom field for an order.
Read_Basket Reads a custom field value associated with a basket.
Write_Basket Writes a value to a custom field for a basket.

Note

The Read_Basket and Write_Basket functions differ slightly from other functions. They do not require an entity identifier as a parameter, as they operate directly on the current basket context.

Reading Custom Field Data#

Syntax#

<mvt:item name="customfields" param="Read_[Entity]_[Code/ID]( entity_identifier, 'field_code', variable )" />

Examples#

Example 1: Reading a Product Custom Field by Code#

<mvt:item name="customfields" param="Read_Product_Code( 'PRODUCT123', 'product_material', l.settings:customfield_material )" />
<p>Material: &mvt:customfield_material;</p>

Example 2: Reading a Category Custom Field by ID#

<mvt:item name="customfields" param="Read_Category_ID( l.settings:category:id, 'category_description', l.settings:customfield_category_description )" />
<p>Description: &mvt:customfield_category_description;</p>

Example 3: Reading an Order Custom Field#

<mvt:item name="customfields" param="Read_Order( l.settings:order:id, 'order_notes', l.settings:customfield_order_notes )" />
<p>Order Notes: &mvt:customfield_order_notes;</p>

Writing Custom Field Data#

Syntax#

<mvt:item name="customfields" param="Write_[Entity]_[Code/ID]( entity_identifier, 'field_code', 'value' )" />

Examples#

Example 1: Writing a Custom Field Value to a Product#

<mvt:item name="customfields" param="Write_Product_Code( 'PRODUCT123', 'product_material', l.settings:variable )" />

Example 2: Writing a Custom Field Value to a Basket#

<mvt:item name="customfields" param="Write_Basket( 'basket_discount', '10%' )" />

Example 3: Writing a Custom Field Value to an Order#

<mvt:item name="customfields" param="Write_Order( l.settings:order:id, 'order_notes', 'Please handle with care.' )" />

Debugging Custom Fields#

The Debug() function helps troubleshoot custom field-related issues by displaying error messages and variable states.

Syntax#

<mvt:item name="customfields" param="Debug()" />

Example: Debugging in Development#

<mvt:if expr="s.remote_addr EQ '123.456.789.0'">
    <mvt:item name="customfields" param="Debug()" />
</mvt:if>

Output: Displays errors and variable states in the top-right corner of the admin interface.

Best Practices#

  1. Use Meaningful Field Codes:

    • Choose descriptive field codes to simplify template integration and debugging.
    • Example: Use product_material instead of pm.

  2. Optimize Field Access:

    • Avoid redundant reads or writes in loops. Cache values when possible to reduce overhead.

  3. Debug Safely:

    • Use the Debug() function conditionally to avoid exposing error messages on live sites.

  4. Document Field Usage:

    • Maintain clear records of custom field codes, entities, and their purposes.

  5. Test in a Sandbox:

    • Use Miva’s branching feature to test custom field functions in a non-production environment.

Advanced Techniques#

Using Loops to Access Multiple Custom 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#

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

Summary#

Custom field functions empower developers to dynamically read, write, and debug custom field data across various entities in Miva Merchant. By incorporating these functions into templates, you can build highly customizable and data-driven e-commerce solutions.

Explore Basket and Order Custom Fields → to learn how to implement order custom fields efficiently.