Web Components can contain CSS, HTML, JavaScript, and metadata files that you can modify according to your app requirements.

Slots are used as placeholders in a Web Component that users can fill in with their markup. Slot is defined in the component JSON file of your Web Component.

<div class="oj-flex oj-flex-item-pad">
  <div role="group" :aria-label="[[$properties.headers[0]]]"
   class="oj-flex-item demo-columns-col-a oj-flex oj-sm-flex-direction-column oj-sm-align-items-center">
    <h3>
			<oj-bind-text value="[[$properties.headers[0]]]"></oj-bind-text>
		</h3>
		<oj-bind-slot name="columnA">
		</oj-bind-slot>
 	</div>
  ... content omitted
</div>

<demo-columns id="composite-container" headers='["Sales", "Human Resources", "Support"]'>
  <!-- ko foreach: sales -->
    <demo-card slot="columnA" name="[[name]]" work-title="[[title]]"></demo-card>
  <!-- /ko -->
  ... contents omitted
</demo-columns>

You can define placeholders in your template using template slots that can be filled with any markup fragment you want when the template element is used within a markup of your component.

<table>
  <thead>
    <tr>
      <th>
        <oj-bind-text value="[[$properties.header]]"></oj-bind-text>
      </th>
    </tr>
  </thead>
  <tbody>
    <oj-bind-for-each data="{{$properties.data}}">
      <template>
        <tr>
          <td>
            <!-- Template slot for list items with default template and an optional alias -->
            <oj-bind-template-slot name="item" data="{{'value': $current.data}}">
              <!-- Default template -->
              <template data-oj-as="listItem">
                <span>
                 <oj-bind-text value='[[listItem.value]]'</oj-bind-text>
                </span>
              </template>
            </oj-bind-template-slot>
          </td>
        </tr>
      </template>
    </oj-bind-for-each>
  </tbody>
  ... contents omitted
</table>

<demo-list data="{{groceryList}}" header="Groceries">
 <template slot="item" data-oj-as="groceryItem">
   <oj-checkboxset>
     <oj-option value="bought"><oj-bind-text value='[[groceryItem.value]]'></oj-bind-text></oj-option>
   </oj-checkboxset>
 </template>
... contents omitted
</demo-list>

Oracle JET Web Components can fire automatic property changed events that are mapped to the properties defined in the component metadata. These components will also fire custom events for the events delared in the component metadata.

<oj-element-name value="{{currentValue}}" on-value-changed="{{valueChangedListener}}"></oj-element-name>

elementName.addEventListener("valueChanged", function(event) {...});

elementName.onValueChanged = function(event) {...};

Web Components can contain slots, data binding, template slots, nested Web Components, and events. You can use the examples provided in the Oracle JET Cookbook for these Web Component features.

Recommended patterns and coding practices for Oracle JET Web Components include standards for configuration, versioning, coding, and archival.

"properties" : {
  "translations": {
    "description": "Property to allow override of default messages",
    "writeback" : false, 
    "properties" : {
      "requiredHint": {
        "description": "Change the text of the required hint", 
        "type": "string"
         },
      "requiredMessageSummary": {
        "description": "...",
        "type": "string"
        },  
      "requiredMessageDetail": {
          "description": "...",
          "type": "string"
        } 
      }
     } 
   }
}

<div data-bind="ojModule: {require: {instance: require_instance, viewPath: "path_to_Web_Component_Views", modelPath: "path_to_cWeb_Component_ViewModels"}}"></div> 

Use the Oracle JET command-line interface (CLI) to create an Oracle JET Web Component template implemented as JavaScript or TypeScript that you can populate with content. If you’re not using the tooling, you can add the Web Component files and folders manually to your Oracle JET app.

The following image shows a simple Web Component named demo-card that displays contact cards with the contact’s name and image if available. When the user selects the card, the content flips to show additional detail about the contact.

Description of the illustration ui_composite_basic.png

The procedure below lists the high level steps to create a Web Component using this demo-card component as an example. Portions of the code are omitted for the sake of brevity, but you can find the complete example at Web Component - Basic. You can also download the demo files by clicking the download button () in the cookbook.

Before you begin:

• Familiarize yourself with the steps to install the Oracle JET CLI, see Install Oracle JET Tooling.
• Familiarize yourself with the steps to add a Web Component to an Oracle JET app using the Oracle JET CLI, see Understand the Web App Workflow.
• Familiarize yourself with the list of reserved names for a Web Component that are not available for use, see valid custom element name.

• Familiarize yourself with the list of existing Web Component properties, events, and methods, see HTMLElement properties, event listeners, and methods.

• Familiarize yourself with the list of global attributes and events, see Global attributes.

To create a Web Component:

1. Determine a name for your Web Component.
   The Web Component specification restricts custom element names as follows:

   • Names must contain a hyphen.

   • Names must start with a lowercase ASCII letter.

   • Names must not contain any uppercase ASCII letters.

   • Names should use a unique prefix to reduce the risk of a naming collision with other components.

     A good pattern is to use your organization’s name as the first segment of the component name, for example, org-component-name. Names must not start with the prefix oj- or ns-, which correspond to the root of the reserved oj and ns namespaces.

   • Names must not be any of the reserved names. Oracle JET also reserves the oj and the ns namespace and prefixes.

   For example, use demo-card to duplicate the contact card example.

2. Determine where to place your Web Component, using one of the following options.

   • Add the Web Component to an existing Oracle JET app that you created with the Oracle JET CLI.

     If you use this method, you’ll use the CLI to create a Web Component template that contains the folders and files you’ll need to store the Web Component’s content.

   • Manually add the Web Component to an existing Oracle JET app that doesn’t use the Oracle JET CLI.

     If you use this method, you’ll create the folders and files manually to store the Web Component’s content.

