The Dojo Library in Worklight Studio V6.0
DavidDhuyvetter 10000034CQ Comments (4) Visits (14378)
Worklight Studio V6.0 introduced a new project structure for dojo apps. It
In Worklight Studio V5, the dojo library was a part of a Worklight Project. There was a dojo folder at the top level of the project, and a build file that had to be adjusted manually if you used anything unusual from dojo.
This arrangement had some challenges. The worklight project was very large from the start. This was primarily a chalenge for source control management. Only the parts of dojo specified in build-dojo.xml got bundled into the application, but the project still had all of dojo source in it. This made the initial check in to SCM quite time consuming. You had to be careful to only synchronize sub trees of the project with the repository, because synchronizing the whole project (including the dojo folder) was also very time consuming. The syntax of build-dojo.xml wasn't the easiest thing to understand, and if you did find
In Worklight V6.0, the dojo source code is now in a separate library. This has several advantages. If more than one project is using the same version of dojo, they can share a single library in the workspace. The dojo library should probably be added to SCM, but a single instane of the library in the repository can be shared by any number of projects and applications. Changing the version of dojo for an existing project involves much simpler changes than it did in V5.
Probably most important, Worklight Studio V6.0 gets rid of the need to edit build-dojo.xml. It makes all of dojo available to your application in test, and gives you a tool to determine exactly which parts of dojo need to be added to your project to make it run outside of the test environment.
Creating a dojo App in Worklight Studio V6.0
The process of creating a dojo app in Worklight Studio V6.0 is similar to the process in V5. The difference is that now you need to specify a library project for dojo.
By default, it will use "dojoLib," creating it if it doesn't exist. You can select another dojo library in the workspace or click on "New Dojo Library..." to customize the library that you will use.
I you customize a new library, you can use the version of dojo provided in Worklight Studio (1.9), or you can provide a different version. If you provide your own version of dojo, the Worklight app will be initially generated a bit differently than if you use the version provided in Worklight Studio. With the default dojo library, deviceTheme.js is included in the main HTML file, and dojoInit() is called out of a require in wlCommonInit. If you create a dojo library with your own version of dojo, the associated application won't include deviceTheme.js and dojoInit() won't be called out of wlCommonInit. You will have to at least fix this later problem to end up with a working dojo application.
The radio drop down above the dojo components list gives you the opportunity to specify particular subsets of dojo to include in the Library, but there isn't a strong disadvantage to just including everything. Whether you create a custom Library, create the default Library, or just use a dojo library already in the workspace, the "New Worklight Project" dialog completes as in V5.
The Structure of a dojo Project
The generated Worklight project will have a reference to the dojo library, and it will contain a www folder that has the same contents as the pre-built folder in the dojo library.
The Rich Page Editor, as well as the Palette View, use the dojo library, so they always have access to everything in the library. When you preview your app in the Mobile Browser Simulator, it also has access to everything in the dojo library. But it access files in the dojo library via a Web Server embedded in Worklight Studio. This means that if your application uses something beyond the standard dojo layers, then the application will only work when Worklight Studio is running, and available.
This is unlikely to cause problems for previewing the app as Common Resources, or in the Mobile Browser Simulator. The most common way to use those tools is on the same system where Worklight Studio is running. Since they depend on the Worklight Test Server, you would have to go out of your way to run them without Worklight Studio running. If you try to use the Mobile Browser Simulator from a browser on another box, you might run into trouble if the port used by Worklight Studio to serve dojo files from the library is blocked by a firewall. This port is 64686 on my system. I haven't been able to determine if that is a fixed port, or a random port selected by my install of Worklight Studio. This is separate from the port used by the Worklight Test server (10080).
In the first release of Worklight Studio V6.0, there was a problem where the hostname for the dojo library server was getting set to localhost. This caused apps that needed dojo files from the Library to fail if they that weren't running on the same host as Worklight Studio. (even apps running in emulators on the same host could run into problems) However, the latest build of Worklight Studio now selects an IP address for the dojo library server in much the same way that the IP address for the Worklight server was auto-selected in V5.
You can see how Worklight is connecting your app to the dojo library server by looking at the HTML source for your running app in Chrome. Launch your application from the Worklight Console in Chrome with the Preview as Common Resources link. Use Tools -> View Source to se the HTML source of your app. In the <head> section you will find a script injected by the Worklight build process.
This tells dojo to load the named modules from the Worklight Server HTTP server. In my case, Worklight Studio selected an IP address that is on my LAN, but is not reachable from the public internet. This means (as long as port 64686 is open on my computer's firewall) that dojo classes can be loaded from any system directly connected to the 192.168.1.x LAN. But it will fail to load files from the dojo library if my device is not on the same LAN as the computer running Worklight Studio.
This does not mean that the app will
Building a dojo Application for Distribution
To determine the additional dojo files that your app depends on, you need to run your app in an environment where the app can reach the Worklight Studio HTTP server. This can be the Mobile Browser Simulator, a device emulator running on the same host as Worklight Studio, or an actual device that is connected to the same LAN as the host running Worklight Studio. Before starting the app, go to the Console view in Worklight Studio. In the Upper right, click on the Open Console icon and select the Dojo Library Requests console.
If there are already items in the console, clear it. Now, run the application in the mobile browser simulator, or on an emulator running on the same host as Worklight studio. Be sure to exercise all of the views and capabilities. When the application has been well exercised, go back to the Dojo Library Request console. If there are no entries in the console, then all dojo dependencies in your application can be loaded form the standard layers. There is no need to add additional dojo files to your project. If there are entries in the Dojo Library Requests console, then these are the files from dojoLib that need to be added to the www folder in your project.
Copy the needed files from dojo
To turn off loading from Worklight Studio, go to the Dojo Library Requests console, and click on the white down arrow in the upper right. If Provide Library Resources is checked, uncheck it.
With Provide Library Resources disabled in the Dojo Library Requests console, Build all and Deploy (or more likely, Build for Remote Server, which will also set the Worklight Server address in the generated app to be a public address for the Worklight server) The generated app will now contain the standard dojo layers, all the files that you copied into www, and the main HTML will not have the script that tells it to load dojo dependancies from the Worklight Studio HTTP server. From here you can use the
It is important to be aware that the un-checking of Provide Library Resources resources is not sticky. If you exit and re-start Eclipse, the setting will return to checked. You must verify the setting before building each time you build for distribution.
In the instructions above, the advice was to copy the dojo source files from dojoLib to the www directory in your project. These source files are not optimized or minified. If there are just a few files to add, then just adding the source to your project is probably OK, but if there are a large number of files, then you might want to consider using the dojo Build System to create a optimized, minified layer containing all the required files. If you create your own layer, you should probably put it in the www/layers folder in your project, and load it along with the standard layers in wlCommonInit()
If you want to, you can completely replace the standard layers in the app with a custom layer that you build with exactly the artifacts needed by your application. To determine what parts of the standard layers your application uses, comment out the above line in wlCommonInit() and add a direct call to dojoInit(). This will cause all dojo dependancies to be loaded through the Worklight Server HTTP server. Use the Dojo Resource Loading console to get a list of what your application loads when you run it and build a layer with exactly the files needed by your application. When the layer is complete, add it to www/layers in your project, remove the direct call to dojoInit() from wlCommonInit, and modify the require so that it loads just your layer.
If you've gotten everything right, you should be able to run your application with Dojo Resource Loading enabled, but the Dojo Library Requests console should be empty. All dependancies should be resolved by your custom layer.
The above technique can also be used to debug with dojo source code. Remove the require in wlCommonInit(), and replace it with a direct call to dojoInit(). Copy the non-minified version of dojo.js (and optionally deviceTheme.js) from dojoLib to the www/dojo folder in your project. Now your application will load everything from the Worklight Studio HTTP server and use the non-minified source code for all of dojo. After debugging, be sure to restore the minified dojo.js to www/dojo from the pre-built folder in dojoLib, and restore the loading the layers in wlCommonInit().
The mechanism for loading dojo artifacts at runtime via the Worklight Studio HTTP server only work for items loaded via a call to require(). If you have a direct reference to a file under one of the dojo modules in your HTML file, then you must put this file in your www folder even if you are testing with the Mobile Browser Simulator. For example, if you drag and drop a dojo
Ideally, you should minimize the dojo artifacts loaded directly in the HTML, but it is important to be aware of this behavior.
Finally, if you check dojoLib into a git repository using the Eclipse git tooling, it actually moves the dojoLib project files out of the default location to a subdirectory of the local git repository. This will break Worklight Studio's ability to use it to load artifacts at runtime through its built in HTTP server.
I'm still looking for a good solution to this problem. A suggestion is that after checking in the dojoLib project, the project be deleted from the workspace (but not from the file system) then the project be re-imported as existing project and copied into the workspace. The result would be a copy of the project in the local git repository that is not in the workspace, a copy of the project that is in the workspace that is not associated with git, and the dynamic dojo Library loading should work. The dojo library itself should seldom (if ever) be modified, so having the copy of the project in the workspace disassociated with the git repository shouldn't be a problem. But this solution still seems quite complex, so I'm looking around for a simpler way to deal with it.
EDIT: After further experimentation, it turns out that restarting Eclipse after checking in dojoLib is enough to straighten this out. Evidently Worklight Studio can handle the fact that the dojoLib project isn't in the workspace directory just fine. It is just having the project moved out of the workspace by eGit that confuses it. Restarting Eclipse resolves this. The initial check in of a dojo library should be an infrequent task, so the need to restart Eclipse in this case isn't too bad.