Work with widgets

Widgets, which are a type of server extension, provide functionality that is deployed on pages of the agent’s console.

Widgets allow you to display content to your agents or to execute specific functions. Widgets are comprised of templates, JavaScript, CSS, locale resources and images. For detailed information on widgets and extensions, refer to the Developing Widgets guide.

When you customize widgets, you create functionality that appears on your website pages. These widgets allow you to add pre-made and pre-configured snippets of text or information to your web pages without having to recreate them for each page. Widgets also allow you to extend the functionality of your storefront by communicating with the Oracle CX Commerce Agent server to access a variety of features.

You can use agent-specific widgets to create a customized agent environment. Widgets are comprised of a set of resource and source files. Using these files, as well as auxiliary files that contain information such as meta-data, you can customize an agent’s environment.

The agent environment uses agent-specific widgets, as well as Oracle Cloud Commerce storefront widgets. There are separate instances for agent and storefront widgets. Note that these instances differ in the template, and sometimes the configuration properties, they use. If you delete an agent widget instance, which uses a different template than the Display template, you will be unable to recreate the widget.

Important: Please note that Oracle CX Commerce Agent Console, unlike Oracle CX Commerce Storefront, does not support application JS, global widgets, or global elements. Any element used in default widgets should be downloaded and customized.

Tasks done by widgets

The following are some general tasks that can be performed by widgets:

Agent Navigation - Enables an agent to navigate throughout the console to review a variety of data. Additionally, you can rename fields and buttons, and hide or display certain fields or navigational items. For information on working with navigation in the Agent Console, refer to Navigate the Agent Console. Configure customer and order searchFor information on working with agent navigation widgets, refer to the Work with Navigation Widgets section.
Search - Allows an agent to search for customers, orders or returns. For information on using Search in the agent console, refer to For information on working with agent search widgets, refer to the Configure Search Widgets section.
Create Orders - You can display navigation, customer cart dialog, shipping details, address books, promotions, loyalty details, scheduled orders and product details, in addition to other displays. For information on working with agent order widgets, refer to the Create and Edit Orders Widgets section.
Order Details - You can create widgets to display order details for account orders, return and exchange orders, quotes and order approvals. You can also customize carts to show subtotals and logic for payment and pricing. For information on working with order details widgets, see Order Details. For information on working with agent order detail widgets, refer to Review order details during checkout.
Customer Details - You can create customized widgets to display account addresses and details, customer profile information, order histories, purchase lists, account contacts and other profile information. For information on working with agent customer details widgets, refer to the Work with Customer Information Widgets section.
Returns and Exchanges - You can create widgets that display or create return requests and refunds, as well as process returns. You can also create widgets that create exchanges. For information on working with returns and exchange-specific widgets, Return Items. For information on working with agent returns and exchanges widgets, refer to the Configure Returns and Exchanges Widgets section.

This documentation provides the following information for each widget:

Description- A description of the widget.
Widget Name - The code name of the widget. The name of the widget is identified in the widget.json file. For example:
```
"javascript": "agent-order-search",
"widgetFamily": "agentOrderSearch",
"widgetType": "agentOrderSearch"
```
Display Name - The widget’s name as displayed in the Design page. The display name can also be found in the widget.json file:
```
"name": "Order Search - Agent"
```
Supported Page Type - The types of pages that the widget can be applied to. This is also identified in the widget.json file:
```
"pageTypes": ["agentOrderSearch"],
```
For information on page types, refer to Define stack meta-data in stack.json.
Layouts - The page layouts that this widget is associated with. A widget’s associated layouts are identified on the Layout tab of the Design page. For detailed information on layouts, see Create Page Layouts that Support Different Types of Shoppers.
Elements - The elements used by this widget. Each element represents a single piece of the structure of the widget. Elements can be configured as drag-and-drop sub-components, which allow you to control their location on a page’s layout. Elements are added to the widget’s display.template file and can be reviewed using the Design tab code view.
For detailed information on elements, see Fragment a Widget into Elements.

