Getting Started with Oracle JET Web Application Development

Developing client-side web applications with Oracle JET is designed to be simple and efficient using the development environment of your choice and Starter Templates to ease the development process.

Oracle JET includes several options for downloading, installing, and creating web applications. Depending upon your application requirements, you can:

  • Use the Oracle JET Yeoman generator to scaffold a web application containing either a blank template or a complete pre-configured sample application that you can modify as needed.

    With this method, you can use Grunt to build the application, serve it in a local web browser, and create a package ready for deployment. This is the preferred approach and recommended if you also plan on creating hybrid mobile applications.

    Note:

    For additional information about creating hybrid mobile applications, see Getting Started with Oracle JET Hybrid Mobile Application Development.
  • Download Oracle JET with a Starter Template ready to run and display in your local browser.

    With this method, you can get up and running quickly, but it will be up to you to package and deploy your application, using whatever method is appropriate for your use case.

  • Download the Oracle JET zip distribution which contains the Oracle JET and third-party libraries, CSS and SCSS files, and a RequireJS bootstrap file.

    With this method, you must manually create the index.html or main application file and pull in the appropriate libraries and CSS as needed. This method is best if you want to use your own application design pattern instead of the templates included with the tooling or Oracle JET Starter collection.

  • Add Oracle JET to an existing JavaScript application.

    With this method, you overlay the pieces of Oracle JET that you need to your existing JavaScript application and modify your main application file and scripts as needed.

Topics:

Create a Web Application Using the Oracle JET Tooling Framework

The Oracle JavaScript Extension Toolkit (JET) framework includes tooling to support web application development, and you can use it to create, build, and serve Oracle JET web applications that run in desktop and mobile browsers.

Before you can create your first Oracle JET web application using the tooling framework, you must also install the prerequisite packages if you haven’t already done so. For details, see Install the Prerequisite Packages.

Note:

You can also use the tooling framework to create hybrid mobile applications. For additional information, see Getting Started with Oracle JET Hybrid Mobile Application Development

Scaffold a Web Application with Yeoman

Use the Yeoman generator to scaffold an application that contains a blank template or one pre-configured with a basic layout, navigation bar, or navigation drawer. Each pre-configured template is optimized for responsive web or hybrid mobile applications. After scaffolding, you can modify the directory structure or add additional libraries.

The following image shows the differences between the pre-configured templates. The blank template contains an index.html but no display and is not shown. The basic:web template is similar to the blank template but adds responsive styling that will adjust the display when the screen size changes. The navbar:web and navdrawer:web templates contain sample content and follow best practices for layouts and styling that you can also modify as needed.

Note:

Do not confuse the basic template which contains no content with the Oracle JET QuickStart Basic application available in NetBeans 8.2 examples. The NetBeans application uses the navdrawer:web layout shown above and contains the same sample content.

If you want your web application to look more like a mobile application, you can scaffold your web application with a hybrid mobile version of the basic, navbar, or navdrawer template: basic:hybrid, navbar:hybrid, or navdrawer:hybrid.

  1. At a command prompt, enter yo oraclejet with optional arguments to create the Oracle JET application and scaffolding.
    yo oraclejet [directory] [--template={template-name:[web|hybrid]|template-url|template-file}] [--help]
    

    The following table describes the available options and provides examples for their use.

    Tip:

    You can also enter yo ––help at a terminal prompt to get additional help with Yeoman and a list of available generators and sub-generators.
    Option Description

    directory

    Application location. If not specified, the application is created in the current directory. The directory will be created during scaffolding if it doesn’t already exist.

    template

    Template to use for the application. Specify one of the following:

    • template-name

      Predefined template. You can enter blank, basic, navbar or navdrawer . Defaults to blank if not specified.

      Optionally, add :web or :hybrid to the template name to specify web or hybrid mobile styling. By default template will use the web styling, but you can add :hybrid to change the styling to hybrid mobile, typically basic:hybrid, navbar:hybrid or navdrawer:hybrid.

    • template-URL

      URL to zip file containing the name of a zipped application: http://path-to-app/app-name.zip.

    • template-file

      Path to zip file on your local file system containing the name of a zipped application: "path-to-app/app-name.zip". For example:
      --template="C:\Users\SomeUser\app.zip"
      --template="/home/users/SomeUser/app.zip"
      --template="~/projects/app.zip"
      

    help

    Displays a man page for the oraclejet Yeoman generator, including usage and options: yo oraclejet --help.

    For example, the following command will create a web application in the web-app-navbar directory using the navbar template with responsive styling:

    yo oraclejet web-app-navbar --template=navbar
    

    To scaffold the web application with the hybrid mobile version of the navbar template, enter the following command:

    yo oraclejet web-app-navbar --template=navbar:hybrid
    

    The scaffolding will take some time to complete. When successful, the terminal will display:

    Done, without errors.
    Oracle JET: Your app is ready! Change to your new app directory web-app-navbar and try grunt build and serve...
    

    The new application will have a directory structure similar to the one shown in the following image.

    The application folders contain the application and configuration files that you will modify as needed for your own application.

    Directory Description

    node_modules

    Contains the Node.js modules used by the tooling framework.

    scripts

    Contains the oraclejet-build.js and oraclejet-serve.js files that you can modify to customize your application’s build and serve steps. See Customize a Web Application’s Grunt Build Behavior and Customize a Web Application’s Grunt Serve Behavior.

    src

    Contains the application’s index.html file that you modify as needed for your application. Depending upon the template, src will also contain JavaScript libraries and Alta CSS files.

    If you want to make modifications to the CSS, you can use the tooling framework to create a custom theme. For details, see Customizing Themes Using the Tooling Framework.

  2. In your development environment, update the code for your application.

    For example, you can modify the content to contain samples from the Oracle JET Cookbook. For details about modifying content in pre-configured templates, see Working with the Oracle JET Web Nav Drawer Starter Template.

    Tip:

    If you selected the blank template during scaffolding, you can still follow the same process to add cookbook samples or other content to your application. However, it will be up to you to create the appropriate view templates or viewModel scripts.

After scaffolding, you can perform the following optional tasks to customize your application:

Modify the Web Application’s File Structure

You can modify your scaffolded application’s file structure if the default structure doesn’t meet your needs.

The oraclejetconfig.json file in your application’s top level directory contains the default source and staging file paths that you can modify.

{
  "paths": {
    "source": {
      "common": "src",
      "web": "src-web",
      "hybrid": "src-hybrid",
      "javascript": "js",
      "styles": "css",
      "themes": "themes"
    },
    "staging": {
      "web": "web",
      "hybrid": "hybrid",
      "themes": "themes"
    }
  },
  "generatorVersion": "x.x.x"
}

To change the web application’s file structure:

If needed, scaffold your web application as described in Scaffold a Web Application with Yeoman.

  1. In your application’s top level directory, open oraclejetconfig.json for editing.
  2. In oraclejetconfig.json, change the paths as needed and save the file.

    For example, if you want to change the default styles path from css to app-css, edit the following line in oraclejetconfig.json:

    "styles": "app-css"
    
  3. Rename the directories as needed for your application, making sure to change only the paths listed in oraclejetconfig.json.
    For example, if you changed styles to app-css in oraclejetconfig.json, change the application’s css directory to app-css.
  4. Update your application files as needed to reference the changed path

    For example, if you modified the path to the CSS for your application to app-css, update the links appropriately in your application’s index.html.

    <link rel="icon" href="app-css/images/favicon.ico" type="image/x-icon" />
    
        <!-- This is the main css file for the default Alta theme -->
        <!-- injector:theme -->
        <link rel="stylesheet" href="app-css/libs/oj/vx.x.x/alta/oj-alta-min.css" type="text/css"/>
        <!-- endinjector -->
        
        <!-- This contains icon fonts used by the starter template -->
        <link rel="stylesheet" href="app-css/demo-alta-site-min.css" type="text/css"/>
    
        <!-- This is where you would add any app specific styling -->
        <link rel="stylesheet" href="app-css/override.css" type="text/css"/>
    
To use the new paths, in your application’s top level directory, build your application as described in Build a Web Application with Grunt.

Add Hybrid Mobile Features to Web Applications

