Using the Oracle JET QuickStart Templates

You can load the Oracle JET QuickStart templates in NetBeans, JDeveloper, or your favorite development environment. After you load one of the templates, you can customize it for your application by modifying the template's index.html and main.js files.

Topics:

Loading the Oracle JET QuickStart Templates

The Oracle JET QuickStart templates includes all of the Oracle JET libraries and an index.html file already configured for your use. To load the Oracle JET QuickStart templates, extract the zip files and copy them as needed for your development environment.

You can also load the Oracle JET QuickStart templates in the NetBeans or JDeveloper IDE.

Topics:

Loading the Oracle JET QuickStart Templates in NetBeans

To load the Oracle JET QuickStart templates in the NetBeans IDE:

  1. Download the Oracle JET QuickStart template as described in Downloading Oracle JET with a QuickStart Template.
  2. Create a new HTML5 application project and add the QuickStart template zip file (for example, OracleJET_QuickStartBasic.zip) as a site template as described in Creating an Oracle JET Application in the NetBeans IDE.
  3. In the Projects panel, right-click the index.html file and choose Run File to display the page in your browser.

    Note:

    To take full advantage of the NetBeans integrated tools, the NetBeans team recommends that you install the NetBeans Connector extension for the Chrome browser. For additional info, see https://netbeans.org/kb/73/webclient/html5-gettingstarted.html.

    The graphic below shows the Oracle JET QuickStart Basic Template displayed in the Chrome browser at run time. In this example, the NetBeans Connector is enabled.

    The image is described in the surrounding text.

Loading the Oracle JET QuickStart Templates in JDeveloper

To load the Oracle JET QuickStart templates in the JDeveloper IDE:

  1. Download the desired Oracle JET QuickStart template as described in Downloading Oracle JET with a QuickStart Template.
  2. Create a custom application and project and extract the QuickStart download bundle as described in Creating an Oracle JET Application in JDeveloper. You do not need to complete the last step to add the index.html file because it is already included with the Oracle JET QuickStart template.
  3. In the Applications window, in the Projects panel, right-click the index.html file and choose Open.
  4. In the Visual Editor, click Source to view and edit your new page.
  5. In the Applications window, in the Projects panel, right-click the index.html file and choose Run to deploy the application and display the page in your default browser.

    When you deploy the application for the first time, JDeveloper adds a default web.xml file to your project. The following example shows the default web.xml file for the OracleJETQuickStartBasic application.

    <?xml version = '1.0' encoding = 'windows-1252'?>
    <web-app xmlns="http://java.sun.com/xml/ns/javaee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
             version="3.0">
    </web-app>
    

Working with the Oracle JET QuickStart Basic Template

The Oracle JET QuickStart Basic Template provides everything you need to start working with code immediately. It is designed to work with the Oracle JET Cookbook examples, and you can use it to familiarize yourself with the Oracle JET components and basic structure of an Oracle JET application.

Topics:

You can also view a video that shows how to work with the Oracle JET QuickStart Basic Template in the Oracle JET Videos collection.

About the QuickStart Basic Template

The QuickStart Basic Template is a single page application that is structured for modular development using RequireJS, Knockout templates, and the Oracle JET ojModule binding. Instead of storing all the application markup in the index.html file, the application uses Knockout's data-bind syntax and the ojModule binding to bind either a Knockout view template containing the HTML markup for the section or both the view template and JavaScript file that contains the ViewModel for any components defined in the section.

The following code shows a portion of index.html. Comments describe the purpose of each section, and you should review them for accessibility and usage tips.

Note:

Any CSS styling with the prefix "demo-" is for demonstration only and is not provided as part of the Oracle JET framework.
<html lang="en-us" class='demo-sticky-footer-layout'>
  <head>
    <title>Oracle JET QuickStart - Basic</title>
    ... contents omitted
    <!-- RequireJS bootstrap file -->
    <script data-main="js/main" src="js/libs/require/require.js"></script>
  </head>
  <body class="demo-appheader-offcanvas-pushwrapper">
    <div id="globalBody" style="display: none">
      <!-- off-canvas content -->
      <div id="appDrawer"
           class="oj-offcanvas-start oj-panel demo-appheader-offscreencontent"
           style="height:100%;">
        <div id='demoAppheaderOffCanvasInnerDiv'
             data-bind="ojModule: {name: 'header', viewName: 'demoAppHeaderOffCanvasTemplate'}"
        </div>
      </div>
      <!-- Header section contains the Global Branding, Global Navigation, and
           Application Navigation code. Template is located in
           /templates/header.tmpl.html -->
      <header id="headerWrapper" role="banner"
              data-bind="ojModule: { name: 'header'}"></header>

      <!-- This is where your main page content will be loaded -->
      <div id="mainContainer">
        <div class="oj-row">
          <div class="oj-xl-3 oj-lg-3 oj-md-12 oj-col"> <!-- demo-coldrop-A -->
            <div role="navigation" class="demo-page-content-area">
            <!--  This section is usually used for Navigation. 
                  If its purpose is changed, the "role" attribute should be
                  changed as well to meet accessibility guidelines-->
              <div id="navigationContent" data-bind="ojModule: { viewName: 'navContent'}">
              </div>
            </div>
          </div>
          <div class="oj-xl-6 oj-lg-9 oj-md-12 oj-col"> <!-- demo-coldrop-B -->
            <div role="main" class="demo-page-content-area">
            <!-- Unlike the Navigation and Complementary sections, this ojModule
                 binding is using "name" instead of "viewName". This tells the
                 binding to look for and load the JavaScript module of the same
                 name before loading the view template file. The value of the name
                 option is set to the current state of the ojRouter object which
                 is defined in the main.js file. This controls the modules that
                 will be loaded when the user clicks the App Nav buttons.
            -->
              <div id="mainContent" data-bind="ojModule: { name: router.stateId()}">
              </div>
            </div>
          </div>
          <div class="oj-xl-3 oj-lg-12 oj-md-12 oj-col"> <!-- demo-coldrop-C -->
            <div role="complementary" class="demo-page-content-area">
              <div id="complementaryContent" data-bind="ojModule: { viewName: 'compContent'}">
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>

The ojModule binding’s viewName option tells Oracle JET that the section is only defining a view template, and the view will be bound to the existing ViewModel. Use the ojModule binding’s name option to load both a ViewModel module and view template.

The main container (div id="mainContainer") is defined as an Oracle JET responsive grid row, with sections for Navigation, Home Content Area, and Complementary. The following graphic shows the main container at run time, with arrows pointing to the names of the view template or ViewModel module defined in index.html.

The image is described in the surrounding text.

The application uses oj.Router to manage navigation when the user clicks one of the application’s navigation buttons. If the user clicks People, for example, the Home Content Area changes to display the content in the people view template.

The image is described in the surrounding text.

The site_root/templates folder contains the view templates (viewName) for the application. site_root/js/modules contains the ViewModel (name) scripts. The application defines the default paths and suffix for the view template in the main.js RequireJS bootstrap file. The image below shows the QuickStart Basic Template application file structure in the NetBeans IDE.

The image is described in the surrounding text.

For additional information about working with single page applications, ojModule, oj.Router, and Knockout templates, see Creating Single-Page Applications.

Modifying the QuickStart Basic Application Content

You can add your own content to the main content area or anywhere on the page. To add content, modify the appropriate view template and ViewModel script (if it exists) for the section you want to update. Add any needed RequireJS modules to the ViewModel require() definition, along with functions to define your ViewModel.

If you add content to a section that changes its role, then be sure to change the role associated with that section. Oracle JET uses the role definitions for accessibility, specifically WAI-ARIA landmarks. For additional information about Oracle JET and accessibility, see Developing Accessible Applications.

To modify the Oracle JET QuickStart Basic application content:

  1. Download the QuickStart Basic Template as described in Downloading Oracle JET with a QuickStart Template.
  2. Load the QuickStart Basic Template as described in Using the Oracle JET QuickStart Templates.
  3. In the index.html file, locate the ojModule binding for the section you want to modify and identify the template and optional ViewModel module.

    For example, to update the Navigation content, locate the ojModule binding for the Navigation div in index.html and determine whether you need to modify a view template or both a view template and ViewModel module.

    <div id="navigationContent" data-bind="ojModule: { viewName: 'navContent'}"></div>
    

    The ojModule binding specifies navContent in the viewName option. Since the viewName option indicates that there is only a view template for this section, you will modify the navContent.tmpl.html file in the templates folder.

    To update the header content which appears above the Navigation, locate the ojModule binding, locate the ojModule binding for the header div, shown below.

    <header id="headerWrapper" role="banner" data-bind="ojModule: { name: 'header'}"></header>
    

    The ojModule binding specifies header for the name option, which indicates that there is both a view template and ViewModel module for the header section. Therefore, you will edit header.tmpl.html in the templates folder and header.js in the js/modules folder.

    The main content area content is a bit trickier to locate. The following code sample shows the mainContent div in the QuickStart Basic index.html file. In this example, the ojModule binding is using the name option to indicate that the binding should load the JavaScript module of the same name as the return value of router.stateId() before loading the view template file.

    <div id="mainContent" data-bind="ojModule: { name: router.stateId()}"></div>
    

    The return value of router.stateId() is set to the current state of the ojRouter object. The ojRouter object is defined with an initial value of home in the application's main.js RequireJS bootstrap, shown below.

    var router = oj.Router.rootInstance;
    router.configure({
      'home': {label: 'Home', isDefault: true},
      'people': {label: 'People'},
      'library': {label: 'Library'},
      'graphics': {label: 'Graphics'},
      'performance': {label: 'Performance'}
    });
    

    Since the ojModule binding specified the name option, you will modify both the home.tmpl.html and home.js file.

  4. To modify the view template, remove unneeded content, and add the new content to the template file.

    For example, if you are working with an Oracle JET Cookbook sample, you can copy the markup into the template you identified in the previous step. Replace everything after the <h1>Home Content Area</h1> markup in the template with the markup from the sample.

    For example, the following code shows the modified markup if you replace the existing content with the content from the Date and Time Pickers demo.

    <h1>Home Content Area</h1>
    <div id="div1">
      <label for="dateTime">Default</label>
      <input id="dateTime" data-bind="ojComponent: {component: 'ojInputDateTime', value: value}"/>
      <br/><br/>
      <span class="oj-label">Current component value is:</span>
      <span data-bind="text: value"></span>
    </div>
    
  5. To modify the ViewModel, remove unneeded content, and add the new content as needed. Include any additional RequireJS modules that your new content may need.

    The application's main.js file contains the list of Require modules currently included in the application. Compare the list of libraries with the list you need for your application, and add any missing modules to your define() function in the ViewModel script. For example, to use the ojInputDateTime components shown in the Date and Time Pickers, add ojs/ojdatetimepicker to the home.js ViewModel script since it's not already defined in main.js.

    The sample below shows the modified home.js file, with the changes highlighted in bold.

    define(['ojs/ojcore' ,'knockout', 'ojs/ojdatetimepicker'
       ], function(oj, ko) {
       /**
        * The view model for the main content view template
        */
      function mainContentViewModel() {
        var self = this;
        self.value = ko.observable(oj.IntlConverterUtils.dateToLocalIso(new Date(2013, 0, 1)));
      }
    
      return mainContentViewModel;
    });
    

    If you're not using a Cookbook example and are not sure which Require module to include, see the table at Oracle JET Module Organization.

  6. If you want to add, change, or delete modules or templates to the application, modify the main.js RequireJS bootstrap file as needed.
    The file also contains the event handler that responds when a user clicks one of the navigation buttons. Depending upon your modifications, you may need to update this method as well.
  7. Run the index.html file in your favorite browser and verify the change.

    The following image shows the runtime view of the QuickStart Basic application with the new Home Content Area content showing the ojInputDateTime component with its current value.

    The image is described in the surrounding text.

    The main container is defined using best practice for responsive design. You can resize the container to see its effect. For additional information about responsive design, see Designing Responsive Applications.