3. Depending upon the choice you made in the previous step, perform one of the following tasks to create the Web Component.

   • If you used the Oracle JET CLI to create an app, then in the app’s top level directory, enter the following command at a terminal prompt to generate the Web Component template:

     ojet create component component-name

     For example, enter ojet create component demo-card to create a Web Component named demo-card in a base app created with JavaScript. The command will add jet-composites/demo-card to the app’s js folder and files containing stub content for the Web Component.

     
     Description of the illustration composite_files.png

     The base app's implementation of JavaScript or TypeScript determines the folder and implementation of the Web Component. If your base app has a TypeScript implementation, then the ts folder, not the js folder, contains the stub contents of the Web Component.

   • If you’re not using the Oracle JET CLI, create a jet-composites folder in your app’s js folder or ts folder, and add folders containing the name of each Web Component you will create.

     For the demo-card example, create the jet-composites folder and add a demo-card folder to it. You’ll create the individual Web Component files in the remaining steps.

4. Determine the properties, methods, and events that your Web Component will support and add them to the component.json file in the Web Component’s root folder, creating the file if needed.
   The name of the Web Component properties, event listeners, and methods should avoid collision with the existing HTML element properties, event listeners, and methods. Additionally, the property name slot should not be used. Also, you must not re-define the global attributes and events.

   The demo-card example defines properties for the Web Component and the contact’s full name, employee image, title, work number, and email address. The required properties are highlighted in bold.

    {
     "name": "demo-card",
     "description": "A card element that can display an avatar or initials on one side and employee information on the other.",
     "version": "1.0.2",
     "displayName": "Demo Card",
     "jetVersion": ">=6.0.0 <17.1.0",
      "properties": {
       "name": {
         "description": "The employee's full name.",
         "type": "string"
       },
       "avatar": {
         "description": "The url of the employee's image.",
         "type": "string"
       },
       "workTitle": {
         "description": "The employee's job title.",
         "type": "string"
       },
       "workNumber": {
         "description": "The employee's work number.",
         "type": "number"
       },
       "email": {
         "description": "The employee's email.",
         "type": "string"
       }
     }
   }
   

   This basic demo-card example only defines properties for the Web Component. You can also add metadata that defines methods and events as shown below. The metadata lists the name of the method or event and supported parameters.

   {
     "properties": {
       ... contents omitted
     },
     "methods": {
        "flipCard": {
          "description": "Method to toggle flipping a card"
        },
        "enableFlip": {
          "description": "Enables or disables the ability to flip a card.",
          "params": [
            {
              "name": "bEnable",
              "description": "True to enable card flipping and false otherwise.",
              "type": "boolean"
             }
           ]
         },
       },
      "events": {
        "cardClick": {
          "description": "Triggered when a card is clicked and contains the value of the clicked card..",
          "bubbles": true,
          "detail": {
            "value": {
              "description": "The value of the card.",
              "type": "string"
                   }
               }
           } 
       }
   }    

5. If your Web Component contains a ViewModel, add its definition to web—component-name-viewModel.js in the Web Component’s root folder, creating the file if needed.

   The code sample below shows the ViewModel for the demo-card Web Component. Comments describe the purpose, parameters, and return value of each function.

   define(['knockout', 'ojs/ojknockout'],
   	function(ko) {
   		function model(context) {
   			var self = this;
   			self.initials = null;
   			self.workFormatted = null;
   			var element = context.element;
   
   			/**
   			 * Formats a 10 digit number as a phone number.
   			 * @param  {number} number The number to format
   			 * @return {string}        The formatted phone number
   			 */
   			var formatPhoneNumber = function(number) {
   				return Number(number).toString().replace(/(\d{3})(\d{3})(\d{4})/, '$1-$2-$3');
   			}
   
   			if (context.properties.name) {
   				var initials = context.properties.name.match(/\b\w/g);
   				self.initials = (initials.shift() + initials.pop()).toUpperCase();
   			}
   			if (context.properties.workNumber)
   				self.workFormatted = formatPhoneNumber(context.properties.workNumber);
   
   			/**
   			 * Flips a card
   			 * @param  {MouseEvent} event The click event
   			 */
   			self.flipCard = function(event) {
   				if (event.type === 'click' || (event.type === 'keypress' && event.keyCode === 13)) {
   					// It's better to look for View elements using a selector 
   					// instead of by DOM node order which isn't guaranteed.
   					$(element).children('.demo-card-flip-container').toggleClass('demo-card-flipped');
   				}
   			};
   		}
   
   		return model;
   	}
   )

6. In the Web Component’s root folder, add the View definition to web—component-name-view.html, creating the file if needed.

   The View for the demo-card Web Component is shown below. Any property defined in the component’s metadata is accessed using the $properties property of the View binding context.

   
   <div tabindex="0" role="group" class="demo-card-flip-container"
     on-click="[[flipCard]]" on-keypress="[[flipCard]]" :aria-label="[[$properties.name + ' Press Enter for 
   more info.']]">
     <div class="demo-card-front-side">
       <oj-avatar class="demo-card-avatar" role="img" size="lg" initials="[[initials]]" 
   src="[[$properties.avatar]]" :aria-label="[['Avatar of ' + $properties.name]]">
       </oj-avatar>
       <h2>
         <oj-bind-text value="[[$properties.name]]"></oj-bind-text>
       </h2>
     </div>
   
     <div class="demo-card-back-side">
       <div class="demo-card-inner-back-side">
         <h2>
   			  <oj-bind-text value="[[$properties.name]]"></oj-bind-text>
         </h2>
         <h5>
           <oj-bind-text value="[[$properties.workTitle]]"></oj-bind-text>
         </h5>
         <oj-bind-if test="[[$properties.workNumber != null]]">
           <h5>Work</h5>
           <span class="demo-card-text"><oj-bind-text value="[[workFormatted]]"></oj-bind-text></span>
         </oj-bind-if>
         <oj-bind-if test="[[$properties.email != null]]">
           <h5>Email</h5>
           <span class="demo-card-text"><oj-bind-text value="[[$properties.email]]"></oj-bind-text></span>
         </oj-bind-if>
       </div>
     </div>
   </div>
   

   For accessibility, the View’s role is defined as group, with aria-label specified for the contact’s name. In general, follow the same accessibility guidelines for the Web Component View markup that you would anywhere else within the app.

7. If you’re not using the Oracle JET CLI, create the loader.js RequireJS module and place it in the Web Component’s root folder.

   The loader.js module defines the Web Component dependencies and registers the component’s tagName, demo-card in this example.

   define(['ojs/ojcomposite', 'text!./demo-card-view.html', './demo-card-viewModel',
           'text!./component.json', 'css!./demo-card-styles'],
     function(Composite, view, viewModel, metadata) {
       Composite.register('demo-card', {
         view: view, 
         viewModel: viewModel, 
         metadata: JSON.parse(metadata)
       });
     }
   );

   In this example, the CSS is loaded through a RequireJS plugin (css!./demo-card-styles), and you do not need to pass it explicitly in Composite.register().

8. Configure any custom styling that your Web Component will use.

   • If you only have a few styles, add them to web—component-name-styles.css file in the Web Component’s root folder, creating the file if needed.

     For example, the demo-card Web Component defines styles for the demo card’s display, width, height, margin, padding, and more. It also defines the classes that will be used when the user clicks a contact card. A portion of the CSS is shown below.

     /* This is to prevent the flash of unstyled content before the Web Component properties have been setup. */
     demo-card:not(.oj-complete) {
       visibility: hidden;
     }
     
     demo-card {
       display: block;
       width: 200px;
       height: 200px;
       perspective: 800px;
       margin: 10px;
       box-sizing: border-box;
       cursor: pointer;
     }
     
     demo-card h2,
     demo-card h5,
     demo-card a, 
     demo-card .demo-card-avatar  {
       color: #fff;
       padding: 0;
     }
      ... remaining contents omitted
     
     

   • If you used the Oracle JET tooling to create your app and want to use Sass to generate your CSS:

     1. If needed, at a terminal prompt in your app’s top level directory, type the following command to add node-sass to your app: ojet add sass.

     2. Create web—component-name-styles.scss and place it in the Web Component’s top level folder.

     3. Edit web—component-name-styles.scss with any valid SCSS syntax and save the file.

        In this example, a variable defines the demo card size:

        $demo-card-size: 200px;
        
        /* This is to prevent the flash of unstyled content before the Web Component properties have been setup. */
        demo-card:not(.oj-complete) {
          visibility: hidden;
        }
        
        demo-card {
          display: block;
          width: $demo-card-size;
          height: $demo-card-size;
          perspective: 800px;
          margin: 10px;
          box-sizing: border-box;
          cursor: pointer;
        }
        
        demo-card h2,
        demo-card h5,
        demo-card a,
        demo-card .demo-card-avatar  {
          color: #fff;
          padding: 0;
        }
        ... remaining contents omitted
        

     4. To compile Sass, at a terminal prompt type ojet build or ojet serve with the --sass flag and app-specific options.

        ojet build|serve [options] --sass

        ojet build --sass will compile your app and generate web—component-name-styles.css and web—component-name-styles.css.map files in the default platform’s folder. For a web app, the command will place the CSS in web/js/js-composites/web—component-name.

        ojet serve --sass will also compile your app but will display the web app in a running browser with livereload enabled. If you save a change to web—component-name-styles.scss in the app’s src/js/jet-composites/web—component-name folder, Oracle JET will compile Sass again and refresh the display.

        Tip:

        For help with ojet command syntax, type ojet help at a terminal prompt.
9. If you want to add documentation for your Web Component, add content to README.md in your Web Component's root folder, creating the file if needed.

   Your README.md file should include an overview of your component with well-formatted examples. Include any additional information that you want to provide to your component’s consumers. The recommended standard for README file format is markdown.

Create JET Packs to simplify project management for consumers who might pick up a component that is related to one or more components. You may require specific versions of the referenced components for individual JET Packs.

1. Create the JET Pack using the JET tooling from the root folder of your app.

   ojet create pack my-pack

   Consider the pack name carefully, as the name will determine the prefix to any components within that pack.

   The tooling adds the folder structure with the template files that you will need to modify:

   /(working folder)
     /src
       /js
         /jet-composites
           /my-pack
             component.json

2. Create the components that you want to bundle with the JET Pack by using the JET tooling from the root folder of your app. The component name that you specify must be unique within the pack.

   ojet create component my-widget-1 --pack=my-pack 

   The tooling nests the component folder /my-widget-1 under the my-pack root folder and the new component files resemble those created for a standalone Web Component.

   /(working folder)
     /src
       /js
         /jet-composites
           /my-pack
             component.json
             /my-widget-1
               /resources
                 /nls
                   /root
                     my-widget-1-strings.js
               component.json
               loader.js
               README.md
               my-widget-1-viewModel.js
               my-widget-1-styles.css
               my-widget-1-view.html

   Note the following about the created component files.

   • component.json specifies the name of the component as my-widget-1 and the pack is set to my-pack, providing the complete definition of the component's identity.
   • loader.js registers the HTML tag for the new component as my-pack-my-widget-1. This is the full name of the component, which is a concatenation of the pack name and the component name. When you need to refer to this component in a dependency from another component's metadata or in HTML, you will use the full name.
