Understanding Fields

Field elements are the heart of any configurator. They perform two tasks: 

  1. Store a value of a certain datatype (text, number, boolean, etc.) so it can be used in Snap code. Values stored in fields are persistent: the contents of a field is saved and retrieved when a configured product is saved and re-opened. If you've written code in other languages, think of a field as a global persistent variable that comes with it's own UI.
  2. Display that value to the end user using a certain UI widget /control (textbox, checkbox, select list, etc.). The default display properties of a field are set in the configurator admin screen during design-time, and can be overridden dynamically by Snap rules during run-time.

Add a field to a configurator

To add a field to a configurator or quote header, first open it in the Admin Interface so you see its design tree. Click on a layout in which you would like the field to appear (such as a group, tab, or expander), and then click on the '+' button that appears to the right of the layout.  Select "field" from the pop-up list.

Move a field within a configurator

Fields, like many other elements in the design tree, can be moved by simply dragging and dropping.  First click the field once to select it, then drag it into any other container in the "Configurator" node of the design tree.

Duplicate or delete a field

Fields, like all other UI elements in the configurator design tree, can be duplicated or deleted by selecting the field in the tree, clicking on the "..." ellipsis button, and selecting the desired command.


Field Properties

Properties of a field can be set by any company administrator in the configurator admin screen by selecting the field in the tree, and changing the options in the properties pane.  These same properties can be changed dynamically while the configurator is running by Snap rules.  

 

Field Property Description
Name

A programmatic name which appears in the design tree and is referenced to in rules. The name is mandatory. Two fields in the same configurator cannot have the same name.

Examples: f_Boat_Height, BoatHeight, bHeight

Label

A user-facing label which appears in the UI. The label is optional: when left blank, the field's name will appear in the UI instead. Labels can be repeated within the same configurator. The label can change when you have multiple languages activated.

Examples: "Boat Height (cm)", "Boat Height"

Data Type The type of value this field will hold, such as a date or number.
Control The control or "widget" used to display the data in this field. Certain controls are only available for specific data types (for example, sliders only work with number fields).
Show Label Hide the label completely by clearing this checkbox.  This is a useful technique when building more complex layouts: the containers page has an example.
Visible Specifies whether this field is shown to the user or hidden. This property is commonly changed dynamically via Snap in a visibility or value rule.
Enabled Specifies whether this field is editable by the user or locked to them. If disabled, the user can see the field but cannot change its value. A disabled field appears "greyed out" and cannot be selected or edited.
Required

If set to false, then the validation rules you write will be applied. This is the default behavior, and supports complex logic.  

If set to true, then a simple test for a null value will be applied to this field. A value will always be required in this field before the user can submit their configuration. An empty field is not allowed.  After this simple test, the standard validation rules are also applied as usual.

This property appears only for certain data types, such as text, date, and color.  To validate other data types, use a validation rule. Most configurator fields require more complex logic than a simple test for a null value.  To apply more complex logic, or to control if the validation shows a warning or an error, use a validation rule.

Value The default value for the field when your configurator first launches. This value can change if the user changes the value by using the control, or if a value rule changes it to meet a business need via Snap.
Help Properties
Description Text that will appear in a help tooltip for the field.
Help Media An image or a video that will show in the help tooltip for the field.
Help Url URL to a webpage that has more information about the selections in this field. For example, you can use this to link to a datasheet on your website.  The URL will appear as a clickable "learn more" link inside the help tooltip for the field.
Number Properties
Precision Specifies how many decimal places the value can have.  For example, many currencies would be expressed with a precision of 2.
Step For a numberbox control, controls how much the value is incremented by when the arrows are clicked.
For a slider control, controls the minimum unit the number is changed while dragging the slider.
Constrain Value

If set to true, then the min and max properties can be set to control the range of valid values for the number field.

  • When using the numberbox control, if the user types a value outside of the min-max range, a validation error will be shown to the user.
  • When using the slider control, specifies the min-max range for the slider.
Min The minimum value this numeric field can hold.
Max The maximum value this numeric field can hold.
Format How to display the value to the user. Can be none (default), number, currency, or percentage.
Currency If currency is selected for the format, specify which of the currencies enabled in this org will be shown to the user.
Min Precision When the field loses focus (is not being edited), this either truncates data or adds trailing zeroes to the value of the field until the minimum precision is met. For example, if the minimum precision is 2 digits, and the data stored in the field is 32.1, then the field will display as 32.10 after editing. If the user enters 32.12345 into the field, then the field will be truncated as 32.12 after editing.
Prefix,
Suffix
Text to prepend before (prefix) or append after (suffix) the number value when it is displayed.  This is for display only: the prefix or suffix seen on-screen is not stored in the value of the field. For example, append a unit of measure, such as "cm" or "in", as the suffix of a field to ensure your users enter the correnct amount.


Detecting changes in a field's value

Since rules automatically execute whenever any field is changed, you usually don't need to worry about checking if a field's value has changed. Your option filters, value rules, etc. refresh automatically. However, there may be some times when you want code to run only when a specific field is changed, not when any field is changed.  For example, if the code is a time-consuming operation, and not needed with every edit.  

In many contexts, you can use the "Get" block in the following manner to detect a change in a specific field's value:

Position

If your field is within a container, that field will also have extra Position properties to align it within that container. Learn more about positioning elements within a container.

Field Controls

Below are the controls you can choose from to represent your field in the UI of the running configurator and their associated properties.  The examples shown are based on the theme skin "Material Design" – if you choose to use the "Classic" theme skin, your fields will have a slightly different appearance, but all the same functions described here.

None

The field will not be shown in the running configurator. It will act simply as a variable hidden to your user byt accessible by any rule in the configurator.


Textbox

A textbox allows the user to enter plain text.

Textbox Properties

Textbox Mask

A textbox mask can be used to provide a format template that the user must follow while entering text. For example, if the mask is set to "phone", the textbox will guide the user to follow the format of a phone number.

Note that a mask is not the same as validation.

  • Validation will allow the user to enter anything, but will validate what they entered against a pattern when they exit the field.
  • A mask both constrains and guides the user as to what can be entered as they fill the field.


Multiline Textbox

Similar to the textbox, but wraps and allows line feeds for multiple lines of plaintext. The size of the textbox can be adjusted during design time and run time.

  • Run-time, by your user, by draging the bottom right handle to resize the textbox.
  • Design-time, adjust the height of the textbox in a loaded or value rule.

 

Numberbox

Similar to a textbox where the user types characters, but specifically for numeric input.  See number properties above for formatting options.


Slider

Lets the user choose a numeric value by sliding a handle through a range.  No typing required.


Sliders also follow the formatting rules set in the number properties.  For example, here is a slider with a suffix of "cm", Min = 0, Max = 1, Precision = 2, and Step = .25

Slider Properties

Allow Direct Edit

When set to true, a numberbox appears to the side of the slider, where users can enter a precise value directly.

Value Visibility

As seen in the examples above, the numeric value shown in the large baloon above the slider can be 

  • Visible
    Always shown
  • Visible when sliding
    Only shown when the user is dragging the slider handle
  • Hidden
    Never shown.

Checkbox and

Toggle

The checkbox or toggle control displays the value of a true/false (boolean) datatype.


Auto-Complete

An auto-complete control will attempt to automatically complete the word, phrase, or numeric value the user is typing. The auto-complete can be connected to a data-source (either a table or database table) to drive the available values. Epicor CPQ will search through the source data to find the best matches for what the user has typed.  Note that for database sources, creating an index on the table can enhance performance.

Auto-complete Properties

You can force that the user must choose one of the values from the source data by setting the property 'Constrain value to source' to true. If this property is false, the auto-complete will still show suggestions to the user but will ultimately allow the user to type a value that is not in the source data.

Source

The source of data for the potential values of the auto-complete.

Table / Database Table Select the name of the table or database table (depending on what you chose for the Source property) that should drive the possible values of the auto-complete.
Value Column The column from the source table or database table that should be used to drive the values of the auto-complete
Label Column (Optional) Specifies which column represents the label displayed to the user for the options. This field is optional. If no label column is specified it will label the options with the value column contents.
Image Column (Optional) A column from the source table or database table that will be used to display images from the media storage for each option in the auto-complete. A text column or image column can be selected. Note that if using a text column, it is expecting a relative path from the media folder itself (not a full url). So if you want to use an image called 'continental.png' from your media storage that is in a folder called 'vehicles', then the path should be 'vehicles/continental.png'.
Image Height Controls the height of the images in pixels
Image Width Controls the width of the images in pixels
Constrain Value to Source If unchecked, allows an end-user to manually type in a value which does not exist in the available options. If checked, the user must specify a value from an available option.


Select

The select control presents the user with options to choose from in a dropdown list.  They are limited to selecting one of the provided choices: they cannot type in a new option. A select control must have one or more options, and a value must be defined for each option. Other attributes can be set for each option to make them easier for your user to understand. 

 

