Create Custom Fields by Customizing Templates

This topic applies to

Applies to

SuiteCommerce Web Stores | SuiteCommerce Advanced

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 Aconcagua and later, you implement custom fields as part of a theme. See Themes for details on creating themes.

If you are using SuiteCommerce Advanced, you implement custom fields by customizing the core SCA source code. See Customize and Extend Core SuiteCommerce Advanced Modules for details.


You can set up custom item, custom transaction body, and custom transaction column and transaction item option fields in SuiteCommerce 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:

Note

The custom item field information rendered to your web store is read-only.


  1. In NetSuite, create the custom item field. See the help topic Custom Item Fields for details.

    For a custom item field to render in your SuiteCommerce web store, 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 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 Customize and Extend Core SuiteCommerce Advanced Modules 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 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 Customize and Extend Core SuiteCommerce Advanced Modules 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 the help topic Custom Transaction Body Fields for details.

    For a custom transaction body field to render in your SuiteCommerce web store, 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 Setup > SuiteCommerce Advanced > 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:

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.

  1. 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 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 Customize and Extend Core SuiteCommerce Advanced Modules 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

SuiteCommerce supports 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. SuiteCommerce provides 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 the help topics Custom Transaction Line Fields and Custom Transaction Item Options for details.

    For a custom transaction line or transaction item option to render in your SuiteCommerce web store, 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 Setup > SuiteCommerce Advanced > 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 Subtab for more information.

Supported Field Types

SuiteCommerce supports 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