Tutorial: Making A Module

Overview

This lesson teaches you how to create a module in the Partner Workbench. Modules are the fundamental method for extending the Partner Platform, with new code, applications, or mapsets.

This tutorial is part of the Partner Platform: Map Framework.

audience

  • system administrators and IT staff
  • power users
  • developers

objectives

  • learn about modules
  • view the currently installed modules
  • create a new module named “Tutorial”
  • create and run an action in the module

prerequisites

You need a working Partner installation and basic familiarity with the Workbench. Partner Platform: Fundamentals covers these nicely.

Modules

Explained

Modules are a very important concept in Partner version 4.4 and above. They allow Partner, customers, and third-party software developers to extend the Partner Platform with custom tools and configuration.

Modules can contain any or all of the following:

  • app scripts
  • OS-specific software and libraries
  • splash screens
  • scripts and script libraries
  • standardized mapsets
  • text templates
  • arbitrary data, image files, or other resources

Viewing Installed Modules

Modules are stored in the modules/ directory. In the Workbench filesystem tree, select this directory and see the listing of available modules and their versions in the Modules tab.

Modules are divided by config level - you will see at least modules/customer/, but you may see any or all of the following:

  • modules/provider/
  • modules/hub/
  • modules/customer/
  • modules/site/
  • modules/seat/

Generally when you are developing you want to work in the modules/seat/ directory, since these files will not be overwritten by updates (losing your work!).

Each of these subdirectories has a similar “Modules” tab to view the installed modules in that directory alone.

Select modules/customer/GPS/. This is the GPS module and modular mapset. Notice the link at the top of the “Module” tab (download and install development release.) - it will automatically download and install the latest version just by clicking that. Powerful! Dangerous!

Required Files

In order for modules to be identified as such by the platform, they must have two files in their “info” subdirectory:

  • info/version.txt
  • info/depends.txt

The first is the version of the module, the second is any other modules (optionally with versions) this module depends on. The depends.txt file must be present but can be blank. The version.txt file must have a version like 1.0.0 in it.

These files are automatically created by the “Make Module” link in the Modules tab when you have a subdirectory of modules/ selected, and there are links to create them in the Module tab for a given module’s directory if they are missing.

Make Your Own

Let’s create our own module. First, make sure you have a modules/seat/ directory. If not select modules/, and either use the quick link in the Modules tab or use the generic “New Directory” tool in the Directory editor.

Now select modules/seat/, click the Modules tab, click the “new module” link, and type in the name Tutorial. It should automatically create and select it.

TODO: screenshot

Module Actions

Explained

Modules can extend the interface for the Workbench in a number of ways; one of the simplest of these is by adding items to the Actions menu. By default, any script placed inside a module under the directory workbench/actions/ will show up as a menu item of the same name in the Workbench’s Actions menu.

Make Your Own

Select your module if it’s not already selected - modules/seat/Tutorial/ if you followed the instructions above.

Create a directory workbench/actions, and select it. The full path is modules/seat/Tutorial/workbench/actions/.

Now select your new directory. Go to the Directory editor and click “New File”. Type in Logging Demo.groovy and click OK. Your new file should appear and be selected.

Type or paste the following into your new file, in the Script editor:

log.info("Gee, this is hard.");
log.warn("Uh oh, spaghetti-o");
log.error("Danger, Will Robinson!");
log.fatal("Et tu, Brute");

Click the Run button at the top and watch the log to see your clever messages. Note the different color codings for the different severity levels of log message.

TODO: screenshot

Run It From The Menu

Restart the Workbench (menu Workbench/Restart Workbench). Your script should now appear as an item in the menu Actions/Tutorial/.

Break It

Mess up your script. You may have already done that. For example, change “log” to “lorg” or some such. When you run it, you’ll see an error with the line on it and a link. Clicking the link takes you to the line the error happened on.

Make It Do Something “Useful”

Obviously most apps should do more than blart something to the log (though, if you look at the logs, you might wonder...).

Try something like this. Play with it, hitting Run whenever you want to see the result. You’ll get an error if you mess up of course; just fix it and move on.

// pythagorean theorem
sideA = 5;
sideB = 10;
hypotenuse = Math.sqrt(sideA * sideA + sideB * sideB);
log.info("Triangle sides are " + sideA + ", " + sideB + ", " + hypotenuse);

Moving On

Now that you’ve mastered basic modules, proceed to Tutorial: Scripted Data Input.