Create Custom Fields by Customizing Templates
You can configure your site and customize template files as part of a theme to render information or ask for information stored in these fields on your web store’s Shopping, Checkout, and My Account pages.
If you are using SuiteCommerce or the Aconcagua release of SCA or later, you implement custom fields as part of a theme. See Develop Themes for details on creating themes.
If you are implementing the Kilimanjaro release of SCA and earlier, you implement custom fields by customizing the core SCA source code. See Develop Your SCA Customization for details.
You can set up custom item, custom transaction body, and custom transaction column and transaction item option fields in SuiteCommerce and SCA by customizing the template files:
Set Up Custom Item Fields
Set up custom item fields to appear in the PDP, Checkout, and My Account. This requires setting up the custom item field in NetSuite and overriding the correct template to render the information in your web store.
To set up a custom item field in NetSuite:
-
In NetSuite, create the custom item field. See Creating Custom Item Fields for details.
Note:The custom item field information rendered to your web store is read-only.
For a custom item field to render in your Commerce website, note the following:
-
Enter a Label and ID for your custom item. If you do not specify an ID, NetSuite will create one for you. Use these when adding field sets and customizing templates.
-
Set the Subtype (Applies To subtab) to either Both or Sale.
-
-
In NetSuite, go to Setup > SuiteCommerce Advanced > Set Up Web Site and click edit next to your site.
-
In the Web Site record, click Actions > Rebuild Search Index and wait for the index to build.
-
On the Field Sets tab, perform the following as applicable:
-
If adding the field to the PDP, locate the Details field set name and add the custom field ID to the Fields Included in Field Set column.
-
If adding the field to Checkout or the Purchase History page of My Account, add the field ID to the Order field set name and add the custom field ID to the Fields Included in Field Set column.
Note:The order field set is the default for the Review Order page, but you can change this by editing the
fieldKeys.itemsFieldsAdvancedName
property in the SuiteCommerce Configuration Record. See Backend Subtab for details. -
To display the custom item field in the PDP or in Checkout:
-
As part of your theme, update the appropriate template:
-
product_details_full.tpl
– exposes the field as read-only information to the PDP. -
transaction_line_views_cell_navigable.tpl
– exposes the field as read-only information to the Review Your Order page and in the Order Summary information displayed throughout Checkout.
See Develop Themes for details on creating themes.
Note:If you implementing a SuiteCommerce Advanced site using the Kilimanjaro release or earlier, you must override the appropriate template. See Develop Your SCA Customization for details.
-
-
Add the following code to any HTML tag within the template that does not have the
data-view
attribute:{{model.item.custitem_my_custom_field_id}}
In this example,
custitem_my_custom_field_id
is the ID of your custom item fieldNote:If the custom field record’s Type is set to Multiple Select, the values render on your site separated by commas.
-
Save your code and test on a local server or deploy to NetSuite and activate as required.
To display the custom item field in My Account:
-
As part of your theme, update the
transaction_line_views_cell_actionable.tpl
template.See Develop Themes for details on creating themes.
Note:If you implementing a SuiteCommerce Advanced site using the Kilimanjaro release or earlier, you must override the appropriate template. See Develop Your SCA Customization for details.
-
Add the following code to the template wherever you want the field to appear:
{{model.item.custitem_my_custom_field_id}}
In this example,
custitem_my_custom_field_id
is the ID of your custom item field -
Save your code and test on a local server or deploy to NetSuite and activate as required.
Set Up Custom Transaction Body Fields
Set up custom transaction body fields to appear in Checkout and My Account. This requires setting up the custom transaction body field in NetSuite and overriding the correct template to render the information in your web store.
To set up a custom transaction body field:
-
In NetSuite, set up the custom transaction body field. See Creating Custom Transaction Body Fields for details.
For a custom transaction body field to render in your Commerce website, note the following:
-
Create a Label and ID for your custom item. If you do not specify an ID, NetSuite will create one for you. Use these when configuring your site and customizing templates.
-
Check Sale and Web Store (Applies To subtab).
-
SCA supports the Mandatory option in the Validation & Defaulting subtab, but as information only. Transaction body fields are not validated in the frontend (client side). If a custom transaction body field is setup as mandatory, the field will be required for Quotes as well.
-
-
In NetSuite, go to Commerce > Websites> Configuration.
-
In the Advanced tab and Custom Fields subtab, add your transaction body field ID to the Sales Order property. See Custom Fields Subtab for more information about this configuration property.
Note:If any transaction body fields where available in the Vinson release of SCA or earlier, you must expose them in the configuration as well.
To display the custom transaction body field:
-
You can add a custom transaction body field to any module template linked to a checkout wizard step or in the Purchase History pages of My Account. See Supported Field Types for a list of supported field types.
As part of your theme, update the appropriate template:
-
To render information in Checkout, override any applicable checkout wizard template.
-
To render the information in My Account, override the
order_history_details.tpl
or theorder_history_summary.tpl
, as required.
See Develop Themes for details on creating themes.
Note:If you implementing a SuiteCommerce Advanced site using the Kilimanjaro release or earlier, you must override the appropriate template. See Develop Your SCA Customization for details.
-
-
In your template, you can include the custom field’s metadata as an option. This is important for rendering the label of a field, for example. The
label
,type
, andmandatory
metadata components apply to all supported transaction body field types. Theoptions
metadata component applies to List/Record types only.Note:After changing the
type
,label
, ormandatory
attributes of a transaction body field, your site uses the metadata values for up two hours. If you configure a new transaction body field, and that field’s attribute is not in the cache, the cache reloads, attempting to get the requested metadata. If the Sales Order Field ID property does not belong to any transaction body field, the application does not render that field.To display metadata for the custom field, include the following helpers (where
custbody_my_transaction_body_field
is the ID of your custom transaction body field):Note:The metadata is available in the Sales Order object as part of the
__customFieldsMetadata
attribute. In your template override, access custom field metadata by introducing the following script (wherecustbody_my_transaction_body_field
is the ID of your custom transaction body field).Metadata Fields
Information
Script
Label
Display the label of the field
model._
_customFieldsMetadata.custbody_my_transaction_body_field.label Type
Display the type of the field
model._
_customFieldsMetadata.custbody_my_transaction_body_field.type Mandatory
Display the Mandatory field. This is information only and is not validated in the frontend (client side).
model._
_customFieldsMetadata.custbody_my_transaction_body_field.mandatory Options
Display the options for a List/Record field.
model._
_customFieldsMetadata.custbody_my_transaction_body_field.options -
To display the value of a transaction body field, include the following helper (where
custbody_my_transaction_body_field
is the ID of your custom transaction body field):{{model.options.custbody_my_transaction_body_field}}
-
To request information from a user, include an
input
,textarea
, orselect
component (where thename
property is the custom field ID). Whenever the Change event is triggered on the field, the value of the HTML component is set in the model associated with the template.The following examples use the Label metadata to display the label of the custom TBF:
<div> {{model.__customFieldsMetadata.custbody_my_transaction_body_field.label}}: <input type="text" name="custbody_my_transaction_body_field" value="{{model.options.custbody_my_transaction_body_field}}"> </div>
<div> {{model.__customFieldsMetadata.custbody_my_transaction_body_field_sel.label}} <select name="custbody_my_transaction_body_field_sel"> {{#each model.__customFieldsMetadata.custbody_my_transaction_body_field_sel.options}} <option value="{{id}}" {{#ifEquals id ../model.options.custbody_my_transaction_body_field_sel}}selected="true"{{/ifEquals}}> {{text}} </option> {{/each}} </select> </div>
<div> {{model.__customFieldsMetadata.custbody_my_transaction_body_field_2.label}} <textarea name="custbody_my_transaction_body_field_2"> {{model.options.custbody_my_transaction_body_field_2}} </textarea> </div>
Supported Field Types
Commerce websites support custom transaction body fields of the following Type:
Type |
Example HTML5 Elements Used to Render the Field |
---|---|
Check Box |
text, checkbox |
Currency |
text |
Date |
text, date |
Date/Time |
text, datetime |
Decimal Number |
text, number |
Document |
select |
Email Address |
text, email |
Free Form Text |
text |
Hyperlink |
url |
Inline HTML |
text |
Integer Number |
text, number |
List/Record |
input, select |
Long Text |
text |
Multiple Select |
select |
Password |
text, password |
Percent |
text |
Phone Number |
text, tel |
Rich Text |
text |
Text Area |
text, textarea |
Time of Day |
text, time |
Set Up Custom Transaction Line and Transaction Item Option Fields
Set up custom transaction line fields to appear in your PDP, Cart, Checkout, and My Account. This requires setting up the custom fields in NetSuite. Commerce websites include a set of default templates (listed below) to render these fields, but you can override these as required.
-
product_views_option_color.tpl
-
product_views_option_dropdown.tpl
-
product_views_option_radio.tpl
-
product_views_option_text.tpl
-
product_views_option_textarea.tpl
-
product_views_option_email.tpl
-
product_views_option_phone.tpl
-
product_views_option_currency.tpl
-
product_views_option_float.tpl
-
product_views_option_integer.tpl
-
product_views_option_percent.tpl
-
product_views_option_password.tpl
-
product_views_option_url.tpl
-
product_views_option_timeofday.tpl
-
product_views_option_datetimetz.tpl
-
product_views_option_tile.tpl
-
product_views_option_checkbox.tpl
-
product_views_option_date.tpl
Transaction line fields and transaction item options render in the same locations on your site. To set up these fields, follow the same set up and configuration procedures and customize the same template file.
To set up a Custom Transaction Line and Transaction Item Option:
-
In NetSuite, set up the transaction line field or transaction item option. See Creating Custom Transaction Line Fields and Creating Custom Transaction Item Options for details.
For a custom transaction line or transaction item option to render in your Commerce website, note the following:
-
Enter a label and ID for your custom item. If you do not specify an ID, NetSuite will create one for you. Use these when customizing templates to render the field.
-
To enable a custom transaction line field to render in the PDP, check Sale Item and Store Item (Applies To subtab).
-
To enable a custom transaction item option to render in the PDP, check Sale and Web Store (Applies To subtab).
-
SCA supports the Mandatory option in the Validation & Defaulting subtab. Some of these fields are validated in the frontend (client side). Others are validated in the backend.
-
SCA does not support all transaction item option types.
-
All the transaction line fields and item options are displayed automatically if the Show Only Items Listed in: ItemOptions and Custom Transaction Line fields property is unchecked. Enabling this property only displays fields with the ID specified in the item options and custom transaction line field’s
Item options and custom transaction line fields
property.
-
-
In NetSuite, go to Commerce > Websites > Configuration.
-
In the Shopping Catalog tab and Item Options subtab, check the Show Only Items Listed in: Item Options and Custom Transaction Line Fields property and set up your item options fields to display. See Item Options Templates Subtab for more information.
Supported Field Types
Commerce websites support transaction line fields and transaction item options of the following Type:
Some of these fields are validated on the frontend (client side). Others are validated on the backend (NetSuite). Invalid fields in the frontend result in error messages displayed at the field where the error occurred. Invalid fields in the backend result in error messages at the top of the page.
Type |
Validation |
Example HTML5 Elements Used to Render the Field |
---|---|---|
Check Box |
Backend |
checkbox |
Currency |
Frontend |
text |
Date |
Backend |
date, datepicker (Bootstrap) |
Date/Time |
Backend |
text |
Decimal Number |
Frontend |
number |
Email Address |
Frontend |
|
Free Form Text |
Frontend |
text |
Hyperlink |
Frontend |
url |
Integer Number |
Frontend |
number |
List/Record |
Frontend |
input, select |
Password |
Backend |
password |
Percent |
Frontend |
text |
Phone Number |
Frontend |
tel |
Text Area |
Frontend |
textarea |
Time of Day |
Backend |
text |