3. Optionally, for any Resource components that you created, as described in Create Resource Components for JET Packs, add the component's working folder with its own component.json file to the pack file structure.

   The tooling nests the component folder /my-widget-1 under the my-pack root folder and the new component files resemble those created for a standalone Web Component.

   /(working folder)
     /src
       /js
         /jet-composites
           /my-pack
             component.json
             /my-widget-1
               /resources
                 /nls
                   /root
                     my-widget-1-strings.js
               component.json
               loader.js
               README.md
               my-widget-1-viewModel.js
               my-widget-1-styles.css
               my-widget-1-view.html 
             /my-resource-component-1
               component.json
               /converters
                 file1.js
                 ...
               /resources
                 /nls
                   /root
                     strings-file.js
               /validators
                 file1.js
                 ...
   

4. Optionally, generate any required bundled for desired components of the pack. Refer to RequireJS documentation for details at the https://requirejs.org web site.

   Tip:

   You can use RequireJS to create optimized bundles of the pack components, so that rather than each component being downloaded separately by the consuming app at runtime, instead a single JavaScript file can be downloaded that contains multiple components. It's a good idea to use this facility if you have sets of components that are almost always used together. A pack can have any number of bundles (or none at all) in order to group the available components as required. Be aware that not every component in the pack has to be included in one of the bundles and that each component can only be part of one bundle.

5. Use a text editor to modify the component.json file in the pack folder root similar to the following sample, to identify pack dependencies and optional bundles. Added components must be associated by their full name and a specific version.

   {
       "name": "my-pack",
       "version": "1.0.0",
       "type": "pack",
       "displayName": "My JET Pack",
       "description": "An example JET Pack",
       "dependencies": {
         "my-pack-my-widget-1":"1.0.0",
         ...
       },
       "bundles":{
           "my-pack/my-bundle":[
             "my-pack/my-bundle-file1/loader",
             ...
           ]
         },
       "extension": {
           "catalog": {
               "coverImage": "coverimage.png"
           }
        }
     }
   }

   Your pack component's component.json file must contain the following unique definitions:

   • name is the name of the JET Pack has to be unique, and should be defined with the namespace relevant to your group. This name will be prepended to create the full name of individual components of the pack.

   • version defines the exact version number of the pack, not a SemVer range.

     Note:

     Changes in version number with a given release of a pack should reflect the most significant change in the pack contents. For example, if the pack contained two components and as part of a release one of these had a Patch level change and the other a Major version change then the pack version number change should also be a Major version change. There is no requirement for the actual version number of the pack to match the version number(s) of any of it's referenced components. For more information see, Version Numbering Standards.

   • type must be set to pack.
   • displayName is the name of the pack component that you want displayed in in Oracle Component Exchange. Set this to something readable but not too long.
   • description is the description that you want displayed in Oracle Component Exchange. For example, use this to explain how the pack is intended to be used.

   • dependencies defines the set of components that make up the pack, specified by the component full name (a concatenation of pack name and component name). Note that exact version numbers are used here, not SemVer ranges. It's important that you manage revisions of dependency version numbers to reflect changes to the referenced component's version and also to specify part of the path to reach the components within the pack.

     If you want to include all components in the JET Pack directory, use a token, "@dependencies@", as the value for dependencies rather than defining individual entries for all the components in the pack. The following snippet illustrates how you use this token in your component.json file:

     {
       "name": "my-pack",
       "version": "1.0.0",
       "type": "pack",
       "displayName": "My JET Pack",
       "description": "An example JET Pack",
       "dependencies": "@dependencies@"
     }

   • bundles defines the available bundles (optional) and the contents of each. Note how both the bundle name and the contents of that bundle are defined with the pack name prefix as this is the RequireJS path that is needed to map those artifacts.
   • catalog defines the working metadata for Oracle Component Exchange, including a cover image in this case.
6. Use a text editor to modify the component.json file in the component folder root similar to the following sample, to identify the pack relationship. Components must be identified by a unique name (without the pack prefix) and a specific version.

   {
       "name": "my-widget-1",
       "pack": "my-pack",
       "displayName": "My Web Component",
       "description": "Fully featured component",
       "version": "1.0.0",
       "jetVersion": "^10.0.0",
       "dependencies": {
         "my-widget-file1":"^1.0.0",
         ...
       },
       ...
   }

   Your pack component's component.json file must contain the following unique definitions:

   • name is the name of the component has to be unique. This name will be prepended with the pack name to create the component full name. For example,
   • pack is the name of the JET Pack that the component is a part of.
   • displayName is the name of the component that you want displayed in Oracle Component Exchange.
   • description is the description that you want displayed in Oracle Component Exchange. For example, use this to explain the role of the components in the pack as they are intended to be used.

   • version defines the exact version number of the component, not a SemVer range.

   • jetVersion defines the compatible version(s) of Oracle JET, specified by a semantic version (SemVer) range. It's important that you manage revisions of this version number to inform consumers of the compatibility of a given change and also to specify part of the path to reach the components within the pack. For more information see, Version Numbering Standards.

   • dependencies defines the set of libraries and other components that make up the component within the pack. In the case where a dependent component is also listed as a member of the JET Pack, specify components here by their full name (a concatenation of pack name and component name). For example, my-pack-my-component. Note that SemVer ranges are allowed. It's important that the range selected for a component within a particular JET Pack version overlaps with the members of that stripe.
7. Optionally, create a readme file in the root of your working folder. This should be defined as a plain text file called README.txt (or README.md when using markdown format).
8. Optionally, create a cover image in the root of your working folder to display the component on Oracle Exchange. The file name can be the same as the name attribute in the component.json file.
9. Use the JET tooling to create a zip archive of the JET Pack working folder when you want to upload the component to Oracle Component Exchange, as described in Package Web Components.
10. Support consuming the JET Pack in Oracle Visual Builder projects by uploading the component to Oracle Component Exchange, as described in Publish Web Components to Oracle Component Exchange.

Create a resource component when you want to reuse assets across web components that you assemble into JET Packs. The resource component can be reused by multiple JET Packs.

1. If you have not already done so, create a JET Pack using the following command from the root folder of your app to contain the resource component(s):

   ojet create pack my-resource-pack

2. Still in the root folder of your app, create the resource component in the JET Pack:

   ojet create component my-resource-comp --type=resource --pack=my-resource-pack

   The tooling adds the folder structure with a single template component.json file and an index file.

   /root folder
     /src
       /js or /ts
         /jet-composites
           /my-resource-pack
   	    /my-resource-comp
   	       component.json

3. Populate the created folder (my-resource-comp, in our example) with the desired content. You can add content in any structure desired, with the exception of NLS content for translation bundles. In the case of NLS content, preserve the typical JET folder structure; this is important if your resource component is going to include such bundles.

   /(my-resource-folder)
     /converters
       phoneConverter.js
       phoneConverterFactory.js
     /resources
       /nls
         /root
          oj-ext-strings.js
       /phone
         countryCodes.json
     /validators
       emailValidator.js
       emailValidatorFactory.js
       phoneValidator.js
       phoneValidatorFactory.js
       urlValidator.js
       urlValidatorFactory.js
   

   In this sample notice how the /resources/nls folder structure for translation bundles is preserved according to the folder structured of the app generated by JET tooling.

4. Use a text editor to update the component.json file in the folder root similar to the following sample, which defines the resource my-resource-comp for the JET Pack my-resource-pack.

   {
     "name": "my-resource-comp",
     "pack": "my-resource-pack",
     "displayName": "Oracle Jet Extended Utilities",
     "description": "A set of reusable utility classes used by the Oracle JET extended 
                     component set and available for general use.  Includes various 
                     reusable validators",
     "license": "https://opensource.org/licenses/UPL",
     "type": "resource",
     "version": "2.0.2",
     "jetVersion": ">=8.0.0 <10.1.0",
     "publicModules": [
       "validators/emailValidatorFactory",
       "validators/urlValidatorFactory"
     ],
     "extension":{
       "catalog": {
         "category": "Resources",
           "coverImage": "cca-resource-folder.svg"
       }
     }
   }

   Your resource component's component.json file must contain the following unique definitions:

   • name is the name of the resource component has to be unique, and should be defined with the namespace relevant to your group.
   • pack is the name of the JET Pack containing the resource component.
   • displayName is the name of the resource component as displayed in Oracle Component Exchange. Set this to something readable but not too long.
   • description is the description that you want displayed in Oracle Component Exchange. For example, use this to explain the available assets provided by the component.
   • type must be set to resource.

   • version defines the semantic version (SemVer) of the resource component as a whole. It's important that you manage revisions of this version number to inform consumers of the compatibility of a given change.

     Note:

     Changes to the resource component version should roll up all of the changes within the resource component, which might not be restricted to changes only in .js files. A change to a CSS selector defined in a shared .css file can trigger a major version change when it forces consumers to make changes to their downstream uses of that selector. For more information see, Version Numbering Standards.

   • jetVersion defines the supported Oracle JET version range using SemVer notation. This is optional and depends on the nature of what you include into the resource component. If the component contains JavaScript code and any of that code makes reference to Oracle JET APIs, then you really should include a JET version range in that case. For more information about specifying semantic versions see Version Numbering Standards.
   • publicModules lists entry points within the resource component that you consider as being public and intend to be consumed by any component that depends on this component. Any API not listed in the array is considered to be pack-private and therefore can only be used by components within the same pack namespace, but may not be used externally.
   • catalog defines the working metadata for Oracle Component Exchange, including a cover image in this case.
5. Optionally, create a readme file in the root of your working folder. A readme can be used to document the assets of the resource. This should be defined as a plain text file called README.txt (or README.md when using markdown format).

   Tip:

   Take care to explain the state of the assets. For example, you might choose to include utility classes in the resource component that are deemed public and can safely be used by external consumers (for example, code outside of the JET Pack that the component belongs to). However, you may want to document other assets as private to the pack itself.

6. Optionally, create a change log file in the root of your working folder. The change log can detail significant changes to the pack over time and is strongly recommended. This should be defined as a text file called CHANGELOG.txt (or CHANGELOG.md when using markdown format).
7. Optionally, include a License file in the root of your working folder.
8. Optionally, create a cover image in the root of your working folder to display the component on Oracle Exchange. Using the third party logo can be helpful here to identify the usage. The file name can be the same as the name attribute in the component.json file.
9. Create a zip archive of the working folder when you want to upload the component to Oracle Component Exchange. Oracle recommends using the format <fullName>-<version>.zip for the archive file name. For example, my-resource-pack-my-resource-comp-2.0.2.zip.

Create a reference component when you need to obtain a pointer to third-party libraries for use by Web Components.