value must be defined for each option, which is shown to the user if no label is provided.  The value they select is always the data stored in the field.

Provide an optional label for any option, if you want to display the option with a more understandable name.  The label appears instead of the value in the UI, but the value is stored in the field.

Provide an optional description for any choice, to help them understand the option. The description appears as smaller, italicized text in each option.

Provide an optional image reference, to represent the option visually.

Specify an optional sort column in the source data table, so the options provided appear in a specific order. If no sort is specified, then the options are presented in the same order as in the source data. For example, the options could be sorted by quantity on hand.

Optional properties do not change data.
The label, description, image, and sort properties are not required.  Regardless of these properties, only the value property is stored in the field.  For example, in each of the examples above, only "RED" is stored. 

Select control automatically offers search filter.
When the select box has more than 10 options, a search box appears above the first option, so the user can type any text to filter the options list. The search box performs a fuzzy search, with best matches appearing at the top.  For example, typing "6 x 4" (separated by spaces, which are considered word breaks) will show options matching those three words, even if the words are separate (as in the last two options listed in this example).  

Format your label text for searching.
When creating long lists of options, consider how your users may be using the search filter. Use either the space character to separate words or other characters like a dash -- or no separator at all -- in your labels so searching works for your labels.


Select Properties 
Source

Specifies the data source that the available options are filled from, either simple or option filter.

  • SimpleThe options that will appear in the select are defined in the field itself. New rows can be added to the options table by clicking the 'Add Row' button. Existing rows can be removed by right-clicking in the row and selecting "remove row".

    When using the 'Simple' source, you can also add or remove options using a snap value rule. In the example rule below, we are clearing and then setting the options of the 'Model' field when the 'Make' is equal to 'Ferrari'.


    Since the options property of the field is just an array, you can add and remove items from it using snap array blocks as well. For example, remove the first option in the 'CarModel' field (arrays are 0-indexed):

  • Option Filter: The options that will appear in the select list are defined as a separate resource, called an option filter, wich allows you to use an external table, database or other source of tabular data. Option filters offer the same four properties for each option (value, label, description, and image), but allow you to manage this data more easily.  Option filters are the preferred mode to populate your list of options, because they allow you to...
    • separate your data from your configurator.
    • re-use tables across multiple configurators.
    • join tables together with SQL-like logic.
    • easily create relationships between fields without writing any code.

Click here to learn more about option filters.

Option Filter If the source is set to 'option filter', then this specifies which option filter provides the source dataset.
Value Column Specifies which column from the dataset provides the value for each option.
Label Column (Optional) Specifies which column from the dataset provides the label for each option. If no label column is specified, then the value will be displayed.
Description Column (Optional) Specifies which column from the dataset provides the description.
Image Column

(Optional) Specifies which column from the dataset provides the image for each option. A text column or image column can be selected.

If using a text column, it is expecting a relative path from the media folder itself (not a full url). So if you want to use an image called 'continental.png' from your media storage that is in a folder called 'vehicles', then the path should be 'vehicles/continental.png'.

Sort Column (Optional) Specifies which column from the dataset should provide the sort order. Sort is in ascending order. Any rows in the datataset which are null or blank will appear as unsorted items at the top or bottom of the order.
Image Height Specifies the height of the option images in pixels.
Image Width Specifies the width of the option images in pixels.
Only show images Specifies whether the user will see both the images and the values displayed, or just the images.


Image Select

Similar to the select control, but instead of using a drop-down menu, this displays all of the options. The options are displayed in a left-to-right wrapping grid, such that when the horizontal space of a row is exhausted, subsequent options will wrap to the next row.

Image select with 'Only show images' = false


Image select with 'Only show images' = true

Image Select Properties
Only show images Controls whether the user will see both the images and the values displayed, or just the images.
Image Height Controls the height of the images in pixels
Image Width Controls the width of the images in pixels

Radio

Allows the user to select one item from a list of choices (like the Select control above), but all choices are always displayed.  This is ideal for selecting an item from a short list, where you want all choices always visible.

Unlike the radio button found in standard HTML, the Radio control also can show descriptions for each option:

Color Picker

Allows the user to pick (or enter) any color they wish from a palette of millions of colors.  The value of the field will be the hex value of the color.

Color Select

Color select properties are identical to standard select properties, with the exception of the color column.

