Adding Third-Party Tools or Libraries to Your Oracle JET Application

You can add third-party tools or libraries to your Oracle JET application. If you’re using RequireJS, you must update the bootstrap file. If you use the tooling framework, you must also install the library and make modifications to the scripts/grunt/config/oraclejet-build.js and js/main-release-paths.json files.

Note:

This process is provided as a convenience for Oracle JET developers. Oracle JET will not support the additional tools or libraries and cannot guarantee that they will work correctly with other Oracle JET components or framework features.

To add a third-party tool or library to your Oracle JET application:

  1. If you scaffolded your application using the tooling framework, do the following:

    1. In your main project directory, enter the following command to install the library using npm:

      npm install library-name --save
      

      For example, enter the following command to install a library named my-library:

      npm install my-library --save
      
    2. In the scripts/grunt/config directory, update the copyCustomLibsToStaging section in oraclejet-build.js file so that it copies your library to the application when you build the application.

      Open the file in your favorite text editor and remove the comments (//) from the copyCustomLibsToStaging section. Add the new libraries 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: [
                    {cwd:'node_modules/my-library/',
                     src: ['*'],
                     dest: 'web/js/libs/my-library' }
                    ]
      },
      
      
    3. In the js directory update the js/main-release-paths.json file to include the new library.

      Use the minified version if available as shown below. The tooling framework uses this file when you build your release version.

      {
          "knockout": "libs/knockout/knockout-x.x.x",
          "jquery": "libs/jquery/jquery-x.x.x.min",
          ... contents omitted
          "my-library": "libs/my-library/my-library.min"
      }
      
  2. If you didn’t use the tooling framework to create your application, in the application’s js/libs directory, create a new directory and add the new library and any accompanying files to it.

    For example, for a library named my-library, create the my-library directory and add the my-library.js file and any needed files to it. Be sure to add the minified version if available.

  3. In your RequireJS bootstrap file, typically main.js, add a link to the new file in the path mapping section and include the new library in the require() definition.

    For example, add the highlighted code below to your bootstrap file to use a library named my-library.

    requirejs.config({
      // Path mappings for the logical module names
      paths: 
      {
        'knockout': 'libs/knockout/knockout-3.4.0',
        'jquery': 'libs/jquery/jquery-3.1.0.min',
        ... contents omitted
        'text': 'libs/require/text',
        'my-library': 'libs/my-library/my-library
      }
      ,
      // Shim configurations for modules that do not expose AMD
      // Updated as needed for your library.
      shim: {
        'jquery': {
          exports: ['jQuery', '$']
        }
      },
      require(['ojs/ojcore', 'knockout', 'jquery', 'my-library'],
      function(oj, ko, $) // this callback gets executed when all required modules are loaded
      {
          // add any startup code that you want here
      }
    );
    

    For additional information about using RequireJS to manage your application's modules, see Using RequireJS for Modular Development.