Widgets

Use widgets in any Customer Service Center customizable area. Commonly used widgets include attribute_layout, attribute_form, attribute_listing, text, link, and tabs.

Widgets are always named directly and configured by registering them with a type.

NameTypeDescription
configobjectan object that contains widget-specific configurations
typestringthe required widget type

Example of widget registration:

Details on customizing each widget are included in the remaining sections of this guide.

The attribute_form widget provides a form element for attributes depending on metadata. The metadata are either derived from attributes or through metadata overwrite in layout.

The attribute_form widget is only configured through layout and its subelements.

With the customization, it's also possible to override the metadata of attributes to:

  • Provide or restrict options of values, for example, the state codes for certain countries
  • Change the type, format or constraints of attributes, for example, the format of the credit card expiration month or the maximum input length
  • Mark an attribute as required

This table lists the options of overriding meta data.

label

Metadata can be adjusted to show different localized text as coming from the Salesforce B2C Commerce platform metadata

required

If an attribute is required in a form, it can be marked accordingly for mark in the UI and verify it.

disabled

A form element can be disabled for read-only purposes with disabled.

type & format

The format attribute lets you override the default display, for example, to show a string in a textbox only. ("format": "text")

The format requires an explicit type declaration.

Currently supported are:

  • string: text, password, email, html, null, date, date-time, and time

  • number: int32, int64, float, double, byte, and null

  • integer: int32, int64, byte, and null

maxLength

The maximum length of an attribute can be restricted with maxLength.

enum

The configuration of an attribute_form widget allows the override of enumeration values to either limit enum values in a certain dropdown based on conditions or localize values differently.

The current example would lead to a dropdown with three items (Price Match, Appeasement, Other) regardless the number of items declared in the meta data. The condition makes sure that this enum is active for product level only.

Each enum element has a separate label attribute including localization.

regex

The attribute form widget recognized regex configured in the meta data. The values can be overwritten if they are more specific to CSC.

dynamic_enum

The dynamic_enum option refers to a particular property that contains the allowed values for a certain attribute. Those values could be determined during the request processing.

For example, To avoid errors when entering the state code, the state code values are provided as a selection for the US. For Canada and France, a simple input field is shown:

The attribute_layout widget prints the content of a certain attribute.

This widget is only configured through layout and its subelements and needs only a simple widget registration. The following example shows how the attributes first_name, last_name, postal_code, and city can be arranged in a layout using the default width, which results in a line break after each attribute.

This example result in the following view of the billing address at an order, in which the grid distributes the cells automatically.

The attribute_listing widget can show system and custom attributes in either one, two or three columns in the order of the configuration.

NameTypeDescription
columnsintegerthe number of columns (1, 2, or 3) to use
attributesarray of stringsthe attributes to display
show_emptyBooleanwhether an attribute appears when no value's defined default is false

A link widget shows a link with an href and text information.

Use the tabs widget to place tabs somewhere in the layout. Each tab can be of type widget_tab or form_tab.

Tabs can contain available widgets and forms.

NameTypeDescription

type

string

Declares the type of tab:

  • widget_tab - to reference a widget directly

  • form_tab - to reference a particular configured area

caption

 

a template to define localized meta data

config

 

A configuration for form_tab tabs:

  • area_id (string): Specifies the area id to appear in this tab.

  • default_data_provider (string): A data provider to access the data in the form

  • query_params (Boolean): query params for the particular data provider

The main layout section needs a reference to the tabs widget only to show the configured tabs with their content.

The text widget shows localized and parametrized text.