1. Create the working folder and use a text editor to create a component.json file in the folder root similar to the following sample, which references the moment.js library.

   {
     "name": "oj-ref-moment",
     "displayName": "Moment library",
     "description": "Supplies reference information for moment.js used to parse, 
                     validate, manipulate, and display dates and times in JavaScript",
     "license": "https://opensource.org/licenses/MIT",
     "type": "reference",
     "package":"moment",
     "version": "2.24.0",
     "paths": {
       "npm": {
         "debug": "moment",
         "min": "min/moment.min"
       },
       "cdn": {
         "debug": "https://static.oracle.com/cdn/jet/packs/3rdparty/moment/2.24.0/moment.min",
         "min": "https://static.oracle.com/cdn/jet/packs/3rdparty/moment/2.24.0/moment.min"
       }
     },
     "extension": {
       "catalog": {
         "category": "Third Party",
         "tags": [
           "momentjs"
         ],
         "coverImage": "coverImage.png"
       }
     }
   }

   Your reference component's component.json file must contain the following unique definitions:

   • name is the name of the reference component has to be unique, and should be defined with the namespace relevant to your group.
   • displayName is the name of the resource component as displayed in Oracle Component Exchange. Set this to something readable but not too long.
   • description is the description that you want displayed in Oracle Component Exchange. For example, use this to explain the function of the third party library.
   • license comes from the third party library itself and must be specified.
   • type must be set to reference.
   • package defines the npm package name for the library. This will also be used as the name of the associated RequireJS path that will point to the library and so will be used by components that depend on this reference.
   • version should reflect the version of the third party library that this reference component defines. If you need to be able to reference multiple versions of a given library then you will need multiple versions of the reference component in order to map each one.
   • paths defines the CDN locations for this library. See below for more information about getting access to the Oracle CDN.
   • min points to the optimal version of the library to consume. The debug path can point to a debug version or just the min version as here.
   • catalog defines the working metadata for Oracle Component Exchange including a cover image in this case.
2. Optionally, create readme file in the root of your working folder. A readme can be used to point at the third party component web site for reference. This should be defined as a plain text file called README.txt (or README.md when using markdown format).
3. Optionally, create a cover image in the root of your working folder to display the component on Oracle Exchange. Using the third party logo can be helpful here to identify the usage. The file name can be the same as the name attribute in the component.json file.
4. Create a zip archive of the working folder when you want to upload the component to Oracle Component Exchange. Oracle recommends using the format <fullName>-<version>.zip for the archive file name. For example, oj-ref-moment-2.24.0.zip.
5. Support consuming the reference component in Oracle Visual Builder projects by uploading the component to a CDN. See below for more details.

{
    "name":"calendar",
    "pack":"oj-sample",
    "displayName": "JET Calendar",
    "description": "FullCalendar wrapper with Accessibility added.",
    "version": "1.0.2",
    "jetVersion": "^9.0.0",
    "dependencies": {
        "oj-ref-moment":"2.24.0",
        "oj-ref-fullcalendar":"3.9.0"
    },
 
    ...

You can use Oracle JET Tooling to theme-enable a custom Web Components project and work with CSS variables to theme custom components that you add to the project.

1. In your Web Component project's top-level directory, enter the following command at a terminal prompt to install the theming toolchain.

   ojet add theming

2. Create a Web Component in the containing project. Or, create a JET Pack and add a Web Component to the pack, as this sample shows.

   ojet create pack my-pack
   ojet create component my-widget1 --pack=my-pack

   For example, the following commands create a pack oj-sample and add a custom component metric to the pack.

   ojet create pack oj-sample
   ojet create component metric --pack=oj-sample

   These commands create a jet-composites folder that contains the oj-sample pack folder and the metric component.

   src
   |   index.html
   |   
   +---css
   +---js
   \---ts
       +---jet-composites
       |   \---oj-sample
       |       |   component.json
       |       |   
       |       \---metric
       |           |   component.json
       |           |   loader.ts
       |           |   metric-styles.scss
       |           |   metric-view.html
       |           |   metric-viewModel.ts
       |           |   README.md
       |           |   
       |           +---resources
       |           \---themes
       |               +---base
       |               |       _metric.scss
       |               |       
       |               +---redwood
       |               |       _metric.scss
       |               |       
       |               \---stable
       |                       _metric.scss
       |                       
       +---viewModels
       +---views
   

   In the directory above, the metric folder shows the base SASS file metric-styles.scss. The themes subfolder contains the SASS partials files _metric.scss that you will modify.

   Note:

   If you see a .css file instead of a .scss file in the root folder of the component, it indicates you did not run the add theming command before creating the component.

3. In the /<componentName>/themes/base folder, edit the _componentName.scss SAAS partials file to define the style selectors for your component. You can define selector properties with hardcoded values or you can define properties controlled by CSS variables when you want to allow overriding of the property by a consuming app.

   Note that style and variable names must be named-spaced to the owning component's HTML element tag to avoid redefinition. For example, the style .oj-sample-metric-value-color is name-spaced by oj-sample-metric.

   @import "oj/utilities/_oj.utilities.modules.scss";
   // Even if this file is imported many times 'module-include-once' ensures the content is included just once.
   @include module-include-once("oj-sample-metric.base") {
     oj-sample-metric:not(.oj-complete){
       visibility: hidden;
     }
     // Selector definitions section
     oj-sample-metric .oj-sample-metric-value-text {
       display:inline-block;
       align-self:center;
     }
     oj-sample-metric .oj-sample-metric-label {
       font-size: var(--oj-sample-metric-label-font-size);
     }
     oj-sample-metric .oj-sample-metric-value-color {
       color: var(--oj-sample-metric-value-color);
     }
     oj-sample-metric .oj-sample-metric-label-color {
       color: var(--oj-sample-metric-label-color);
     }
     ...
   }

   In this sample, only the selector .oj-sample-metric-value-text selector is completely defined in place and references no CSS variables. Properties of this style cannot be overridden. The font-size property for the .oj-sample-metric-label selector references a CSS variable that you will define in the theme-specific SASS partials file. The color property for the .oj-sample-metric-value-color and .oj-sample-metric-label-color selectors also references a CSS variable to be defined. The usage of CSS variables allows these properties to be overridden in the consuming app.

   When you do not need to allow overriding of a selector property value in the consuming app, you can reference variables defined by JET itself without definition in the theme-specific SASS partials file. In this next sample, the selector is defined directly by --oj-core-text-color-secondary, a JET CSS variable that defines text color.

     ...
     oj-sample-metric .oj-sample-metric-label-color {
       color: var(--oj-core-text-color-secondary);
     }
     ...
   }

   For a list of JET CSS variables, refer to the resources listed in the Before You Begin section of this topic.

   Note:

   If you define mappings such as:

   color: rgb(var(--oj-palette-neutral-rgb-60));

   Then, when you build your project, you will encounter an error: "Error: Function rgb is missing argument $green" in your .scss files. This is a known SASS compiler issue and the workaround is to use uppercase for the function name, like this:

   color: RGB(var(--oj-palette-neutral-rgb-60));