For information on Storefront widgets refer to Appendix: Layout Widgets and Elements.

Access widgets

You can review Oracle CX Commerce default widgets by opening the Design page on your administration server. This page displays both the layouts that are used in the agent console, but also the components, such as widgets, that are available. Click the Component tab to see the list of widgets.

Each widget displays the associated page layouts. By selecting the page layouts, you can customize the pages by adding or removing widgets. For information on working with widgets and layouts, see Appendix: Layout Widgets and Elements.

Note that widgets that are specific to the agent console contain the word “Agent”. The agent console also uses a number of widgets that are also used by the Storefront.

Extend functionality with widgets

You can customize widgets by downloading the widget source code and making modifications to the JavaScript and HTML files. For example, you could add custom JavaScript to an existing widget. Once you have made all of your changes, you then upload the widget by adding it to an extension as described in Understand Extension Features.

Important: When creating or renaming a widget, ensure that the name is less than 50 characters. Errors will occur if the widget name is greater than 50 characters.

You can also extend a widget’s JavaScript by using the JavaScript Code Layering feature that allows you to layer custom JavaScript on top of the widget. For information on the JavaScript Code Layering feature, see Use the JavaScript Code Layering User Interface feature.

Note: For a widget’s JavaScript code to be editable, ensure that the jsEditable flag in the widget.json file is set to true. By default, the flag is set to false, indicating that the JavaScript associated with the widget cannot be edited.

When you upgrade or modify a widget, you must remove any existing instances of it from the page layouts and replace it with the new widget.

Upgrade widgets

Widgets that have been deployed are not automatically updated when a newer version of the widget is released. This allows you to customize widgets without the fear of them being overwritten. To update a widget, you must remove the old widget from all of your page layouts and replace them with the new widget. Additionally, you must recreate templates or style sheets that you have customized for the new widget.

For detailed information on how to upgrade widgets, see Customize your store layouts.

Migrate widgets with multiple templates

Some widgets use more than one template. If you migrate your widgets and load the latest version of the widget, the agent-specific template is not available for newly created widget instances. To update the widget with the new version, you must ensure that the widget's new template file is recognized by the layout.

To do this, perform the following steps:

Open the widget in the administrative interface using the Settings icon.
Open the About tab. Click the Go to widget code button.
Click the Download Source button.
Unzip the file that you downloaded.
Open the /widget/widgetName/layouts/layoutThatContainsTheLayout file and copy the contents of the newer version of the widget-layoutAndVersion.template file.
For example, you might copy the widget-orderDetailsDefaultLayout_v3.template file.
Return to the administrative interface from where you downloaded the source. In the Template tab, replace the existing code with the code you have copied from the new version of the widget.template file.
Click Save.
Ensure that you update the associated layouts.

Migrate widget with multiple LESS files

If you have recently migrated, your widgets will be listed in the page layout components. However, if you use a widget in a page layout region, and then create a new widget instance, the widget instance will be created with the default template, which won't be applicable to the page layout. To update these widgets, perform the following steps:

Open the widget in the administrative interface using the Settings icon.
Open the About tab. Click the Go to widget code button.
Click the Download Source button.
Unzip the file that you downloaded.
Open the /widget/widgetName/less/ file and copy the contents of the newer version of the widget.less file.
For example, you might copy the widget-agentAccountOrderDetailsInst_v4.less file.
Return to the administrative interface from where you downloaded the source for the widget. In the Style Sheet tab, replace the code with the code you have copied from the new version of the LESS file.
Click Save.
Ensure that you update the associated layouts.

Recreate shared widgets after deletion

Some widgets also have corresponding storefront widgets. These widgets, although designed to perform similar tasks, use different templates and, sometimes, configuration properties. If an agent-specific widget is deleted, and the agent widget uses a different template than the storefront widget, you will not be able to recreate the widget from the administrative interface.

To rectify this, download the agent-specific widget and recreate the template for the instance.