Module development "hands-on"

This section describes the full process of writing and deploying extension modules. We will compose a simple module and show how to make Together recognize it.

1. Objectives.

Let us say we want to develop a simple module which can be used as a startup and as regular module. This time we are not very interested in the module's functionality, so it must display just a short message, for the sake of simplicity.

2. Source code for the module.

Since we want to be able to run the module as a startup and as a regular Together module, we must implement both com.togethersoft.openapi.ide.IdeScript and com.togethersoft.openapi.ide.IdeStartup interfaces.

To output messages to the Together Message pane, we must use the com.togethersoft.openapi.ide.message.IdeMessageManagerAccess and com.togethersoft.openapi.ide.message.IdeMessageType interfaces (see the API documentation in $TOGETHER_HOME$/doc/api).

Important: Each new module must define its own package in the com.togethersoft.modules package.

The only thing left is the name of the module. Let's name it MyFirstModule. Below is the source code listing. If you want to try this out, create a directory %TOGETHER_HOME%\modules\com\togethersoft\modules\myFirstModule and save this code as MyFirstModule.java.

MyFirstModule.java source listing

//the MyFirstModule.java file
package com.togethersoft.modules.myFirstModule;

import com.togethersoft.openapi.ide.IdeContext;
import com.togethersoft.openapi.ide.IdeScript;
import com.togethersoft.openapi.ide.IdeStartup;
import com.togethersoft.openapi.ide.message.IdeMessageManagerAccess;
import com.togethersoft.openapi.ide.message.IdeMessageType;
public class MyFirstModule implements IdeScript, IdeStartup{
 public void run(IdeContext context){ //regular modules perform this method
   IdeMessageManagerAccess.printMessage(IdeMessageType.INFORMATION,"This is my first module. It was called as a regular Together module.");
 }
 public void autorun(){ //startup modules perform this method
   IdeMessageManagerAccess.printMessage(IdeMessageType.INFORMATION,"This is my first module. It was called as a startup module."); //this will appear in the Message pane when Together is loaded
   System.out.println("This is my first module. It was called as a startup module."); //this will appear in the console window at the startup
 }
}

3. The manifest file

If you run Together now and open Modules tab of the Explorer, you'll discover that MyFirstModule isn't shown. This is because we haven't informed Together about what we were going to do with the module.

We do this through a manifest file. A manifest file is a simple text file with the .def extension. It contains some information about the usage of a module.

Specifying if a module is a startup module

Startup modules are modules that load when Together starts. If your module is to be a startup module, the manifest must contain the line:
Startup = true

For regular (i.e. non-startup) modules the line Script = true.

This should be the first line of the manifest file. Each manifest file must have a minimum of one line... either Startup = true or Script = true . You can put both lines if you want the module to run automatically on startup and you want to be able to run it during the Together session.

The manifest file can contain some other lines that provide additional information to Together so that the module appears in, and is accessible from the Together UI.

Defining a visible name for the module

You can specify a visible name for the module by adding this line to the manifest file:
Name = Visible Name

The string after the equality sign will be displayed as the name of the module in the Modules tab of the Explorer. In this example exercise, we'll specify a "Visible Name".

Specifying the Modules tab location

You can specify where your module should appear in the Explorer's Modules tab. For example, you can display it in the existing Sample folder, or you can cause a new folder to appear. To specify the Modules tab location, add this line to the manifest file:
Folder = "<Folder name>"

<Folder name>" can be anything you want. Examples:

Adding the module name to menus for classes, interfaces, and members

You can cause the module to be displayed in the Modules submenu of the speedmenu for classes, interfaces, attributes and operations. Add this line:
PopupMenuItem = true

Adding the module name to menus of elements with specific shapetype

You can cause the module to show up in the Modules submenu of the speedmenus of elements having a specific shapetype (see the explanation of this term in the documentation for the property RwiProperty.SHAPE_TYPE in the API documentation).

Briefly, by optional addition of a constraint using the shapetype parameter, you can make the module appear in the the "Modules" submenu only for operations, or only for attributes, or only for classes and interfaces. Two lines are required to accomplish this: the line specified in the previous section, and an addition line as shown below:
PopupMenuItem = true
PopupConstraints = "shapeType=<shapetype identifier>"