4. In the /<componentName>/themes/redwood or /<componentName>/themes/stable folder, edit the _componentName.scss SAAS partials file to provide the theme-specific settings required by the base partials SCCS file. Within root you can define all component-specific CSS variables as hardcoded values or JET CSS variables.

   @include module-include-once("_metric.redwood") {
     :root {
       --oj-sample-metric-label-font-size:0.875rem;
       --oj-sample-metric-value-color:var(--oj-core-text-color-primary);
       --oj-sample-metric-label-color:var(--oj-core-text-color-secondary);
       ...
     }
   }

   In this sample, only the CSS variable --oj-sample-metric-label-font-size is hardcoded. The other two variables inherit values from underlying JET variables. However, all settings defined in the theme-partials file may be overridden in the app that consumes the web component.

   For a list of JET CSS variables, refer to the resources listed in the Before You Begin section of this topic.

   To prepare the themed component or pack for a consuming app, see these topics:

   • Consolidate CSS for JET Packs
   • Optimize CSS to Allow Consuming Apps to Provide Styles

You can consolidate the stylesheets of custom components in a JET Pack to a single CSS file.

1. Add the Resource component that you created with a component.json file to the pack file structure and add a subfolder styles with a single SCSS file that you will use to import the CSS of the individual components in the pack.
   
   Description of the illustration mytheme_res_css_files.jpg

   In the figure above, the folder common is the working folder for the Resource component and the styles subfolder shows a SCSS file oj-sample-style.scss named for the pack.

2. Edit the SCCS file in the styles folder to replicate the import commands for the SCSS partials files of the components that you want to combine into the consolidated stylesheet.

   @import "../../metric/themes/redwood/_metric.scss";
   @import "../../input-email/themes/redwood/_input-email.scss";
   @import "../../input-email/themes/redwood/_input-url.scss";

   In this sample, we show import statements for three components from the oj-sample pack example. In addition to the metric component's import, we include the import statements for the input-email component and the input-url component (omitted from the figure).

3. For each component that you want to consolidate into a shared stylesheet, edit the component's loader.js file (.ts in the case of a TypeScript project) to reference the shared stylesheet named in the Resource component. Do not edit the loader file for any component that you want to continue to use the component-specific stylesheet.

   define (['ojs/ojcomposite',
            'text!./metric-view.html',
            './metric-viewModel',
            'text!./component.json',
            'css!oj-sample/common/styles/oj-sample-styles'
            ],
    
   function(Composite, view, viewModel, metadata){
     Composite.register("oj-sample-metric", {
       view: view,
       viewModel: viewModel,
       metadata: JSON.parse(metadata)
     });
    }
   );

   In this JavaScript sample, the loader script for the metric component shows the modified path statement references oj-sample-style from the SCSS file that was added to the Resource component's /common/styles folder.

   In the case of a TypeScript app, modify the import statement like this sample:

   import "css!oj-sample/common/styles/oj-sample-styles";

   Note:

   Do not use relative path mapping to reference a pack component. Identify the path to the consolidated file in the pack component as shown in the previous examples for a JavaScript and TypeScript app.

   To perform a further optimization that allows the consuming app to manage the style completely in its own CSS, you can perform this task:

   • Optimize CSS to Allow Consuming Apps to Provide Styles

You can optimize the loading of component styles in the theme CSS for the consuming app.

1. For each component that you want to consolidate into a shared stylesheet, edit the component's loader.js file (.ts in the case of a TypeScript project) and modify the import statement for the consolidated stylesheet by replacing the normal CSS requireJS plugin with the configurable ojcss plugin.

   define (['ojs/ojcomposite',
            'text!./metric-view.html',
            './metric-viewModel',
            'text!./component.json',
            'ojcss!oj-sample/common/styles/oj-sample-styles'
            ],
    
   function(Composite, view, viewModel, metadata){
     Composite.register("oj-sample-metric", {
       view: view,
       viewModel: viewModel,
       metadata: JSON.parse(metadata)
     });
    }
   );

   In the case of a TypeScript app, modify the import statement like this sample:

   import "ojcss!oj-sample/common/styles/oj-sample-styles";

   Note that the ojcss plugin import gives the downstream developer the ability to set up their app to configure the processing of the plugin directive and optionally suppress loading of custom component stylesheets when the consuming app defines the styles.

