Using Knockout.js Templates and the ojModule Binding

The Oracle JET Cookbook and many sample applications use the native templating mechanism included with Knockout.js and the Oracle JET ojModule namespace to manage the binding. Knockout templates allow you to reuse code and provide a simple mechanism for building UI structures as a function of your viewModel data.

Knockout templates capture the HTML markup contained in an element and use it as a template to render against an arbitrary data item. For example, the Sample-SPA-ojModule-ojRouter single-page application uses various templates to define the HTML markup for the application. The image below shows the main page for the application as it runs on the desktop, with arrows pointing to the names of five such templates defining view content for the application.

Note:

The customers.html template has children templates to display details of a single customer, list of customers, orders for a customer, and details of a specific order.

The home template is shown below. In the highlighted code, the first data-bind definition uses Knockout's text binding to set the h1 element's content to a text node containing the value of title. The second data-bind definition uses Knockout's foreach binding to iterate through the content, and the list items display the text defined in line.

<div class="oj-flex oj-flex-items-pad">
  <div class="oj-xl-9 oj-lg-9 oj-md-9 oj-sm-12 oj-flex-item">
    <div role="main" class="oj-panel demo-page-content-area">
      <h2 data-bind="text: title"></h2>
      <!-- ko foreach: description -->
        <p data-bind="text: line"></p>
      <!-- /ko -->
    </div>
  </div>
  <div class="oj-xl-3 oj-lg-3 oj-md-3 oj-sm-12 oj-flex-item">
    <div class="oj-panel oj-panel-alt2 demo-page-content-area">
      <p>Click on the navigation buttons to switch which component is displayed in this page.</p>
          <p>To enter the Admin page, you must turn on the switch that says you are the Admin. 
             This is an example of the canEnter method and is defined in the router configuration.</p>
    </div>
  </div>
</div>

The code that defines the title and line is contained in the viewModel for the home section's content, stored in the home.js viewModel.

/* Home content module, example of singleton view model object. */
define(['knockout'], function(ko) {
  var viewModel = {
    title: 'Responsive Web Application with router',
    description:[{ 
               line: 'This application demonstrates the Responsive Web Application pattern using the \
JET router for navigation.'
      },{
        line: 'This text is from the home module.'
      }]
  };
  return viewModel;
});

To add Knockout.js templates and the ojModule binding to your Oracle JET application:

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

  1. To modify the default location of the application’s view templates and viewModel scripts, add code to the application's main script that initializes the location of the viewModels and view templates and defines the suffix for the view templates.

    The ojModule binding namespace contains the default location and names of managed templates and viewModels.

    Property Description

    viewPath

    Defines the path to the view templates. Defaults to text!..views/

    viewSuffix

    Defines the suffix for view templates. Defaults to .html.

    modelPath

    Defines the location of the viewModel scripts. Defaults to viewModels/

    The Oracle JET Sample-SPA-ojModule-ojRouter application uses the default locations and paths for its view templates and viewModels. If you want to modify the paths, you can add the following code to your main application script, substituting the paths appropriate for your application.

    oj.ModuleBinding.defaults.modelPath = 'modules/';
    oj.ModuleBinding.defaults.viewPath = 'text!../templates/';
    oj.ModuleBinding.defaults.viewSuffix = '.tmpl.html';
    
  2. In your RequireJS bootstrap file (typically main.js) add ojs/ojmodule to the list of RequireJS modules, along with any other modules that your application uses.

    require(['ojs/ojcore', 'knockout', 'jquery', 'ojs/ojknockout', 'ojs/ojmodule', 'ojs/ojrouter', 'text'],
    
  3. If needed, create a templates folder in the default location or in the viewPath if you defined one in the previous step.

  4. Create your view templates and add them to the viewPath folder.

    Use the default viewSuffix or the value you set for the viewSuffix in Step 1.

  5. If needed, create a folder for your viewModels in the default location or in the modelPath you specified in Step 1.

  6. As needed, create your viewModel scripts and add them to the modelPath folder.

    Use the same name for the module that you used for the template in Step 4. For example, if your template is named customers.html, use customers.js for the viewModel's name.

  7. Add code to the application's HTML page to reference the view template or viewModel in the ojModule binding.

    If the page section contains only a view template, use ojModule with the viewName option:

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

    To reference a viewModel with a view template, use ojModule with the name option:

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

    If you're using oj.Router, use ojModule with the router.moduleConfig option.

    <div id="content" role="main" class="oj-panel" style="padding-bottom:30px" data-bind="ojModule: router.moduleConfig"></div>
    

For more information about oj.Router and ojModule, see the Oracle JET oj.Router and ojModule API documentation.

For more information about using Knockout's template binding, see http://knockoutjs.com/documentation/template-binding.html.