Dojo in XPages – 3: Loading Dojo Modules

In the last post, I showed how to use some string utilities that are automatically loaded and available to any XPage. However, there are more Dojo modules with great functionality that are on the server but not loaded by default so as not to introduce unnecessary overhead when loading your pages. In this post, I’ll show how to load additional modules when you want to use their features so you can easily include any Dojo module that’s already on the server.

In this post I’ll use an example of an array utility called indexOf, which works on arrays like the standard JavaScript indexOf function works on strings. We’ll get to array utilities more in the next post, but we need to first pause to look at how we can load the array module so that we can use it, because it’s not automatically loaded in the XPages context.

Dojo in XPages Series

Dojo in XPages — All Blog Posts

Option 1 – Loading On Demand

You can load a Dojo module on demand and use it within a function as shown below.

require(["dojo/_base/array"], function(array) {
  var myArray = ["car", "train", "boat", "plane", "car", "submarine", "helicopter", "motorcycle"];
  console.log(array.indexOf(myArray, "car"));
});

This loads the array module and makes it available within the function based on the object named array. If you try to reference array outside of the function, it will be out of scope and will raise an error.

Note that this is a newer style of loading modules as of Dojo 1.7, so it will work in Notes 9 (which uses dojo 1.8), but not in Notes 8.x (which uses 1.6 and below). See the first post in the series for more details.

Option 2 – Loading at the Page Level

You can also load a Dojo module at the page level in order to make it available to any component on the page, rather than just within the scope of a single function.

XPages and Custom Controls give you properties to make this easy.

On the Resources subtab of the page properties, click the Add... button and select Dojo Module. Then type in the name of the module that you want to load and click OK.

Dojo_3_LoadDojoModule

This includes an xp:dojoModule tag in the page source.

<xp:this.resources>
  <xp:dojoModule name="dojo._base.array"></xp:dojoModule>
</xp:this.resources>

This makes the module available for use throughout the page, but note that you have to refer to it as dojo._base.array.indexOf(). This is different than with the first option, which assigned a variable to refer to the module within the scope of the function.

Here’s an example of how to use it:

dojo._base.array.indexOf(myArray, "car")

Option 3 – Loading Application-Wide via a Theme

If you’re going to use the function throughout your application, then you can make it available throughout the application by including it in a theme.

<resources>
  <dojoModule name="dojo._base.array"></dojoModule>
</resources>

With this method, you would use it the same way as shown in option 2, because it’s essentially being loaded the same way.

Advertisements

4 responses to “Dojo in XPages – 3: Loading Dojo Modules”

  1. Richard Moy says :

    Brad,

    Have you seen any advantages of either of the three. It seems the first option is more flexible, but does Domino incorporate it into a single load package if you using option 2 or 3.

  2. seanshaggerty says :

    Brad, in Option 1, I do not see Where that dojo require is placed?
    Where would you place that “require” ?; and,

    It seems the AMD post 1.6 style of DOJO is for all dojo functions to be separate from the widget the dojo operates upon. How would you keep the DOJO with the elements/xpage_widget the DOJO code applies to?
    (e.g. switch control with different dojo for each facet key)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: