The purpose of this document.

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

Step one: 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.

Step two: the source code of 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's message pane, we must use the com.togethersoft.openapi.ide.message.IdeMessageManagerAccess and com.togethersoft.openapi.ide.message.IdeMessageType interfaces (see API documentation).

The only thing left is the name of the module. Let's name it MyFirstModule. As all modules, this module must define its own package in the com.togethersoft.modules package: 

//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
 }
}
Create a directory %TOGETHER_HOME%\modules\com\togethersoft\modules\myFirstModule (it will be the module's directory), and save this code as the MyFirstModule.java file into that directory.

Step three: manifest file.

If you now run Together and open "Modules" tab, you will notice that your MyFirstModule module is absent. This is because we haven't informed Together of what we were going to do with the module.

This can be done through a manifest file. A manifest file is a simple text file with the .def extension, containing some information about the usage of a module. For startup modules it must contain the line "Startup = true", for regular modules the line "Script = true".

Each manifest file must have at least one line: either "Startup = true" or "Script = true"

Additionally, you can:

The manifest file must satisfy these conditions:

Since MyFirstModule can be used as both kinds of modules, we can use either of the module declaration lines ("Script = true", "Startup = true"), depending on how we are going to run the module, or both - if we want the module to run automatically _and_ we wish to be able to run it during the session.

Let us choose the latter case. So far, compose the %TOGETHER_HOME%\modules\com\togethersoft\modules\myFirstModule\MyFirstModule.def file with the following contents: 

Script = true
Startup = true
Name = This is my first module.
Folder = "MyNewModuleFolder"

Step four: compilation.

Now you have to compile the module. You can do it using Together, or your favourite java compiler (do not forget to include the %TOGETHER_HOME%\lib\openapi.jar file containing API classes in your compiler's classpath)

We recommend to keep module's .class files 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 the %TOGETHER_HOME%\modules\com\togethersoft\modules or %TOGETHER_HOME%\classes\com\togethersoft\modules directory. 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 directory com\togethersoft\modules\coolModule\.

Once again, for your first modules we recommend you keep the .class files in the same directory where .def file and sources are (the best way is to keep them all in a module's separate directory under the %TOGETHER_HOME%\modules\com\togethersoft\modules).

Step five: evaluation.

Once you have compiled the module, run Together (if you compiled the module using Together, please 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 performed autorun method. Note, that although autorun method contains two output commands, only one message appeared (console message). 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 the loading.

When Together is loaded, open the "All modules" folder. You should see the "MyFirstModuleFolder" folder with the "This is 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)

Conclusion.

We do not provide the the .def and .java files of the module described in this document, to make you create your first module. Once you create it, deploy it, and run it, you will find it a matter of minutes creating new modules.

After you succefully deploy and run this example (Please do it. If you are going to write modules, this will save you a _lot_ of time later ), we recommend you 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 demonstating the usage of Together's open API.

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

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

Also, you may face these common problems:

Good luck!