Color Select / Swatch Select Properties
Color Column A column from the source option filter that will be used to create color swatches for each option. A text column or color column can be selected. Note that if using a text column, a hex value for the color (such as #084860) is required. Any of the 140 established HTML color names can be entered: they will be converted into hex values.

Color Select limits the user to a list of color choices you define.  The appearance is a drop-down, similar to the select control.

Swatch Select

Swatch Select is similar to color select, in that it limits the user to a list of color choices you define.  However, all choices are displayed in a horizontal layout that wraps when necessary.

Multiselect

Color Multiselect

Similar to a select box, but allows a user to select multiple values for the field, instead of just one.  This control is only available for fields that have an array datatype (like Text Array, Number array, Color array).

Image Multiselect

Similar to a multiselect, but choices are represented by images that remain on-screen instead of a drop-down list that disappears.

Image Multiselect Properties
Only show images Controls whether the user will see both the images and the values displayed, or just the images.
Image Height Controls the height of the images in pixels
Image Width Controls the width of the images in pixels
Option Layout

Wrap – (The Default layout.) An image multiselect will display choices horizontally until no more space is available, and then remaining choices will wrap to the next line. 

Horizontal – The image multiselect will be forced to show only once choice horizontally.  This can be a useful effect if you want a column of choices (using up all the horizontal space) rather than a wrapping row of choices.  This layout, however, is not dynamic and consumes more vertical space on-screen.

Horizontal Scroll – Opposite of the "Horizontal" option layout, this layout forces all choices onto one horizontal row.  If there is no more space available, then a horizontal scrollbar will appear.  Since horizontal scrollbars are not often used, the options will be spaced so that the right-most option is always only partially visible at first.  This half-seen option (for example, the "neptune" choice below) is a visual reminder to the user that scrolling is available.

Horizontal scroll can be useful for apps used predominantly on mobile devices.  In most cases, users don't expect a horizontal scrollbar.

Date Picker

Allows the user to choose a date from a calendar control.  This control is only available for fields with a data type of 'date'.  After selecting the date, the calendar widget disappears and the date selected remains.  While the data stored in a date field is always the same datetime type, you can change the way this date is shown on-screen.

Date Picker Properties
Min Date / Max Date The earliest and latest dates the user is allowed to select. Selecting a date outside of this range will automatically add a validation message to the field.
Format

The date stored is always a datetime value, granular to the second.  However, you may want to change how it is displayed to your user.  For example, a "delivery date" field should not have the time component shown.  You can specify a format pattern to control how the value appears on-screen. The possible characters in the pattern are:

Character Description Example
d Day of the month, 2 digits with leading zeros 01 to 31
D A textual representation of a day Mon through Sun
l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday
j Day of the month without leading zeros 1 to 31
J Day of the month without leading zeros and ordinal suffix 1st, 2nd, to 31st
w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
F A full textual representation of a month January through December
m Numeric representation of a month, with leading zero 01 through 12
n Numeric representation of a month, without leading zeros 1 through 12
M A short textual representation of a month Jan through Dec
U The number of seconds since the Unix Epoch 1413704993
y A two digit representation of a year 99 or 03
Y A full numeric representation of a year, 4 digits 1999 or 2003

Examples

Following are some examples of different formats and their resulting text for a date of April 28th, 2017, 07:30 AM

Format Result
Y-m-d 2022-04-28
Y-n-d 2022-4-28
m-d-y 04-28-22
M j, Y Apr 28, 2022
F J, Y April 28th, 2022
l F J, Y Friday April 28th, 2022



File Upload

Allows a user to upload a file to this specific field. This file will be bound to the field, plus be automatically attached to the quote product after it has been added to the quote. From there, it can be included in other output builds. Common use-cases would be...

  • your user wants to upload their own image to use as a label or etching in the product they are configuring.
  • your user wants to attach a PDF or Word document they created that is required as part of the sale (such as a Letter of Understanding they signed, or a picture of the site where the product will be installed).
File Upload Properties
Accepted File Types The file types to allow for the upload. Use the convention for the accept attribute described here: https://www.w3schools.com/TAGS/att_input_accept.asp


Tags A list of tags to automatically tag the attached file with.  Tags help ensure this file is visible to the correct users after the configured product is submitted into a workflow.
Convert PDF to image Set this to true, and the first page of the PDF uploaded will be converted into an image as well. This can be useful to allow a customer to upload a PDF which then can appear in a 3D Scene.

The "FileIsUploaded" SNAP block can help you determine if a File Upload field is set to a value, or if it is null.


Was this article helpful?