Add Cordova hybrid mobile platforms to your web application using the yo oraclejet:add-hybrid command. When you run this command, the tooling framework creates a Cordova project and new hybrid-src and web-src directories, enabling you to create both web and hybrid mobile applications from the same source.

To add hybrid mobile platforms to your web application:

If needed, install the mobile tooling packages as described in Install the Mobile Tooling.

  1. At a terminal prompt, in your application’s top level directory, enter the following command to add hybrid mobile features to your web application:
    yo oraclejet:add-hybrid --platforms=android,ios,windows [--appid=application-id] [--appname=application-name] [--help]
    

    You must specify at least one platform for the platforms value. Add additional platforms as needed, separated by commas.

    --platforms=android
    --platforms=ios,windows
    

    The platforms, appid, appname, and help options use the same values as the yo oraclejet:hybrid command described in Scaffold a Hybrid Mobile Application with Yeoman

    When you run the command, Oracle JET tooling creates the Cordova project and two new empty source directories that you can use for platform specific content: src-hybrid and src-web.

    Note:

    The file locations will vary for this step and the remaining steps in this procedure if you modified your directory structure as described in Modify the Web Application’s File Structure or Modify the Hybrid Mobile Application’s File Structure.
  2. To make changes to content that apply to both web and hybrid platforms, edit content in src.
  3. To make changes to content that apply only to the web or hybrid platform, add the new content to src-web or src-hybrid as needed.
    When you build your application, the content in the platform specific file takes precedence over content in src. For example, if you create a new index.html file to src-hybrid, content in that file will take precedence when you build the application as a hybrid mobile application.

Build a Web Application with Grunt

Use Grunt with the build option to build a development version of your web application before serving it to a browser. This step is optional.

Change to the application’s root directory and use the grunt build command to build your application.

grunt build [--theme=themename[:android|ios|web|windows] --themes=theme1,theme2,... --no-sass]

The following table describes the available options and provides examples for their use.

Tip:

You can also enter grunt help at a terminal prompt to get command line help specific to the Oracle JET tooling and grunt ––help to get additional help with grunt options.
Option Description

theme

Theme to use for the application. The theme defaults to alta:web, but you can specify a hybrid mobile theme (alta:android, alta:ios, alta:windows) if you want your application to have the look and feel of a mobile application.

You can also enter a different themename with optional platform for a custom theme as described in Customizing Themes Using the Tooling Framework.

themes

Themes to include in the application, separated by commas.

If you don’t specify the --theme flag as described above, Oracle JET will use the first element that you specify in --themes as the default theme. Otherwise grunt will build the application with the theme specified in --theme.

no-sass

Suppresses Sass compilation. Use this option if you’re Customizing Themes Using the Tooling Framework and don’t want to compile Sass during this build.

The command will take some time to complete. If it’s successful, you’ll see the following message:
Done, without errors.

The command will also create a web folder in your application’s root to contain the built content.

Note:

You can also use the grunt build command with the :release option to build a release-ready version of your application. For information, see Packaging and Deploying Web Applications.

Customize a Web Application’s Grunt Build Behavior

Edit oraclejet-build.js to modify default build behavior. For example, you can add additional libraries to your application or change the default markers used to inject links into the application’s index.html during build time.

The Oracle JET tooling framework defines default build and serve behavior in node_modules/oraclejet-tooling/lib/defaultconfig.js. The first part of the file contains the default build configuration, including entries for application paths and other options used during the build process. To modify defaults or add your own, edit oraclejet-build.js and remove comments from the options that you want to configure. The file contains detailed instructions for each configurable option.

Oracle JET will merge the options with the default configuration during the build. However, be aware that fileList options will completely replace the corresponding option in the default configuration and will not be merged.

To customize Grunt build behavior:

  1. Open scripts/grunt/config/oraclejet-build.js for editing in your favorite text editor.
  2. Identify the entry that you want to change and remove the comments (//) preceding each line.

    For example, to add a custom library to the build’s staging directory, remove the comments from the following sections in oraclejet-build.js as shown below:

    /**
     * # copyCustomLibsToStaging
     * This task copies any custom libraries that are not provided by JET to staging directory.
     * This task supports a single option: fileList. The fileList option defines an array of file objects. 
     * Each file object contains the following properties: 
     *   cwd, current working directory
     *   dest, destination path
     *   src, array of source file patterns
     *   rename, function to return the full path of desired destination
     * If a fileList value is specified, it completely replaces the default fileList value defined by JET
     * Example: {cwd: 'app', src: ['**', '!test.js'], dest: 'staging',  rename: function (dest, file) {return renamed path}}
     */
         copyCustomLibsToStaging: {
           fileList: []
         },
    
    
  3. Edit the options as desired and save the file.

    For example, to add a custom library named my_custom_module, place the module in node_modules, and edit the copyCustomLibsToStaging entry:

    copyCustomLibsToStaging: {
        fileList: [
                  {cwd:'node_modules/my_custom_module/',
                   src: ['*'],
                   dest: 'web/js/libs/my_custom_module'   }
                  ]
    },
    
  4. Repeat the previous step for each option that you want to modify.

    For example, to change the default injection marker defined in injectTheme, remove the comments from the injectTheme option and add the appropriate marker:

    /**
     * # injectTheme
     * This task injects css stylesheet links for the current theme into index.html using the injection start and end markers defined below.
     */
        injectTheme: {
        startTag: '<!-- injector:mycustomtheme -->',
      }
    
Test your changes by running Build a Web Application with Grunt with appropriate options.

Serve a Web Application with Grunt

Use Grunt with the serve option to run your web application in a local web server for testing and debugging. By default, a live reload option is enabled which lets you make changes to your application code that are immediately reflected in the browser.

Enter the following commands at a terminal prompt:
  1. Change to the application’s root directory and use the grunt serve command with optional arguments to launch the application.
    grunt serve [--server-port=server-port-number --livereload-port=live-reload-port-number --no-livereload --no-sass --no-build --theme=themename[:android|ios|web|windows] --themes=theme1,theme2,...]
    

    The following table describes the available options and provides examples for their use.

    Tip:

    You can also enter grunt help at a terminal prompt to get help specific to the Oracle JET tooling commands and grunt ––help to get additional help with grunt options.
    Option Description

    server-port

    Server port number. If not specified, defaults to 8000.

    livereload-port

    Live reload port number. If not specified, defaults to 35729.

    no-livereload

    Disables live reload.

    Disabling live reload can be helpful if you’re working in NetBeans or other IDE and want to use that IDE’s mechanism for loading updated applications.

    no-sass

    Suppresses Sass compilation. Use this option if you’re Customizing Themes Using the Tooling Framework and don’t want to compile or watch Sass during this build.

    no-build

    Suppresses the build. Use this option if you’ve already built the application and just want to serve it.

    theme

    Theme to use for the application. The theme defaults to alta:web, but you can specify a hybrid mobile theme (alta:android, alta:ios, alta:windows) if you want your application to have the look and feel of a mobile application.

    You can also enter a different themename with optional platform for a custom theme as described in Customizing Themes Using the Tooling Framework.

    themes

    Themes to use for the application, separated by commas.

    If you don’t specify the --theme flag as described above, Oracle JET will use the first element that you specify in --themes as the default theme. Otherwise grunt will serve the application with the theme specified in --theme.

    For example, the following command will launch your application in the default web browser with live reload enabled: grunt serve.

  2. Make any desired code change in the src folder, and the browser will update automatically to reflect the change unless you set the no-livereload flag.

    While the application is running, the terminal window remains open, and the watch task waits for any changes to the application. For example, if you change the content in src/js/views/dashboard.html , the watch task will reflect the change in the terminal as shown below on a Windows desktop.

  3. To terminate the process, close the application and press Ctrl+C in the command window.
    You may need to enter Ctrl+C a few times before the process terminates.

Note:

You can also use the grunt serve command with the :release option to serve a release-ready version of your application previously built with the :release option. For information, see Packaging and Deploying Web Applications.

Customize a Web Application’s Grunt Serve Behavior

Edit oraclejet-serve.js to modify default serve behavior. For example, you can add your own watch tasks or specify actions specific to web or hybrid applications.

The Oracle JET tooling framework defines default build and serve behavior in node_modules/oraclejet-tooling/lib/defaultconfig.js. The second half of the file contains the default serve configuration, including entries for application paths and other options used during the serve process. To modify defaults or add your own, edit oraclejet-serve.js and remove comments from the options that you want to configure. The file contains detailed instructions for each configurable option.

Oracle JET will merge the options with the default configuration during the build. However, be aware that rewriting the three default watch targets (sourceFiles, sass, and themes) can result in unpredictable behavior.

To customize Grunt serve behavior:

  1. Open scripts/grunt/config/oraclejet-serve.js for editing in your favorite text editor.
  2. Identify the entry that you want to change and remove the comments (//) preceding each line that you want to include.

    For example, to define one or more shell commands that you want to execute after grunt serves the application and you modify a source file, you can edit the sourceFiles option in the watch sub task. Remove the comments from the highlighted lines as shown below.

    // // Sub task watch default options
         watch: {
           sourceFiles:
           {
        //     files: [],
        //     options: {
        //       livereload: true
        //     },
                   commands: ['']
           },
    
        //   sass: {
        //     files: [],
        //     commands: ['compileSass']
        //   },
    
        //   themes: {
        //     files: [],
        //     options: {
        //       livereload: true
        //     },
        //     commands: ['copyThemes']
        //   },
         },
    
  3. Edit the options as desired and save the file.
    For command options, add one or more commands, each surrounded by single quotes and separated by commas. For example, the following code snippet adds node --version and npm --version to the commands option in the sourceFiles sub task:
         watch: {
           sourceFiles:
           {
        //     files: [],
        //     options: {
        //       livereload: true
        //     },
                   commands: ['node --version', 'npm --version']
           },
           ... contents omitted
         },
    
Test your changes by running Serve a Web Application with Grunt with appropriate options. When you change one of the source files, the terminal output will display the output of the node --version and npm --version commands and reload the page.

Create a Web Application Using the oraclejet.zip Download

You can create a new Oracle JET application in your favorite IDE or text editor using files extracted from oraclejet.zip. After you create your application, you can modify it to include references to Oracle JET CSS and libraries.

Topics

Download the Oracle JET Zip File

You can download Oracle JET from the Oracle Technology Network (OTN) as a single zip file. The zip file contain the libraries, scripts, styles, and files needed to develop applications using Oracle JET.

To download Oracle JET from the Oracle Technology Network (OTN):

  1. Navigate to the Oracle JET download location at: Oracle JET Downloads.

  2. Choose Accept License Agreement.

  3. Download Oracle JavaScript Extension Toolkit: Base Distribution.

Tip:

If you plan to use NetBeans 8.2 or higher for developing your Oracle JET application, you can skip this step. The NetBeans IDE’s Oracle JET Base Distribution Sample already includes oraclejet.zip. For details, see Create an Oracle JET Application in the NetBeans IDE

Create an Oracle JET Application in the NetBeans IDE

You can use NetBeans 8.2 or higher to create an Oracle JET application using the NetBeans Oracle JET Base Distribution, which includes the oraclejet.zip download.

To create an Oracle JET application in the NetBeans IDE:

  1. If needed, download and install NetBeans. Select a download bundle that includes support for HTML5. For additional detail, see https://netbeans.org/downloads/index.html.
  2. In the NetBeans IDE, choose File > New Project from the main menu.

  3. In the New Project dialog, create a new HTML5/JavaScript application.

    1. In the Categories area, click HTML5/JavaScript.

    2. In the Projects area, click Oracle JET Base Distribution.

      In this example, the All download bundle is used for the initial NetBeans 8.2 download. If you downloaded a different NetBeans download bundle or are using a different version, the dialog may include different categories.

    3. Click Next.

  4. In the New Oracle JET Base Distribution dialog, configure the project name and project location.

    1. In the Project Name field, enter a name for your project.

    2. In the Project Location field, enter a location to store the project files.

      In this example, the project is named OracleJETApplication1, and the project files will be stored in the C:\NetBeansProjects\ directory.

  5. Click Finish to create your application.

    When you click Finish, NetBeans creates the project from the Oracle JET Base Distribution. You can expand the js/libs/ directory to see the JavaScript libraries that constitute Oracle JET. This figure shows the project files and README.md file that NetBeans 8.2 generated for a project named OracleJETApplication1 with no optional tools installed.

    Note:

    If you decide you want to use one of the tools after you create your application, you can add it in the NetBeans IDE. Choose Tools, then Options, and HTML/JS. Select the tab containing the tool you wish to add, and select the option to install the package.

Include References to CSS Files in Your Oracle JET Application

Specify the reference to the CSS files directly in your application’s main page, typically index.html.

If needed, download Oracle JET as described in Download the Oracle JET Zip File.

  1. Create a new index.html file in the project root.
  2. In the application’s main page, index.html, add the HTML link element and point it to the CSS theme that you will use.

    For example, to use the Oracle JET Alta web theme:

    <!-- Oracle JET CSS files -->
    <link rel="stylesheet" href="css/libs/oj/version/alta/oj-alta-min.css" type="text/css"/>
    

    For additional information about Oracle JET and the themes available for your use, see Theming Applications.

  3. If you will be using the CSS included with Oracle JET, add the following line to the top of your application’s main HTML page:
    <!DOCTYPE html>
    

    This line is needed for the Oracle JET CSS to function as expected.

Use RequireJS to Manage Library, Link, and Script References

RequireJS is a JavaScript file and module loader that makes it easier to manage library references and is designed to improve the speed and quality of your code.

Oracle JET uses RequireJS by default for the Oracle JET Starter Templates and is required if you plan to use Oracle JET's internationalization, data visualization components, or the oj.OAuth plugin in your application.

To use RequireJS to manage references:

If needed, download Oracle JET as described in Download the Oracle JET Zip File.

  1. Copy js/libs/oj/version/main-template.js to the js folder.
  2. In the js folder, rename main-template.js to main.js.
  3. Add the following script reference to your index.html file:
    <script data-main="js/main" src="js/libs/require/require.js"></script>
    
  4. Update main.js as needed to reference Oracle JET modules or your own scripts.

    For a list of Oracle JET modules and additional details about using RequireJS in your Oracle JET application, see Using RequireJS for Modular Development.

For more information about RequireJS, see http://requirejs.org.

Specify Library, Link, and Script References Without RequireJS

You can specify the Oracle JET script and link references directly in your index.html or main application file without using RequireJS.

If you know that your application will not need RequireJS, you can add script references specifying the library links. However, Oracle JET requires its use for major pieces of the Oracle JET framework, such as internationalization and data visualization components.

To specify library, link, and script references without using RequireJS to manage references:

If needed, download Oracle JET as described in Download the Oracle JET Zip File.

  1. If your application will run on devices that support touch, add the following entry to your index.html inside the head element to eliminate tap delay:
    <head>
    ...
    <meta name="viewport" content="width=device-width">
    ...
    </head>
    
    This entry has the effect of disabling double tap to zoom on supported browsers. If you don’t add this entry, browsers will wait approximately 300 to 350 milliseconds to see if the first tap is followed by another before firing the click event on the first tap.

    Note:

    Due to lack of universal browser support, you should also add the following entry to your CSS if you’re not using one of the themes included with Oracle JET:
    body { 
      touch-action: manipulation;
    } 
    
  2. Add the following script references as needed, inside the head element in your index.html file:
    <head>
    ...
    <!-- 3rd Party JavaScript files -->
    <script type="text/javascript" src="js/libs/knockout/knockout-3.4.0.js"></script>
    <script type="text/javascript" src="js/libs/jquery/jquery-3.1.1.min.js"></script>
    <script type="text/javascript" src="js/libs/jquery/jquery-ui-1.12.0.custom.min.js"></script>
    <script type="text/javascript" src="js/libs/knockout/knockout.mapping-latest.js"></script>
    <script type="text/javascript" src="js/libs/js-signals/signals.min.js"></script>
    <script type="text/javascript" src="js/libs/es6-promise/es6-promise.min.js"></script>
    <script type="text/javascript" src="js/libs/hammer/hammer-2.0.8.min.js"></script>
    <script type="text/javascript" src="js/libs/require-css/css.min.js"></script>
    <script type="text/javascript" src="js/libs/proj4js/dist/proj4.js"></script>
    
    <!-- Oracle JavaScript files -->
    <script type="text/javascript" src="js/libs/dnd-polyfill/dnd-polyfill-1.0.0.min.js"></script>
    <script type="text/javascript" src="js/libs/oj/v3.1.0/min/oj.js"></script>
    <script type="text/javascript" src="js/libs/webcomponents/CustomElements.min.js"></script>
    ...
    </head>
    

    If you want to use the design time Oracle JET libraries for debugging, replace the min/oj.js reference with:

    <script type="text/javascript" src="js/libs/oj/v3.1.0/debug/oj.js"></script>
    

Create a Web Application Using the Oracle JET Starter Templates

You can load the Oracle JET Starter Templates in NetBeans 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 application files.

Topics:

Downloading Oracle JET with a Starter Template

You can download any of the applications in the Oracle JET Starter Template collection to get Oracle JET. The Web Nav Drawer Starter Template contains the Oracle JET bundle, an index.html file already configured for Oracle JET and is a good choice for getting started with Oracle JET.

Tip:

If you use the Yeoman generator to scaffold a web application with a navdrawer template as described in Scaffold a Web Application with Yeoman, then you already have a Starter Template and can skip this step.

Also, if you use NetBeans IDE version 8.2, it includes the Oracle JET QuickStart Basic project which contains the same content as the Web Nav Drawer Starter Template.

To download Oracle JET with a Starter Template:

  1. Navigate to the Oracle JET download location at: Oracle JET Downloads.

  2. Choose Accept License Agreement.

  3. Download the desired template.

    For example, to download the Web Nav Drawer template, select Web Nav Drawer Starter Template with Oracle JavaScript Extension Toolkit Pre-configured.

Loading the Oracle JET Starter Templates

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

You can also load the Oracle JET Starter Templates in the NetBeans IDE.

Create an Application in the NetBeans IDE with a Site Template

You can create a new Oracle JET application in the NetBeans IDE using files extracted from oraclejet.zip or any of the Oracle JET Starter Templates. NetBeans 8.1 and higher includes support for Oracle JET applications using the Oracle JET zip files as site templates in the NetBeans IDE.

To create an Oracle JET application in the NetBeans IDE using a site template:

Tip:

If you’re specifically interested in the Web Nav Drawer Starter Template, you can skip all steps following Step 1. In the NetBeans IDE, choose File > New Project, then in the Categories area, select Samples > HTML5/JavaScript, and select Oracle JET QuickStart Basic from the Projects list.
  1. If needed, download and install NetBeans. Select a download bundle that includes support for HTML5. For additional detail, see https://netbeans.org/downloads/index.html

  2. In the NetBeans IDE, click New Project.

  3. In the New Project dialog, create a new HTML5 application.

    1. In the Categories area, click HTML5/JavaScript.

    2. In the Projects area, click HTML5/JS Application.

      In this example, the HTML5 & PHP download bundle is used for the initial NetBeans 8.2 download, and the categories are limited to HTML5 and PHP. If you downloaded a different NetBeans download bundle or are using a different version, the dialog may include additional or different categories.

    3. Click Next.

  4. In the New HTML5/JS Application dialog, configure the project name and project location.

    1. In the Project Name field, enter a name for your project.

    2. In the Project Location field, enter a location to store the project files.

      In this example, the project is named OracleJETSample, and the project files will be stored in the C:\NetBeansProject directory.

    3. Click Next.

  5. In the New HTML5/JS Application dialog, specify the name of the site template.

    1. Choose Select Template.

    2. In the Template field, choose Browse and select the location containing the download bundle.

      In this example, the completed HTML5 Application dialog specifies C:\Downloads as the location for the JET-Template-Web-NavDrawer.zip file.

    3. Click Next.

  6. Optionally, in the New HTML5 Application Dialog, remove the check mark from any tools your application won’t need. By default, all tools are checked.

    Tip:

    If you decide you want to use one of the tools after you create your application, you can add it in the NetBeans IDE. Choose Tools, then Options, and HTML/JS. Select the tab containing the tool you wish to add, and select the option to install the package.
  7. Click Finish to create your application.

    When you click Finish, NetBeans creates the project and adds an index.html file to your project. This figure shows the project files and index.html file that NetBeans 8.2 generated for a project named OracleJETSample with no optional tools installed.

Run the Oracle JET Starter Templates in NetBeans

To run the Oracle JET Starter Templates in the NetBeans IDE:

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/docs/webclient/html5-gettingstarted.html.

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

Working with the Oracle JET Web Nav Drawer Starter Template

The Oracle JET Web Nav Drawer Starter Template in the Starter Template Collection 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 Starter Templates in the Oracle JET Videos collection.

About the Web Nav Drawer Starter Template

The Web Nav Drawer Starter 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 Knockout's data-bind syntax and the ojModule binding 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 index.html highlighting the ojModule binding 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

     <div role="main" class="oj-web-applayout-max-width oj-web-applayout-content" data-bind="ojModule: router.moduleConfig">
     </div>
     
     ... 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 div element with its role defined as main (role="main") for accessibility.

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. When the ojModule binding’s name option is defined instead, the application will load both the viewModel and view template with the name corresponding to the value of the name option.

When the ojModule binding’s name and viewName options are missing, as in this example, the behavior will depend on the parameter specified in the binding’s definition.
  • If the parameter is an Oracle JET router’s moduleConfig object as in the above example, then ojModule 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.

  • 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.

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

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

Modifying the Web Nav Drawer Starter Template 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 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:
  1. Download the Web Nav Drawer Starter Template as described in Downloading Oracle JET with a Starter Template.

  2. Load the Starter Template as described in Create a Web Application Using the Oracle JET Starter Templates.

To modify the Web Nav Drawer Starter Template content:

  1. In the index.html file, locate the ojModule binding for the section you want to modify and identify the template and optional ViewModel script.

    In the Web Nav Drawer Starter Template, the ojModule binding is using the router.moduleConfig parameter. The following code sample shows the mainContent HTML div definition in index.html .

    <div role="main" class="oj-web-applayout-max-width oj-web-applayout-content"
         data-bind="ojModule: router.moduleConfig">
    </div>
    

    The return value of router.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 .

  2. 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 the content from the Date and Time Pickers demo.

    <h3>Dashboard Content Area</h3>
    <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>
    
  3. 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 dashboard.js ViewModel script since it's not already defined in dashboard.js.

    The sample below shows 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 QuickStart page that you are pasting into is a RequireJS module which uses define() to create a module that can be used by other parts of your application.

    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.

  4. 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.
  5. Run the index.html file in your favorite browser and verify the change.

    The following image shows the runtime view of the Web Nav Drawer Starter Template with the new Dashboard Content Area content showing the ojInputDateTime component with its current value.

Add Oracle JET to an Existing JavaScript Application

You can add Oracle JET to your existing JavaScript application by extracting the oraclejet.zip file into the site root of your application and including references to the Oracle JET libraries and CSS as needed.

To add Oracle JET to an existing JavaScript application:

If needed, download oraclejet.zip as described in Download the Oracle JET Zip File.

  1. Extract oraclejet.zip into the site root of your application.

    For example, if your application's site root is Site Root, extract oraclejet.zip into Site Root. After extraction, your site root folder will contain the following Oracle JET files and folders as shown in the NetBeans IDE.

    The css folder contains the themes included with Oracle JET, and the scss folder contains the SASS source files for the Oracle JET themes. For additional information about Oracle JET theming, see Theming Applications.

    The js folder contains the Oracle JET libraries and third party libraries, and the buildnum and revnum files identify the Oracle JET build number and version. For additional information about the libraries included in Oracle JET, see What's Included in Oracle JET.

  2. If you want to use one of the themes included with Oracle JET, add the appropriate link to the CSS. For details, see Include References to CSS Files in Your Oracle JET Application.
  3. If you want to use the Oracle JET libraries, you can either specify the links directly in your main application file or use RequireJS to manage the Oracle JET library, link, and script references.