4 Use RequireJS for Modular Development
About Oracle JET and RequireJS
RequireJS is a JavaScript file and module loader that simplifies managing library references and is designed to improve the speed and quality of your code.
RequireJS implements the Asynchronous Module Definition (AMD) API which provides a mechanism for asynchronously loading a module and its dependencies.
Oracle JET's modular organization enables app developers to load a subset of needed
features without having to execute require()
calls for each referenced
object. Each Oracle JET module represents one functional area of the toolkit, and it
typically defines more than one JavaScript object.
You do not have to use RequireJS to reference Oracle JET libraries, but it is required if you plan to use Oracle JET's internationalization or data visualization components in your app. The Oracle JET download includes the RequireJS library, and it is used by default in the Oracle JET Starter Templates and Cookbook examples.
For more information about RequireJS, see http://requirejs.org.
About Oracle JET Module Organization
The Oracle JET modules are listed in the following table with description and usage tips. Use this table to determine which modules you must load in your app. Where your app can directly interact with a module API, the available objects that the module returns also appear in the table. Your app would typically call functions on the returned object or instantiate new objects via the constructor function. For more information about module loading in Oracle JET apps, see API Reference for Oracle® JavaScript Extension Toolkit (Oracle JET) - JET Module Loading Overview.
Note:
Certain functionality that had been previously available from the now deprecated ojcore
, ojvalidation-base
, ojvalidation-datetime
, and ojvalidation-number
modules is provided by refactored modules that return their own object. The table indicates which modules have been refactored. You should explicitly import needed modules in the dependency list of your require function to use its classes.
Oracle JET Module | Refactored | Available Objects | Description | When to Use |
---|---|---|---|---|
|
No |
|
Classes of the JET Common Model |
Other than |
|
No |
|
Utilities for integrating Oracle JET's Common Model into Knockout.js |
Deprecated. Use the Oracle JET |
|
No |
Varies by component |
Oracle JET component modules. Examples include
Most Oracle JET components have their own module with the same name in lowercase and without hyphens as shown above, except for the following components:
|
Use component modules that correspond to any Oracle JET component in your app. |
|
No |
|
Oracle JET data binding for global attributes of any HTML element in the user interface |
Use when your app includes HTML elements (JET custom elements included) with databound global attributes (ones that use the : (colon) prefix) or that use the [[..]]/{{..}} syntax (for global attributes of custom elements). |
|
No |
|
Class for managing routing in single page apps |
Use if your single page app needs to manage routing. |
|
No |
|
Binding that implements navigation within a region of a single page app |
Use if your single page app needs to manage navigation within a page region. |
|
No |
|
Component that implements navigation within a region of a single page app |
Use if your single page app needs to manage navigation within a page region. |
|
No |
|
Used in conjunction with |
Use if your app adds animation effects. |
|
Yes, from |
|
Class that exposes the |
Use if your app needs to query the busy state of components on the page. |
|
Yes, from |
|
Class for setting and retrieving configuration options. |
Use if your app needs to set or retrieve app configuration details. |
|
Yes, from |
|
Utilities for setting up a logger and collecting logging information |
Use if your app needs to define logger callback functions. |
|
Yes, from |
|
Utilities for working with responsive screen widths and ranges. Often used in conjunction with |
Use if your app needs to work with responsive page design. |
|
Yes, from |
|
Utilities for getting theme information |
Use if your app needs to know about the theme's fonts or the target platform. |
|
Yes, from |
|
Utilities for time information |
Use if your app needs to calculate the position of a given time point within a range. |
|
Yes, from |
|
Service for retrieving translated resources |
Use if your app needs to work with translated resources. |
|
No |
|
Classes for managing attribute groups |
Use if your app needs to generate attribute values from data set values (key value pairs). |
|
No |
|
Utilities for converting Knockout templates to a renderer function that can be used in JET component renderer APIs |
Use if your app needs to work with Knockout templates. |
|
No |
|
Utilities for creating Knockout observables to implement responsive page design |
Use if your app needs to create observables for responsive page design. |
|
No |
|
Utilities for setting up and handling swipe to reveal on an offcanvas element |
Use if your app needs to support the swipe gesture. |
|
No |
|
Class for working with selection items in |
Use if your app needs to work with selections as a set. |
|
No |
|
Utilities for working with a JSON object to support the |
Use if your app creates an |
|
No |
|
Class for controlling off-canvas regions |
Use if your app needs to manage off-canvas regions. |
|
No |
|
Classes for aggregating data values in |
Use if your app renders aggregated cubic data in an |
|
No |
|
Data provider modules. Examples include:
|
Use if your app includes an Oracle JET component, and its data source is defined in
one of the |
|
No |
no public class available |
Time zone data |
Use if you want to add time zone support to |
|
Yes, from |
|
Color, date, and time conversion services. |
Use if your app needs to support conversion services. |
|
Yes, from |
|
Date and number validation services. |
Use if your app needs to support validation services. |
|
Yes, from |
|
Async date and number validation services. |
Use if your app needs to support async validation services. |
About RequireJS in an Oracle JET App
Oracle JET includes the RequireJS library and sample bootstrap file in the Oracle JET download.
The code below shows excerpts of the main-template.js
bootstrap file
distributed with the Oracle JET base distribution in the
appRootDir\node_modules\@oracle\oraclejet\dist\js\libs\oj\
directory.
Typically, you place the bootstrap file in your app's js
directory and rename
it to main.js
. The comments in the code describe the purpose of each
section. The sections that you normally edit are highlighted in bold.
/**
* Example of Require.js boostrap javascript
*/
(function () {
requirejs.config({
// Path mappings for the logical module names
paths: {
},
// This section configures the i18n plugin. It is merging the Oracle JET built-in translation
// resources with a custom translation file.
// Any resource file added, must be placed under a directory named "nls". You can use
// a path mapping or you can define a path that is relative to the location
// of this main.js file.
config: {
ojL10n: {
merge: {
// 'ojtranslations/nls/ojtranslations': 'resources/nls/myTranslations'
}
},
text: {
// Override for the requirejs text plugin XHR call for loading text
// resources on CORS configured servers
// eslint-disable-next-line no-unused-vars
useXhr: function (url, protocol, hostname, port) {
// Override function for determining if XHR should be used.
// content omitted for brevity
// Return true or false. true means "use xhr", false
// means "fetch the .js version of this resource".
return true;
}
}
}
});
}());
/**
* A top-level require call executed by the app.
* Although 'ojcore' and 'knockout' would be loaded in any case (they are specified as dependencies
* by the modules themselves), we are listing them explicitly to get the references to the 'oj' and 'ko'
* objects in the callback.
*
* For a listing of which JET component modules are required for each component, see the specific component
* demo pages in the JET cookbook.
*/
require(['ojs/ojcore', 'knockout', 'jquery', 'ojs/ojknockout', 'ojs/ojbutton', 'ojs/ojtoolbar', 'ojs/ojmenu'],
// add additional JET component modules as needed
// eslint-disable-next-line no-unused-vars
function (oj, ko, $) { // this callback gets executed when all required modules are loaded
// add any startup code that you want here
}
);
You can use RequireJS in a regular app as shown, or you can use RequireJS with
oj-module
element to define view templates and viewModels for page sections
in a single-page app. For example, the Oracle JET Starter Templates use the
oj-module
element with RequireJS to use a different view and viewModel when
the user clicks one of the navigation buttons.
For additional information about the Oracle JET Starter Templates, see About the Starter Templates. For more information about using ojModule
and templates, see Create Single-Page Apps.
Use RequireJS in an Oracle JET App
To use RequireJS in your app, edit the bootstrap file to add the Oracle JET modules you need. You can also add your own modules as needed for your app code.
If needed, install Oracle JET and install RequireJS at http://requirejs.org.
To use RequireJS in an Oracle JET app:
- In the bootstrap file or your app scripts, in the
require()
definition, add additional Oracle JET modules as needed. - Add any scripts that your app uses to the
require()
definition and update thefunction(ko)
definition to include the script. - Add any app startup code to the callback function.
- If your app includes resource bundles, enter the path to the bundle in the
merge
section.
Here's an example of the steps in order.
Your app uses the Oracle JET Common Model integrated with Knockout and includes anoj-dialog
. Add the highlighted modules to your bootstrap file or
app
script.require(['knockout','ojs/ojmodel'
,'ojs/ojknockout-model'
,'ojs/ojdialog'
], function(ko) // obtaining a reference to the oj namespace { } );
Then, to use a script named myapp.js
, add the highlighted code
to your require()
definition.
require(['myapp',
'knockout', 'ojs/ojmodel', 'ojs/ojknockout-model', 'ojs/ojdialog'], function(myapp
, ko) // obtaining a reference to the oj namespace { } );
Next, you have a Knockout binding call for an element named
dialogWrapper
. Add that to the callback
function.
require(['myapp', 'knockout', 'ojs/ojmodel', 'ojs/ojknockout-model', 'ojs/ojdialog'], function(myapp, ko) // obtaining a reference to the oj namespace {ko.applyBindings(new app()/*View Model instance*/,
document.getElementById('dialogWrapper'));
} );
Finally, you have a translations bundle, which you add to the
merge
section.
config: {
ojL10n: {
merge: {
'ojtranslations/nls/ojtranslations': 'resources/nls/myTranslations'
}
}
}
For more information about module loading in Oracle JET apps, see API Reference for Oracle® JavaScript Extension Toolkit (Oracle JET) - JET Module Loading Overview.
Add Third-Party Tools or Libraries to Your Oracle JET App
You can add third-party tools or libraries to your Oracle JET app. The steps to take will vary, depending on the method you used to create your app.
If you used command-line tooling to scaffold your app, you will install the library
and make modifications to appRootDir/src/js/path_mapping.json
. If you created your app using any other
method and are using RequireJS, you will add the library to your app and update the RequireJS
bootstrap file, typically main.js
.
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 toolkit features.
To add a third-party tool or library to your Oracle JET app, do one of the following:
-
If you created your app with command-line tooling, perform the following steps.
-
In your main project directory, enter the following command in a terminal window 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
-
Add the new library to the path mapping configuration file.
-
Open
appRootDir/src/js/path_mapping.json
for editing.A portion of the file is shown below.
{ "baseUrl": "js", "use": "local", "cdns": { "jet": "https://static.oracle.com/cdn/jet/16.0.0/default/js", "css": "https://static.oracle.com/cdn/jet/16.0.0/default/css", "config": "bundles-config.js" }, "3rdparty": "https://static.oracle.com/cdn/jet/16.0.0/3rdparty" }, "libs": { "knockout": { "cdn": "3rdparty", "cwd": "node_modules/knockout/build/output", "debug": { "src": "knockout-latest.debug.js", "path": "libs/knockout/knockout-#{version}.debug.js", "cdnPath": "knockout/knockout-3.x.x" }, "release": { "src": "knockout-latest.js", "path": "libs/knockout/knockout-#{version}.js", "cdnPath": "knockout/knockout-3.x.x" } }, ... contents omitted
-
Copy one of the existing entries in
"libs"
and modify as needed for your library.The sample below shows modifications for
my-library
, a library that contains both minified and debug versions.... "libs": { "my-library": { "cwd": "node_modules/my-library/dist", "debug": { "src": "my-library.debug.js", "path": "libs/my-library/my-library.debug.js" }, "release": { "src": "my-library.js", "path": "libs/my-library/my-library.js" } }, ...
In this example,
cwd
points to the location where npm installed the library,src
points to a path or array of paths containing the files that will be copied during a build, andpath
points to the destination that will contain the built version.Note:
If the existing entry that you copy to modify includes
"cdn": "3rdparty",
remove it from the newly-created entry for your library. This line references the Oracle JET third-party area on the content distribution network managed by Oracle. Your library won't be hosted there and keeping this line will cause a release build to fail at runtime by mapping the path for your library to a non-existent URL.If you use a CDN, add the URL to the CDN in the entry for
cdnPath
.
-
-
-
If you didn’t use the tooling to create your app, perform the following steps to add the tool or library.
-
In the app’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 themy-library
directory and add themy-library.js
file and any needed files to it. Be sure to add the minified version if available. -
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 therequire()
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.x.x', 'jquery': 'libs/jquery/jquery-3.x.x.min', ... contents omitted 'text': 'libs/require/text', 'my-library': 'libs/my-library/my-library }, require(['knockout', 'my-library'], function(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 app's modules, see Use RequireJS for Modular Development.
-
Troubleshoot RequireJS in an Oracle JET App
RequireJS issues are often related to modules used but not defined.
Use the following tips when troubleshooting issues with your Oracle JET app that you suspect may be due to RequireJS:
-
Check the JavaScript console for errors and warnings. If a certain object in the
oj
namespace is undefined, locate the module that contains it based on the information in About Oracle JET Module Organization or the Oracle JET Cookbook and add it to your app. -
If the components you specified using Knockout.js binding are not displayed and you are not seeing any errors or warnings, verify that you have added the
ojs/ojknockout
module to your app.
About JavaScript Partitions and RequireJS in an Oracle JET App
RequireJS supports JavaScript partitions that contain more than one module.
You must name all modules using the RequireJS bundles
option and supply a path mapping with the configuration options.
requirejs.config( { bundles: { 'commonComponents': ['ojL10n', 'ojtranslations/nls/ojtranslations', 'ojs/ojknockout', 'ojs/ojcomponentcore', 'ojs/ojbutton', 'ojs/ojpopup'], 'tabs': ['ojs/ojtabs', 'ojs/ojconveyorbelt'] } } );
In this example, two partition bundles are defined: commonComponents
and tabs
.
RequireJS ships with its own Optimizer tool for creating partitions and minifying JavaScript code. The tool is designed to be used at build time with a complete project that is already configured to use RequireJS. It analyzes all static dependencies and creates partitions out of modules that are always loaded together. The Oracle JET team recommends that you use an optimizer to minimize the number of HTTP requests needed to download the modules.
For additional information about the RequireJS Optimizer tool, see http://requirejs.org/docs/optimization.html.
For additional information about optimizing performance of Oracle JET apps, see Optimize Performance of Oracle JET Apps.