Custom Fields

Custom fields can be used both on the frontend and backend of the store and can have their values set either by the customer, on the front-end, or by the store admin via the backend.

See our Tutorial section for information on Adding a Custom Field, or our Cheat Sheet for code snippets related to Custom Fields.

Uses for Custom Fields

Custom Fields can be used in a variety of ways. Here are a handful of ideas:

  • Frontend product field to have your customers fill out an engraving message for jewelry products.
  • Backend product rich-text area, to output "additional information" content for each product in your store.
  • Customer field to add a "tax number" to customer records, which they can fill out at on registration or checkout.
  • Cart / Order field to include a "request delivery date" field for orders.

Where can I add a Custom Field?

Custom fields in LemonStand can exist in the following areas of your store:

1. Backend Product – added to the backend product form and can be shown on the frontend (e.g. product specs).

2. Frontend Product – can be added on the frontend product page, customers can enter the value for it (example: engraving message).

3. Customer – added to the customer form in the admin area, can be added on the frontend (example: customer tax number).

4. Cart / Order – can be added to the frontend cart page (example: delivery instructions).

Custom Field Definitions

To add a custom field to your store, go to Settings and then click on Custom Fields. You will be presented with the "Custom Field Definitions" list.

Field Name - Set the name for your custom field.

Field Title - Set the title for the custom field. The field title will be used when displaying the custom field in the backend.

Field Type - Select the type for your custom field. Options include – text field, checkbox, drop-down list, text area, rich text field.

Required - Set the required status for the custom field, preventing the record from being saved if the field is left empty. Should not be used with "Checkbox" type fields.

Adding a Custom Field

Click the Add button to add a new custom field for your store. You will then be presented with a drop-down allowing you to select the type of field you would like to add.

Select the custom field type of your choice and then hit continue. You will then see a form containing the various options available for your custom field.

Note: You can have a maximum of 20 fields for each field type (20 backend product fields, 20 frontend product fields, 20 customer fields etc). Of those 20 fields for each type, only 10 can be text area or rich text fields.

Backend Forms

Backend fields like backend product and customer will also have a "Backend Form" tab on the custom field's settings page.

This section will allow you to create and name a tab that your custom field will appear under for the custom field's related form in the backend of your store. For example, setting a tab name of "Product Specs" for the backend product field type will create a tab on the product form when editing a product named "Product Specs". In this tab you'll also see entry fields for any custom fields you've created and linked to this tab, as shown below. If the tab name is left blank, LemonStand will create a tab for you named "Custom Fields" instead.

Accessing Backend Custom Fields In Your Theme

Displaying the values of back-end custom fields like backend product or customer in your theme can be done by simply outputting the custom field's name as part of a TWIG tag, similar to how you would access any of the regular attributes in the system. For example, our "Product Specs" backend product field can be outputted on the front-end using:

{{ product.product_specs|unescape}}

Frontend Product Fields

To save the value entered by a customer for a frontend product field, we first need to add the field to the product form, similar to how we would add any other form input field.

For example, if we were to create a frontend product field that would allow the customer to add an engraving message to a bracelet, we would add the following to our shop-product partial:

Engraving message:

<input type="text" name="engraving_message">

The input field's name value will simply need to be equal to the name you gave your custom field when setting it up.

Frontend product fields will be saved using the shop:onAddToCart handler, so the value will be saved when the customer adds the item to the cart using the "Add to cart" button.

For more code snippets, including drop-down field types, Customer Fields, and Cart/Order Fields, see the Cheat Sheet for this section.

Drop-down field type

For drop-down list type fields, the options can be accessed by adding options to the field name, for example if the custom field's name is giftwrap_color, your code would look like this:

Gift Wrap Color:

<select id="giftwrap_color" name="giftwrap_color" class="product-option">
{% for key, value in product.giftwrap_color_options %}
<option value='{{ value }}'>{{ value }}</option>
{% endfor %}

The custom fields selected when adding the product to the cart are added to the string outputted bycartItem.optionsString(), so they don't need to be displayed separately in the list of items displayed in the cart. Alternatively, if you want to display custom field values separately from the regular product options, you can use {{ cartItem.optionsString("; ", false) }} to get just the regular options string without the custom fields. You can then show custom fields separately, using {{ cartItem.my_custom_field_name }}, for example.

Customer Fields

Customer type custom fields can be saved using the shop:onUpdateCustomerProfile ajax handler which is generally used on customer profile pages and can be included on the customer profile form in the same manner as other frontend product fields. For example:

Tax Number:

<input type="text" name="customer_tax_number">

Cart / Order Field

Cart / Order type custom fields are saved using the shop:cart ajax handler and can be included in the cart page of your store. They can also be saved to the order by using shop:checkout ajax handler in the checkout steps of your store, like the Address or Shipping Method step.

For example, you could include a delivery instructions custom field on your cart page using:

Delivery Instructions:

<textarea name="delivery_instructions" placeholder="Enter delivery instructions here...">
{{ cart.delivery_instructions }}

In the backend, custom Cart / Order fields show up under the summary section on the order details tab.

Keep in mind that hitting the checkout button on the cart page does not generally fire an ajax handler. In order to have your custom cart field value saved when hitting the checkout button, you will need to add the shop:cart handler to your checkout button and also add a redirect value for data-ajax-extra-fields to handle the redirect to the checkout-start page. For example:

<a data-ajax-handler="shop:cart" data-ajax-extra-fields="redirect=/checkout-start">Checkout</a>

Displaying all custom fields

You can loop through all of the custom fields for a page using the getCustomFields() helper:

{# This can be used anywhere a cart item is in scope #}

{% for field in item.getCustomFields() %}
    {% if not field.displayOnly %}
        <label class="control-label" for="{{ }}">{{ field.label }}</label>
        <input class="form-control custom-field" style="width: 100%;" name="{{ }}" value="{{ field.value }}" />
    {% endif %}
{% endfor %}  
Variable Usage