Developing a JavaScript module

Thanks to the Oracle Nashorn Project, now included by default with JDK 8, JavaScript interpretation is possible and more powerful than ever in plain ol' Java. Toast utilizes Nashorn for configuration files, as well as extending module creation into this script interface. Because of this, Toast gives developers the power to write their modules in pure JavaScript, or a mix of Java and JavaScript.

Getting Started

Getting started with JavaScript modules is pretty simple. First, you have to decide the nature of your module. Is it a single .js file, or multiple? Your file tree for your module should look similar to the following.

toast/script/js/modules
|- YourModule.jsm                   <-- Your module archive. This is made with HotPlate
||- module.json                     <-- This defines your Module name, version and main file
||- {main javascript file}.js       <-- Entry point for your module. Invoked when require('mymodule') is called
||- {all your other resources}      <-- Any other resources or .js files for your module

If you've ever developed a Node.js Module, the JavaScript Toast Module file tree is more or less the same.

Multiple File Projects

Because of file paths in Toast being largely relative based, we include 3 flavors of the require() function.

• require(filename)
• Requires a file from the script/js file directory, or a module by that name
• require_relative(__FILE__, filename)
• Requires a file relative to the folder the __FILE__ is in. This will work across all USB drives, so if USB drive 0 has a file a.js and USB drive 1 has a file b.js, a.js can access b.js.
• require_here(__FILE__, filename)
• Requires a file relative to the folder the __FILE__ is in. This only requires from the current USB drive. If you're developing a module, use require_here so on the odd chance that 2 USB devices contain 2 different module versions, you're loading the correct one.

NOTE: __FILE__ is written literally in code. If you want, you can replace it with your own file object, but in most cases, using __FILE__ is more than sufficient.

Creating your Module

For your convenience, we created the HotPlate CLI to aid in the development and creation of Modules. HotPlate supports both Java and JavaScript modules, and is available on all platforms.

Head to the HotPlate Project and follow the installation instructions. On Linux/Mac (unix), run gem install hotplate. On windows, download the .exe from the releases page and run it.

Running toast init will ask you a few questions (module language, module name and your main file) and create a new, fresh module for you with the module.json and main.js files already setup and good to go.

Preparing your module for distribution is as simple as running toast build in your module directory, which will package it into a .jsm file that can be included in any user's toast/script/js/modules/ directory and automatically loaded.

Excluding Files

If you want to exclude files from your build, you can create an exclude.build file in similar syntax to a .gitignore

(NOTE: The .jsm file is simply a .zip file with a different extension, if you want to package the module yourself. Ensure you have the module.json file included or else your module will be invalidated.)