Working with the Oracle JET Starter Templates

The Oracle JET Starter Templates provide everything you need to start working with code immediately. Use them as the starting point for your own application or to familiarize yourself with the JET components and basic structure of an Oracle JET application.

Each template is designed to work with the Oracle JET Cookbook examples and follows current best practice for application design.

Topics:

You can also view a video that shows how to work with the Oracle JET Starter Templates in the Oracle JET Videos collection.

About the Starter Templates

Each template in the Starter Template collection 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 the oj-module component to bind either a 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 the index.html file in the Web Nav Drawer Starter Template that highlights the oj-module component definition. For the sake of brevity, most of the code and comments are omitted. Comments describe the purpose of each section, and you should review the full source code for accessibility and usage tips.

<!DOCTYPE html>
<html lang="en-us">
  <head>
    <title>Oracle JET Starter Template - Web Nav Drawer</title>
       ... contents omitted
  </head>
  <body class="oj-web-applayout-body">

    ... contents omitted

     <oj-module role="main" class="oj-web-applayout-max-width oj-web-applayout-content" config="[[moduleConfig]]">
     </oj-module>
     
     ... contents omitted

         <script type="text/javascript" src="js/libs/require/require.js"></script>
         <script type="text/javascript" src="js/main.js"></script>
  </body>
</html>

The main page’s content area uses the Oracle JET oj-web-applayout-* CSS classes to manage the responsive layout. The main page’s content uses the HTML oj-module element with its role defined as main (role="main") for accessibility.

The oj-module component’s config.view attribute tells Oracle JET that the section is only defining a view template, and the view will be bound to the existing viewModel. When the oj-module element’s config.view-model attribute is defined, the application will load both the viewModel and view template with the name corresponding to the value of the config.view-model attribute.

When the oj-module element’s view and view-model attributes are missing, as in this example, the behavior will depend on the parameter specified in the config attribute’s definition.

If the parameter is an Oracle JET router’s moduleConfig object as in the above example, then oj-module will automatically load and render the content of the viewModel script and view template corresponding to the router’s current state.

The Web Nav Drawer Starter Template uses oj.Router to manage navigation when the user clicks one of the application’s navigation items. The router states include dashboard, incidents. customers, , and about. If the user clicks Incidents, for example, the main content area changes to display the content in the incidents view template.

Description of the illustration gs_qs_incidents.png
If the parameter is a Knockout observable containing the name of the viewModel, the application will load both the viewModel and view template with the indicated name.

The site_root/js/views folder contains the view templates for the application. site_root/js/viewModels contains the viewModel scripts. The image below shows the Web Nav Drawer Starter Template file structure in the NetBeans IDE.

Description of gs_qs_file_structure.png follows

Description of the illustration gs_qs_file_structure.png

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

For details about the oj-web-applayout-* CSS classes, see Web Application Patterns. For additional information about working with responsive design, see Designing Responsive Applications.

Modifying Starter Template Content

To add content, modify the appropriate view template and ViewModel script (if it exists) for the section that you want to update. Add any needed RequireJS modules to the ViewModel’s define() 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.

Before you begin:

Create your Oracle JET application using one of the following methods:
Load the starter template into your favorite IDE, or extract the zip file into a development folder.

The example in the procedure below uses the Web Nav Drawer Starter Template, but you can use the same process on any of the Starter Templates.

Tip:
If you used the command line tooling to scaffold your application, you can still use an IDE like NetBeans for editing. For example, in the NetBeans IDE, choose File –> Open Project and select the folder containing the application you created. Edit your application as needed, but use the tooling commands in a terminal window to build and serve your application.

To modify the Starter Template content:

In the application’s index.html file, locate the oj-module element for the section you want to modify and identify the template and optional ViewModel script.
In the Web Nav Drawer Starter Template, the oj-module element is using the config attribute. The following code sample shows the mainContent HTML oj-module definition in index.html .
```
<oj-module role="main" class="oj-web-applayout-max-width oj-web-applayout-content"
           config="[[moduleConfig]]">
</oj-module>
```
The return value of [[moduleConfig]] is set to the current state of the ojRouter object. The ojRouter object is defined with an initial value of dashboard in the application's appController.js script, shown below.
```
// Router setup
self.router = oj.Router.rootInstance;
self.router.configure({
  'dashboard': {label: 'Dashboard', isDefault: true},
  'incidents': {label: 'Incidents'},
  'customers': {label: 'Customers'},
  'about': {label: 'About'}
});
oj.Router.defaults['urlAdapter'] = new oj.Router.urlParamAdapter();
```
To modify the Dashboard Content Area, for example, you will modify both dashboard.html and dashboard.js.
To modify the view template, remove unneeded content, and add the new content to the view template file.
For example, if you are working with an Oracle JET Cookbook sample, you can copy the markup into the view template you identified in the previous step (dashboard.html). Replace everything after the <h1>Dashboard Content Area</h1> markup in the template with the markup from the sample.

The following code shows the modified markup if you replace the existing content with a portion of the content from the Date and Time Pickers demo.
```
<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>
```
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 oj-input-date-time elements shown in the demo, add ojs/ojdatetimepicker to the dashboard.js ViewModel script since it's not already defined in dashboard.js.

The sample below shows a portion of the modified dashboard.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 DashboardViewModel() {
    var self = this;
    self.value = ko.observable(oj.IntlConverterUtils.dateToLocalIso(new Date(2013, 0, 1)));
  }

  return DashboardViewModel;
});
```
Important:
Notice that with this example, you are not copying the entire code section. The Cookbook uses a require() call to load and use the needed libraries in a single bootstrap file. The Starter Template that you are pasting uses define() to create a RequireJS module that can be used by other parts of your application.

If you're not using a Cookbook example and are not sure which RequireJS module to include, see the table at Oracle JET Module Organization.
If you want to add, change, or delete modules or templates to the application, modify the main.js RequireJS bootstrap file and appController.js file as needed.
The appController.js file also contains the event handler that responds when a user clicks one of the navigation items. Depending upon your modifications, you may need to update this method as well.
Verify the changes in your favorite browser.

The following image shows the runtime view of the Web Nav Drawer Starter Template with the new Dashboard Content Area content showing oj-input-date-time with its current value.

Description of the illustration gs_quickstart_runtime.png