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:

- specify a visible name for the module by placing this line:
  - Name = Visible Name
  The string after the equality sign will be displayed as the name of the module in the "Modules" tab (in this example, "Visible Name" will be displayed)
- specify the location of your module in the "Modules" tab. For example, you can put it into "Sample" folder, or you can create its own folder. To specify the location put this line in the manifest file:
  - Folder = "<Folder name>"
  - "<Folder name>" can be "Sample/Tutorial", "Sample", "MyNewFolder" etc
- enable the appearence of the module in the "Modules" submenu in the popup menu for classes, interfaces, attributes and operations. This can be done by this string:
  - PopupMenuItem = true
  See an example of such module in the %TOGETHER_HOME%\modules\com\togethersoft\modules\tutorial folder.
- enable the appearence of the module in the "Modules" submenu in the popup menu for elemenets with the specified shapetype (see the explanation of this term in the documentation of `RwiProperty.SHAPE_TYPE` property in the main API docs). Briefly, using this 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 (an example of such module is in the %TOGETHER_HOME%\modules\com\togethersoft\modules\tutorial folder). This can be done by these lines (line "PopupMenuItem = true" is required to use this feature):
  - PopupMenuItem = true
    PopupConstraints = "shapeType=<place the shapetype here>"

    Examples:

    1. PopupMenuItem = true
       PopupConstraints = "shapeType=Operation" - only for operations
    2. PopupMenuItem = true
       PopupConstraints = "shapeType=Attributes" - only for attributes
    3. PopupMenuItem = true
       PopupConstraints = "shapeType=Class" - only for lasses and interfaces
       Please note that since classes and interfaces have the same shapetype ("Class"), you can't selectively control the appearance of a module, for example, only for interfaces using the manifest files. 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.
    4. PopupMenuItem = true
       PopupConstraints = "shapeType=Actor" - only for actors
  Possible shapetypes are defined in the `RwiShapeType` interface (see API docs).

The manifest file must satisfy these conditions:

- Its name must be exactly the name of the module's main class (the class implementing IdeStartup or IdeScript interfaces).
- Its location must be somewhere under the directories specified in the scriptloader.config file. This file defines two possible root directories for manifests files:
  1. %TOGETHER_HOME%\modules\com\togethersoft\modules
  2. %TOGETHER_HOME%\classes\com\togethersoft\modules

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:

- import all the required API interfaces/classes
- added all the required libraries to the compiler's classpath
- use API methods properly. See API documentation in the \doc folder under the installation.

Also, you may face these common problems:

- Everything compiles without errors, but you can't find your module in Together's "Modules" tab.

  Almost certainly, you didn't compose a .def file at all, or placed it not under the directories specified by the scriptloader.config file (by default, these are %TOGETHER_HOME%\modules\com\togethersoft\modules and %TOGETHER_HOME%\classes\com\togethersoft\modules)

- Everything compiles without errors, and .def file is located okey, but you still can't find your module in Together's "Modules" tab.

  Most likely, you made a spelling error in the lines "Startup = true" or "Script = true" in the .def file.

  Or, the name of the manifest file in not the name of the module. In this case Together will write something like "The manifest file c:\together3\modules\com\togethersoft\modules\coolModule\CoolSript.def exists but Together either cannot find or cannot read its associated module files." in the message page.

- Everything compiles without errors, you see your module's folder in the "Modules" tab, but there are only java sources (assuming you want to see and run the compiled module)

  Make sure module's .class files located in the right place so that Together can find them. It was discussed in this document earlier (if you keep .class files where the .def file is, you won't encounter such a problem).

- Everything compiles without errors, you see the module's compiled class in the "Modules" tab, but your module doesn't seem to work.

  We highly recommend to mark the start and finish of each of your modules (regular and startup) with appropriate messages in the Message pane. This instantly clarifies whether your module was actually run or not. For example: ``

        IdeMessageManagerAccess.printMessage(IdeMessageType.INFORMATION,"MyCoolModule : started"); //start
        IdeMessageManagerAccess.printMessage(IdeMessageType.INFORMATION,"MyCoolModule : finished"); //finish

Good luck!