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.

Important:

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 Transaction Body Fields

• Set Up Custom Transaction Line and Transaction Item Option Fields

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:

1. 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, observe 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.

2. In NetSuite, navigate to Setup > SuiteCommerce Advanced > Set Up Web Site and click edit next to your site.

3. In the Web Site record, click Actions > Rebuild Search Index and wait for the index to build.

4. 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:

1. 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.

2. 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 field

   Note:

   If the custom field record’s Type is set to Multiple Select, the values render on your site separated by commas.

3. 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:

1. 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.

2. 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

3. 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:

1. 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, observe 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 mandatory for Quotes as well.

2. In NetSuite, go to Commerce > Websites> Configuration.

3. 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 on 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:

1. 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 the order_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.

2. 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, and mandatory metadata components apply to all supported transaction body field types. The options metadata component applies to List/Record types only.

   Note:

   After changing the type, label, or mandatory 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 (where custbody_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

3. 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}} 
   
                   

4. To request information from a user, include an input, textarea, or select component (where the name 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

Note:

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:

1. 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, observe 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.

2. In NetSuite, navigate to Commerce > Websites > Configuration.

3. 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:

Note:

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	email
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

Related Topics

Commerce Custom Fields

Create Custom Fields Using an Extension

General Notices