EXAMPLES

Only for operations:

PopupMenuItem = true
PopupConstraints = "shapeType=Operation"

Only for attributes:

PopupMenuItem = true
PopupConstraints = "shapeType=Attributes"

Only for lasses and interfaces:

PopupMenuItem = true
PopupConstraints = "shapeType=Class"

Note that since classes and interfaces have the same shapetype (i.e. "Class"), you can't selectively limit the appearance of a module to just interfaces via the manifest file. Do not worry, this can be done, but you will have to do a little more work in the module. There is a module in the %TOGETHER_HOME%\modules\com\togethersoft\modules\tutorial which shows how to do it.

Only for actors:

PopupMenuItem = true
PopupConstraints = "shapeType=Actor"

Rules for the manifest file

The manifest file must satisfy these conditions:

Since MyFirstModule can be used as both kinds of modules (startup and runnable during session), we will use both of the module declaration lines (Script = true, Startup = true). Invoke your text editor and create the manifest file now. Add the following lines:

Script = true
Startup = true
Name = My First Module
Folder = "MyFirstModuleFolder"

Save the file as: %TOGETHER_HOME%\modules\com\togethersoft\modules\myFirstModule\MyFirstModule.def

4. Compiling a module

Now you have to compile the module's source code. You can do so using Together, or your favorite Java compiler. Remember to include the %TOGETHER_HOME%\lib\openapi.jar file containing API classes in your compiler's classpath.

Where to store the compiled class

Keep module's .class file(s) in the same directory where the manifest file and sources reside. If you keep .class files somewhere else, make sure that their relative path matches the path of the manifest file counting from %TOGETHER_HOME%\modules\com\togethersoft\modules or %TOGETHER_HOME%\classes\com\togethersoft\modules .

For example, if your manifest file is modules\com\togethersoft\modules\coolModule\CoolModule.def, then your .class files must be somewhere in the classpath under the directory com\togethersoft\modules\coolModule\.

Once again, especially for your first modules, it's recommended to keep the .class files in the same directory as the manifest (.def) file and the sources. The best way is to keep them all together in a separate directory under %TOGETHER_HOME%\modules\com\togethersoft\modules.

5. Evaluation.

Once you have compiled the module, run Together (if you compiled the module using Together, close it and run again. If the console window is on, you should see the module's startup message - that marks when it was called at the startup, and when it performed autorun method. Note, that although autorun method contains two output commands, only one console message appears . When Together is loading, its message pane is not visible, so all the messages written to it at the startup will be displayed only after Together finishes loading.

When Together is loaded, select the Modules tab in the Explorer. Expand the All modules folder. You should see the "MyFirstModuleFolder" node with the "My First Module" files. One file is the module's source, another is the compiled .class file. Select either file, right-click, and choose "Run" (for the source file this command will cause Together to try to compile it, and run then. If you wish to use your home-brewed compilation results, select the .class file) If the message pane is open, you should see a module's message.

Congratulations, you have just deployed your first Together module!

It is highly recommended to sequentially comment out each of the manifest file's line to feel that this makes the module work in only one mode. Try it:

Script = true
;Startup = true
Name = This is my first module.

and

;Script = true
Startup = true
Name = This is my first module.

(You will have to restart Together after each change in the manifest file to see the difference)

Last things

The .def and .java files of the module described in this document are not provided with Together... that's to make you create your own first module :-). Once you create it, deploy it, and run it, you will find it a matter of minutes to create new modules.

After you successfully deploy and run this example (please do it. If you are going to write modules, this will save you a lot of time later), look through the sample modules located in the %TOGETHER_HOME%\modules\com\togethersoft\modules directory. Pay attention to the tutorial folder, containing a set of sample modules demonstrating the usage of Together's open API.

Try to take something from the first "lesson" modules in the tutorial folder, and use it in a new module (or, simply rename a tutorial's lesson to be your second module).

Troubleshooting

If you get some compilation errors, please check that you:

Also, you may face these common problems: