Much like the ext.json file defines meta-data for an extension, a widget.json file defines meta-data for a widget. An example of a widget.json file is provided below:

  "version": 1,
  "global": false,
  "javascript": "widget-type-js",
  "i18nresources": "widget-type",
  "availableToAllPages": true,
  "jsEditable": true,
  "config": {
  "translations" : [
      "language": "en",
      "name": "Name in English"
      "language": "de",
      "name": "Name in German"

The following list describes all the properties that you might choose to include in a widget.json file.

  • javascript: The name of the widget’s main JavaScript file, to which .js is appended, to load in the storefront. The convention is to use the widget-type as the JavaScript module name without the .js suffix. This property is required if the widget includes one or more JavaScript files and should refer to the main JavaScript file for the widget. Other JavaScript files can be defined as dependencies in the main JavaScript file. See Include multiple JavaScript files for more details.

  • jsEditable: A flag that determines whether it is possible to edit the widget’s JavaScript code within the Design page. Defaults to false.

  • i18nresources: The namespace name for the resources of this widget, to which ns is prepended and .json is appended. The convention is to use the widget-type for this property, creating a file with a name like ns.widget-type.json. This property is required if the widget has resource files. See Localize a widget for more information.

  • imports: By default, widgets have access to data and functions contained in the common view models (user, cart, order and so on). However, in order for a widget to have access to page-specific view models, those view models must be explicitly defined in the imports property. The possible values that are acceptable for the imports property depends on the type of page the widget will be placed on. See Acceptable values for the imports property for detailed information.

  • availableToAllPages: Set this property to true to allow the widget to be placed on all page types; the widget will appear in the Component library for all pages. Omit this property altogether to restrict placement of the widget to the page types defined in the pageTypes property. Also, omit this property for global widgets (see the global property below). Note that this property and the pageTypes property are mutually exclusive but one of them must be set.

  • pageTypes: Defines which page types the widget can be placed on; the widget will appear in the Component library for the specified pages. If you use this property, you must omit the availableToAllPages property. Note that this property and the availableToAllPages property are mutually exclusive but one of them must be set.

    Available page types include:

    • product

    • category

    • home

    • cart

    • checkout

    • confirmation

    • article

    • error

    • searchResults

    • noSearchResults

    The widget will appear in the Component library for the page types you specify.

  • translations: An array that provides translations for the widget name. This name is displayed in the Components library panel that you use to add a widget to a page layout. Note that either the translations property or the name property, described below, is required.

    The translations property has two sub-properties, language and name. The language property can be either a two-letter language code (for example, en) or a two-letter language code and a two-letter country code with an underscore in between (for example, en_US). ISO 639-1 defines the two-letter language codes. ISO 3166-1 alpha-2 defines the two-letter country codes.

  • version: Specifies the version of the widget, used to ensure the right version of a widget is used in the storefront. See Understand widget versioning for more information. Defaults to 1.

  • name: If your storefront only uses one language, meaning you do not need multiple translations for the name of the component, you can choose to use the name property instead of the translations property. Note that one of the two properties is required.

  • global: Defines the widget as a global widget. A global widget does not include a display template. It is automatically added to all pages but, due to the lack of template, it is excluded from template rendering. Global widgets are useful for tasks like logging web analytics or loading JavaScript libraries. Defaults to false.

  • minWidth: The minimum width that this widget will fit into it. The system will check if the widget will fit in the region in Grid View.

  • hiddenFromSiteStudio: A Boolean that determines whether the widget’s initial state is to be hidden or not in the Component library. Set to false by default. See “Customize your component library widgets” in Using Oracle Commerce Cloud for details on showing or hiding widgets in the Component library.

Copyright © 1997, 2017 Oracle and/or its affiliates. All rights reserved. Legal Notices