About the Oracle JET User Interface

Identifying Oracle JET UI Components, Patterns, and Utilities

The Oracle JET Cookbook lists all the components, design patterns, and utilities available for your use. By default, the cookbook is organized into functional sections, but you can also click Sort to arrange the contents alphabetically.

The Cookbook contains samples that you can edit online and see the effects of your changes immediately. You’ll also find links to the API documentation, if applicable.

Common Functionality in Oracle JET Components

All Oracle JET components are implemented as custom HTML elements, and programmatic access to these components is similar to interacting with any HTML element.

Custom Element Structure

Oracle JET custom element names start with oj-, and you can add them to your page the same way you would add any other HTML element. In the following example, the oj-label and oj-input-date-time custom elements are added as child elements to a standard HTML div element.

<div id="div1">
  <oj-label for="dateTime">Default</oj-label>
  <oj-input-date-time id="dateTime" value='{{value}}'>
  </oj-input-date-time>
</div>

Each custom element can contain one or more of the following:

Attributes: Modifiers that affect the functionality of the element.

String literals will be parsed and coerced to the property type. Oracle JET supports the following string literal type coercions: boolean, number, string, Object, Array, and any. The any type, if used by an element, is marked with an asterisk (*) in the element’s API documentation and coerced to Objects, Arrays, or strings.

In the oj-input-date-time element defined above, value is an attribute that contains a Date object. It is defined using a binding expression that indicates whether the element’s ViewModel should be updated if the attribute’s value is updated.
```
<oj-input-date-time id="dateTime" value='{{value}}'>
```
The {{...}} syntax indicates that the element’s value property will be updated in the element’s ViewModel if it’s changed. To prevent the attribute’s value from updating the corresponding ViewModel, use the [[...]] syntax.
Methods: Supported methods

Each custom element’s supported method is documented in its API.
Events: Supported events

Events specific to the custom element are documented in its API. Define the listener’s method in the element’s ViewModel.
```
var listener = function( event )
{
  // Check if this is the end of "inline-open" animation for inline message
  if (event.detail.action == "inline-open") {
    // Add any processing here
  }
};
```
Reference the listener using the custom element’s DOM attribute, JavaScript property, or the addEventListener().
- Use the DOM attribute.
  Declare a listener on the custom element using on-event-name syntax.
```
<oj-input-date-time on-oj-animate-start='[[listener]]'</oj-input-date-time>
```
  Note that in this example the listener is declared using the [[...]] syntax since its value is not expected to change.
- Use the JavaScript property.
  
  Specify a listener in your ViewModel for the .onEventName property.
```
myInputDateTime.onOjAnimateEnd = listener
```
  Note that the JavaScript property uses camelCase for the onOjAnimateEnd property. The camelCased properties are mapped to attribute names by inserting a dash before the uppercase letter and converting that letter to lower case, for example, on-oj-animate-end.
- Use the addEventListener() API.
```
myInputDateTime.addEventListener('ojAnimateEnd', listener);
```
By default, JET components will also fire propertyChanged custom events whenever a property is updated, for example, valueChanged. You can define and add a listener using any of the three methods above. When referencing a propertyChanged event declaratively, use on-property-changed syntax.
```
<oj-input-date-time value="{{currentValue}}" on-value-changed="{{valueChangedListener}}" </oj-input-date-time>
```
Slots

Oracle JET elements can have two types of child content that determine the content’s placement within the element.
- Any child element with a supported slot attribute will be moved into that named slot. All supported named slots are documented in the element’s API. Child elements with unsupported named slots will be removed from the DOM.
```
<oj-table>
  <div slot='bottom'<oj-paging-control></oj-paging-control></div>
</oj-table>
```
- Any child element lacking a slot attribute will be moved to the default slot, also known as a regular child.

A custom element will be recognized only after its module is loaded by the application. Once the element is recognized, Oracle JET will register a busy state for the element and will begin the process of upgrading the element from a normal element to a custom element. The element will not be ready for interaction until the upgrade process is complete. The application should listen to either the page-level or element-scoped oj.BusyContext before attempting to interact with any JET custom elements. However, property setting (but not property getting) is allowed before the oj.BusyContext is initialized. See the oj.BusyContext API documentation on how BusyContexts can be scoped.

The upgrade of custom elements relies on a binding provider which manages the data binding. The binding provider is responsible for setting and updating attribute expressions. Any custom elements within its managed subtree will not finish upgrading until the provider applies bindings on that subtree. By default, there is a single binding provider for a page, but subtree specific binding providers can be added by using the data-oj-binding-provider attribute with values of none and knockout. The default binding provider is knockout, but if a page or DOM subtree does not use any expression syntax or knockout, the application can set data-oj-binding-provider=”none" on that element so that its dependent JET custom elements do not wait for bindings to be applied to finish upgrading.

Other Common Functionality

Oracle JET custom elements also have the following functionality in common:

Context menus

Custom elements support the slot attribute to add context menus to Oracle JET custom elements, described in each element’s API documentation.

<oj-some-element>
  <-- use the contextMenu slot to designate this as the context menu for this component -->
  <oj-menu slot="contextMenu" style="display:none" aria-label="Some element's context menu"
    ...
  </oj-menu>
</oj-some-element>

Keyboard navigation and other accessibility features

Oracle JET components that support keyboard navigation list the end user information in their API documentation. For additional information about Oracle JET components and accessibility, see Developing Accessible Applications.
Drag and drop

Oracle JET includes support for standard HTML5 drag and drop and provides the dnd-polyfill library to extend HTML5 drag and drop behavior to supported mobile and desktop browsers. In addition, some Oracle JET custom elements such as oj-table support drag and drop behavior through the dnd attribute. For specific details, see the component’s API documentation and cookbook examples. To learn more about HTML5 drag and drop, see http://www.w3schools.com/html/html5_draganddrop.asp.
Deferred rendering

Many Oracle JET custom elements support the ability to defer rendering until the content shown using oj-defer. To use oj-defer, wrap it around the custom element.
```
<oj-collapsible id="defer">
  <h4 id="hd" slot="header">Deferred Content</h4>
    <oj-defer>
      <oj-module config='[[deferredRendering/content]]'>
      </oj-module>
    </oj-defer>
</oj-collapsible>
```
Add the deferred content to the application’s view and ViewModel, content.html and content.js, as specified in the data-bind definition. For the complete code example, see Collapsibles - Deferred Rendering.

For a list of custom elements that support oj-defer, see oj-defer.

Custom Element Examples and References

The Oracle JET Cookbook and JavaScript API Reference for Oracle® JavaScript Extension Toolkit (JET) provide examples that illustrate how to work with custom elements. In addition, the Cookbook provides demos with editing capability that allow you to modify the sample code directly and view the results without having to download the sample.

To learn more about the World Wide Web Consortium (W3C) web component specification for custom elements, see Custom Elements.

Oracle JET Reserved Namespaces and Prefixes

Oracle JET reserves the oj namespace and prefixes. This includes, but is not limited to component names, namespaces, pseudo-selectors, public event prefixes, CSS styles, Knockout binding keys, and so on.