2. For these same components, edit the component's component.json file to decorate the component with the extension metadata to specify the SCSS partials that define its theme.

   {
       "name": "metric",
       "pack": "oj-sample",
       "type":"composite",
       "displayName": "Metric Component",
       "license": "https://opensource.org/licenses/UPL",
       "description": "A simple tile that displays a label and value.",
       "version": "4.0.0",
       "jetVersion": ">=8.0.0 <10.0.0",
       "icon": {
           "iconPath": "extension/images/cca-metric.svg",
           "selectedIconPath": "extension/images/cca-metric.svg",
           "hoverIconPath": "extension/images/cca-metric-ovr.svg"
       },
       "properties": {
         . . .
       },
       "events": {
           . . .
       },
       "extension": {
           "themes":{
               "default":"Redwood",
               "unsupportedThemes":["Alta"]
               "partials":{
                 "Redwood":"themes/redwood/_oj-sample-metric.scss"}
         }
           "catalog": {
               . . .
           },
           "vbdt": {
               . . .
           }
       }
   
     }

   In this sample, the extension : themes attribute defines an array of themes supported by the component. Each theme points to the relative path of the root partial as the source for that component's theme implementation. The definition also indicates whether or not it is the expected default theme. Components may support multiple themes, but only one of can be marked as the default.

   Note that this metadata is not required by JET but is recommended for any themeable custom component. This information will be used by the downstream developer to set up their app to pull in these SCSS partials into its own SCSS file. They can then build the app to assemble individual stylesheets into a combined CSS file.

   In normal usage there is no difference in operation between the ojcss and css plugins. However, the consuming app now has the ability to control the processing of the plugin directive.

   To understand how the consuming app controls the processing of the plugin directive to suppress the loading of the component CSS and define style classes within their app's custom theme, see Incorporate Themed Components into a Consuming App.

You can override CSS variables in a properly themed Web Component by making changes to the style classes in your consuming app's theme.

1. In the working project, where you added the custom components, open the /src/themes/<themeName>/web folder and examine the folder structure.

   /src
     /themes
       /redwood-plus
         /web
           _redwood-plus.components.scss
           _redwood-plus.cssvars.settings.scss
           _redwood-plus.sass.settings.scss
           redwood-plus.scss

   In this sample, we see three SCSS partials files and the CSS aggregating file redwood-plus.scss. In the context of customizing the theme in the working project with themeable custom components, the four files have these purposes.

   • _redwood-plus.components.sccs allows you to tune the overall size of your theme by specifying that it should only style specific components from JET core. Usually you will not touch this file as you'll be styling the whole component set. See also Optimize the CSS in a Custom Theme.
   • _redwood-plus.cssvars.settings.scss is the file that you use to make most of the style changes in your custom theme, assuming you need to make any. You will use it to set the CSS variable values that you want to be used by the various JET Core components (and possibly by the custom components, as well). For example, to change the primary text color for JET, as a whole, you can do it in this file by uncommenting and setting the value for --oj-core-text-color-primary. Assuming this same variable happens to be used by one of the custom components, then it would share this common change. See also Modify the Custom Theme with the JET CLI.
   • _redwood-plus.sass.settings defines other aspects of the theme that you may need to change but that can't be expressed as simple variable values, for example animation effects. For basic theming scenarios, you probably don't need to touch this file.
   • redwood-plus.scss this is the main CSS aggregating file for the theme as a whole and is the one that will be transformed into the final output, as the redwood-plus.css file.
2. In the /src/themes/<themeName>/web folder, edit the CSS aggregating file <themeName>.scss and add the import statements for the theme-able custom components that you added to the working project.

   ...
   // import SASS custom variable overrides
   @import "_redwood-plus.sass.settings.scss";
   
   // Imports all jet components styles
   //@import "oj/all-components/themes/redwood/_oj-all-components.scss";
   
   // To optimize performance, consider commenting out the above oj-all-components
   // import and uncomment _redwood-plus.components.scss below.
   // Then in _redwood-plus.components.scss uncomment only the component 
   // imports that your app needs.
   //
     
   // @import "_redwood-plus.components.scss";
   
   // Import components from oj-sample JET Pack
   @import "oj-sample/metric/themes/redwood/_oj-sample-metric.scss";
   @import "oj-sample/input-email/themes/redwood/_input-email.scss";
   @import "oj-sample/input-url/themes/redwood/_input-url.scss";
   
   // import CSS Custom properties
   @import "_redwood-plus.cssvars.settings.scss";

   In this sample, the import statements for the three theme-able custom components in the oj-sample pack are added. With these import statements referencing each component partials' includePath added to the CSS aggregating file, the indicated component partials will be incorporated into the custom theme.

3. Optionally, if you are making changes to the theme (and not using the process only to consolidate CSS), you can test your theme by embedding sample components, including your custom components, into the working project's index.html page and run it. You can then verify the theme changes are what you expect. However, before you run the project, you must ensure that the custom components can pick up their styles from the theme, and not from their own stylesheets.
   1. To suppress the loading of component CSS, edit the main.js file and add an ojcss configuration section in the requirejs configuration that names the CSS loading to suppress.

      requirejs.config(
          {
            baseUrl: 'js',
            ojcss: {
              'exclude': ['oj-sample']
             },
            paths:
            /* DO NOT MODIFY
            ** All paths are dynamically generated from the path_mappings.json file.
            ** Add any new library dependencies in path_mappings json file
            */
            // injector:mainReleasePaths
            {
              ...
            }
            // endinjector
            ,
        
          }
        );
      }());
      

      Make sure that you add the ojcss configuration section outside of the //injector block, as shown. Otherwise, the build process will remove and ignore the section.

      In this sample, the ojcss section of the requirejs configuration excludes the consolidated stylesheet of the JET Pack oj-sample. The ojcss section defines an array of requireJS paths that will be excluded from loading. Note this configuration depends upon imports within the component using consistent Reliable Referencing based paths that match.

   2. Run the project to verify the changes.

      ojet serve --theme=redwood-plus

4. Update the version number in the /src/themes/<myTheme>/theme.json file to one that is suitable for the target CSS and build the consolidated theme. By default the version number is initially 0.0.1.

   ojet build --theme=redwood-plus