Custom Fields
Important!
Before using this app, please check whether you will need to install coding on your ShopWired theme. For more information please click here.
The custom fields app is an advanced and powerful tool that can be used to add additional data to categories, brands, products, orders, quotes, pages, blog posts and customers.
Different types of custom fields are available (text fields, data lists, product lists, dates and times) and can be used for a number of different purposes.
At the most basic level, custom fields can be used to show additional data on your website, such as a specification table, as shown in the example below:
Functionality as shown in the example above can be achieved by creating a custom field for each specification type, like 'Color' or 'Screen Size Diagonal', and then entering the appropriate data for each product.
At a more advanced level, custom fields can be used to change the functionality of your website (for example, to swap an 'add to cart' button to an 'enquire now' button on product pages if a custom field is selected).
To use custom fields you must first install the app. To do this select INSTALL THIS APP.
from the menu. Find and select the 'Custom Fields' app and select• Configuring custom fields
• Adding data for custom fields (categories, products, blog posts, pages & brands)
• Using custom fields on your website
• Custom fields for customers
• Adding data for custom fields (orders & quotes)
• Using order custom fields on your ShopWired account
• Use case examples
Configuring custom fields
Once you've installed the app you can begin to configure your custom fields by selecting
from the menu.At the top of the page you can use the box to create a new custom field.
In the Item Type field select which type of field you are creating, either one for products, categories, brands, orders, pages, blog posts or customers.
In the Name field you need to enter the variable that you'd like to use when referencing the data in the field on your website files. You should only use letters and the _ character here (no spaces).
The Sort Order field enables you to organize the order in which the custom fields are displayed when adding data to them on pages in the admin system. You can leave this field blank if the order is not important to you.
In the
Label field you can enter the label of the field, as it will display to you when adding/editing the product, category, brand, page, blog post, customer or order.
In the Type field you should select what type of data the field will contain. In our example above (the specification table) you would use 'Text Box'.
Depending on the Type selected, you may be able to configure the Allowed Values for the field. For example, if you select 'List', then you'll be able to enter the available values (separating each with a comma).
Text Box | A text string |
Toggle | Either a TRUE or FALSE option |
Choice | A list of available values for you to choose one of, using radio buttons. |
List | A list of available values for you to choose one of, using a drop down list. |
Date Picker | Pick a date |
Date & Time Picker | Pick a date & time |
Value List | Enter a list of individual values |
Product List | Pick from a list of products |
The below is an example of how a custom field might look if configured correctly for a 'Screen Size' attribute:
Customer custom fields
When creating or editing a custom field for customer records, you'll see an additional question about whether the custom field can be exposed on the front end of your website. You can tick yes if you'd like to be able to display this as a field on the account creation and edit pages of your website.
In order for the field to be available on your website, code needs to be added to your theme (details are included below). The field will not display automatically.
Adding data for custom fields (categories, products, blog posts, pages & brands)
When adding/editing a product, category, blog post, page or brand, scroll to the 'custom fields' section.
The custom fields that you have created will be displayed in this section:
Enter your data into the fields and click the save button.
If you've created a product list custom field, then the drop down will display all of the products loaded onto your account for you to select from.
Using custom fields on your website
Data attached to a product, category or brand through the custom fields system is available through the corresponding Twig object. (Either the product, category or brand object).
Our example below is for custom field data attached to a product, so uses the product object, if you're using custom fields for brands or categories, substitute the format of the variable to use the corresponding object.
The format required is product.custom_fields.X where X is the name given to the custom field, e.g. product.custom_fields.screen_size.
Where you have created a Toggle custom field, the variable will return TRUE or FALSE depending on whether the custom field is ticked or not.
Value Lists
Where you have created a Value List custom field, the variable will return an array.
{% for value in product.custom_fields.X %} {{ value }} {% endfor %}
It's also possible to reference a specific element of the array, e.g. product.custom_fields.X[0], 0 is the first item in the array.
Product Lists
Where you have used the Product List type, this will also return an array which can then be used to return details about the selected product(s). For example,
{% set product_id = product.custom_fields.X[0] %} {% set alternative_product = product(product_id) %} {{ alternative_product.title }}
In the example above we've referenced just the first selected product, in the example below we're iterating through all the selected products.
{% for value in product.custom_fields.X %} {% set product_id = value %} {% set alternative_product = product(product_id) %} {{ alternative_product.title }} {% endfor %}
Dates
Where you have used the Date Picker or Date & Time Picker type, you can modify the output using Twig's Date Filter.
Custom fields for customers
Adding data
If you have created custom fields for customers, you can add data to an existing customer when editing the customer's details in the admin system. When editing the customer scroll to the ‘Custom Fields’ section:
All of the custom fields which you created using the ‘Customer’ item type will be displayed for you to use.
Using the customer import/export system
Additionally, you can add data to customer custom fields when you create a customer through the import system.
However, because you cannot update customers using the import/export system, you will not be able to add or change custom field data for existing customers. This would need to be done manually through the admin system.
When an export is taken of your current customers, any custom field data which has been entered for a customer will be displayed in the file.
Using customer custom field data on your website
Custom field data for customers can be referenced on your website in the same way as products, categories and brands, as described above, by using the required format ofcustomer.custom_fields.X, where X is the name given to the custom field, e.g. customer.custom_fields.priority.
Order object
Through the order object, custom field data entered for customers can be displayed on orders (e.g. on order invoices, order PDFs, order confirmation and status emails or on the order details pages on your website).
The required format is order.customer.custom_fields.X, where X is replaced with the name given to the custom field. For example, order.customer.custom_fields.priority.
Because custom field data for customers is not stored within an order, the data which is returned will be the data which currently exists in the custom field(s). This means that the data which existed when the order was placed will not appear if the data has since been changed.
Display customer custom fields on your website
If you've indicated that you'd like to be able to expose a customer custom field on your website, you can follow the instructions below to add code to your theme for the field to display.
An array of custom_fields is available to return all custom fields exposed.
Each item within the array has the following properties:
name - the name that the custom field is given
type - the type of custom field, e.g. date or toggle
label - the label that the custom field is given
value - the value already entered for the custom field (used on account/edit) - this can be an array depending on type
allowed_values - an array of available values, only available for certain types (choice or list types)
Some sample code is below but this should not be used in its exact form.
{% for field in custom_fields %} <label> {{ field.label }} </label> {% if field.type == 'toggle' %} <input type="checkbox" name="{{ field.name }}" value="1" {% if field.value %} checked{% endif %}> <br> {% elseif field.type == 'choice' or field.type == 'list' %} <select name="{{ field.name }}"> <option value="">Please select...</option> {% for value in field.allowed_values %} <option value="{{ value }}"{% if value == field.value %} selected{% endif %}> {{ value }} </option> {% endfor %} </select> {% elseif field.type == 'date' %} <input type="text" name="{{ field.name }}" value="{{ field.value|date('d/m/Y') }}"> {% elseif field.type == 'value_list' or field.type == 'product_list' %} <input type="text" name="{{ field.name }}" value="{{ field.value[0] }}"> {% else %} <input type="text" name="{{ field.name }}" value="{{ field.value }}"> {% endif %} {% endfor %}
For a simpler implementation, you may wish to just output the name for use in an input field, in which case use the variable custom_fields.X.form_field_name where X is the name of the custom field. For example:
<input type="text" name="custom_fields.X.form_field_name">.
Adding data for custom fields (orders & quotes)
Order custom fields are created in the same way that they are for products, categories and brands (described above).
Any custom fields created for orders will also be available for use on quotes.
When creating or editing an order or a quote, you can then select the data for the custom field(s).
Custom field data attached to orders or quotes can be added or changed at any time in the 'Custom Fields' section of the order/quote.
When a quote is marked as paid and becomes an order, the custom fields and any inputted data will transfer from the quote to the order along with the rest of the details in the quote.
Custom field order data is exported within the order CSV export.
Using order custom fields on your ShopWired account
Filtering orders using custom fields
When viewing your orders you can filter them using custom fields that you have created. To use custom fields to filter your orders select More Filters:
from the menu. Then selectBeneath the regular filters for orders you will see any custom fields you have created. Use these filters to view orders related to that custom field.
Please note!
Custom fields created using the ‘Product List’ or ‘Value List’ types will not be eligible to use as filters.
Searching orders based on text custom fields
In addition to filtering using custom fields you can use the ‘Search Your Orders’ function to search your orders based on text custom fields which you have created.
In the search box enter a value which was placed in a text custom field to see search results related to that value. Do not search using the label you gave the custom field as this will not yield results.
Please note!
The search function will not work for text custom fields which use numeric values. For these types of custom fields you should use the filter function instead.
Order Object
Custom fields for orders are available on the Order Object (using Twig coding).
This means that you can use order custom field data in the following places/functionality:
• Order confirmation emails (when custom data is added to an order at the time the order is created through the admin system)
• Order status emails
• Order PDF
• Order XML feed
• The order pages (within customer accounts)
Required Format
The format required is order.custom_fields.X where X is the name given to the custom field, e.g. order.custom_fields.sage_customer_id.
Where you have created a Toggle custom field, the variable will return TRUE or FALSE depending on whether the custom field is ticked or not.
Value Lists
Where you have created a Value List custom field, the variable will return an array.
{% for value in order.custom_fields.X %} {{ value }} {% endfor %}
It's also possible to reference a specific element of the array, e.g. orer.custom_fields.X[0], 0 is the first item in the array.
Product Lists
Where you have used the Product List type, this will also return an array which can then be used to return details about the selected product(s). For example,
{% set product_id = order.custom_fields.X[0] %} {% set alternative_product = product(product_id) %} {{ alternative_product.title }}
In the example above we've referenced just the first selected product, in the example below we're iterating through all the selected products.
{% for value in order.custom_fields.X %} {% set product_id = value %} {% set alternative_product = product(product_id) %} {{ alternative_product.title }} {% endfor %}
Use case examples
The most common, and most obvious, use of custom fields is to display additional information on your website. The information can be as simple as one line of text, or more structured data as shown at the top of the page.
Moving to an intermediate level, custom fields can enable things to be 'done' or displayed in a certain way when enabled. For example, a custom field checkbox (of the 'toggle' type) allows you to select (or not select) and the custom field variable on your website will then return true or false. In twig, you can detect this true or false state of the custom field and action code accordingly. For example, a 'This product is POA' tick box could be used to hide a product's price and add to cart button and instead display an 'Enquire about this product' button.
At a more advanced coding level, toggle custom fields can be used to render completely different product, category or brand page templates/layouts.
Using custom field product lists, on category pages you could output a list of 'favorite products' for each category, or on product pages show different products for customers to purchase with the product they're viewing (e.g. essential accessories, recommended products).
Custom field product lists can be displayed in various places, so you could for example display a section of 'we recommend you purchase these products' in a popup, displayed when the main product is added to the cart.
Order custom fields
Using order custom fields you can store and output additional information attached to an order (such as a Sage Accounts Customer ID).
You can use toggle choices to change the design or layout of customer facing information like order confirmation emails and invoice PDFs.
Data in custom fields is available on order status emails too. Using this system, you can attach as much information about an order as you like and then send this through to the customer through the order status email system.