Adding an Oracle JET Custom Element to Your Page

Use the Oracle JET Cookbook recipes and API documentation to locate examples that illustrate the specific element and functionality you want to add to your page.

To add an Oracle JET custom element to your page:

If needed, create the application that will house your main HTML5 page and supporting JavaScript. For additional information, see Getting Started with Oracle JET Application Development.

1. Using the Oracle JET Cookbook, select the Oracle JET element that you want to add.

   Each cookbook demo will usually contain several examples illustrating common use cases. Look for an example that comes closest to your use case.

2. Follow the example’s recipe and add the markup, modifying as needed, to your HTML page.

   All Oracle JET recipes include the basic format for initializing the component using custom element syntax. The code below shows a portion of the markup for the oj-input-date-time example shown in the Date and Time Pickers demos.

   <div id="div1">
     <oj-label for="dateTime">Default</oj-label>
     <oj-input-date-time id="dateTime" value='{{value}}'>
     </oj-input-date-time>
   
     <br/><br/>
   
     <span class="oj-label">Current component value is:</span>
     <span data-bind="text: value"></span>
   </div>
   

   In this example, the oj-input-date-time element is declared with its value attribute using {{...}} expression syntax, which indicates that changes to the value will also update the corresponding value in the ViewModel. Each Oracle JET custom element includes additional attributes that are defined in the custom element's API documentation.

3. Use the Oracle JET Cookbook for example scripts and the syntax to use for adding the custom element’s Require module and ViewModel to your RequireJS bootstrap file or module.

   For example, the basic demo for oj-input-date-time includes the following script that you can use in your application.

   require(['ojs/ojcore', 'knockout', 'jquery', 'ojs/ojknockout', 'ojs/ojdatetimepicker'], 
   function (oj, ko, $)
   {
   
     function SimpleModel()
     {
       this.value = ko.observable(oj.IntlConverterUtils.dateToLocalIso(new Date(2013, 0, 1)));
     }
      
     $(document).ready(function ()
     {
       ko.applyBindings(new SimpleModel(), document.getElementById('div1'));
     });
      
   });
   

   Important:

   If you’re working with a Starter Template or define modules for different sections of your page, you can’t simply copy and paste the cookbook example. The Cookbook uses a require() call to load and use the needed libraries in a single bootstrap file. The starter file that you are pasting into is a RequireJS module which uses define() instead to create a module that can be used by other parts of your application. For additional details, see Modifying Starter Template Content.

   If you already have a RequireJS bootstrap file or module, compare your file with the Cookbook sample and merge in the differences. For details about working with RequireJS, see Using RequireJS for Modular Development.

Adding Animation Effects

You can use the oj-module component’s animation property in conjunction with the ModuleAnimations namespace to configure animation effects when the user transitions between or drills into views. If you’re not using oj-module, you can use the oj.AnimationUtils namespace instead to add animation to Oracle JET components or HTML elements.

Adding Animation Effects Using the oj-module Component

The oj.ModuleAnimations namespace includes pre-configured implementations that you can use to configure the following animation effects:

• coverStart: The new view slides in to cover the old view.

• coverUp: The new view slides up to cover the old view.

• drillIn: Animation effect is platform-dependent.

  • Web and iOS: coverStart

  • Android: coverUp

  • Windows: zoomIn

• drillOut: Animation effect is platform-dependent.

  • Web and iOS: revealEnd

  • Android: revealDown

  • Windows: zoomOut

• fade: The new view fades in and the old view fades out.

• goLeft: Navigate to sibling view on the left. Default effect is platform-dependent.

  • Web and iOS: none

  • Android and Windows: pushRight

• goRight: Navigate to sibling view on the right. Default effect is platform-dependent.

  • Web and iOS: none

  • Android and Windows: pushLeft

• pushLeft: The new view pushes the old view out to the left.

• pushRight: The new view pushes the old view out to the right.

• revealDown: The old view slides down to reveal the new view.

• revealEnd: The new view slides left or right to reveal the new view, depending on the locale.

• zoomIn: The new view zooms in.

• zoomOut: The old view zooms out.

For examples that illustrate how to add animation with the oj-module component, see Animation Effects with Module Component.

Adding Animation Effects Using oj.AnimationUtils

The oj.AnimationUtils namespace includes methods that you can use to configure the following animation effects on HTML elements and Oracle JET components:

• collapse: Use for collapsing the element

• expand: Use for expanding the element

• fadeIn and fadeOut: Use for fading the element into and out of view.

• flipIn and flipOut: Use for rotating the element in and out of view.

• ripple: Use for rippling the element.

• slideIn and slideOut: Use for sliding the element into and out of view.

• zoomIn and zoomOut: Using for zooming the element into and out of view.

Depending on the method’s options, you can configure properties like delay, duration, and direction. For examples that illustrate how to configure animation using the oj.AnimationUtils namespace, see Animation Effects.