...

The image below shows an example of the IGB Tools Menu with the addition of a Hello World App item in the menu. The tutorial on this page will walk you through the steps required to add a menu item to one of the IGB menus, as seen in the image below. While this may seem trivial, it is not, because by adding a menu item to an IGB menu a developer can create an entry point that their IGB App can hook into.

Get the IGB code base - clone the IGB repository from Bitbucket

Go the IGB source code repository, hosted on Bitbucket. Copy the repository address and clone it onto your computer.

Also, see Developing IGB for instructions.

Checkout an IGB branch (optional)

If you are planning to share your plug-in with current IGB users, you should check out code corresponding to the current or upcoming release. If you want to develop for an upcoming release of IGB, use the master branch.

The master branch is checked out by default when you clone the repository. To check out a different branch or release tag:

• Change into your cloned IGB project directory
• Use git to check out the the branch or tag you want to use
• Run git clean to remove untracked files after checking out the new branch

For example:

git checkout master # check out current or upcoming minor release of IGB

Note that when you switch branches, files present in the first branch that are not present in newly checked-out branch with remain - git won't delete them. Running the "git clean" command will remove them.

Note also that the version of the IGB code base you use for developing a new IGB App will depend on when you plan to share your App with users. The IGB team recommends you develop your App using the master branch so that you will can take advantage of the latest, most powerful API features, but if you want to release your App right away, then you should use whichever version of IGB your target audience is using - typically whatever release is available on the BioViz.org Web site. To decide which version makes the most senses for you, you'll need to understand how branches and tags in the IGB git repository correspond to versions of IGB downloaded by users. See About the code base.

Build the App

To build your App, select Run > Build in NetBeans.

Alternatively, you can build it from the command line by entering:

mvn clean install

Install the App in IGB

Start IGB and add your target directory as a new plugin repository (local App store)

1. Re-open IGB project (double-click it in the Projects tab or use File > Open Project)
2. Open the IGB "main" sub-project; select IGB Project > Modules > main
3. Select Run to run IGB
4. Within IGB, select the Plug-Ins Tab
5. Select Launch App Manager to open the App Manager window
6. Within the App manager, select Manage Repositories... (top right corner). This opens the App Repositories tab in the IGB Preferences window
   1. Image Removed
7. Within the App Repositories tab in the Preferences window, select Add 
8. Enter a name for your repository, and then select the Choose local folder button
   1. Image Removed
9. Select the target directory of your maven project and click submit. The target directory is the actual target directory created by maven when you built your App.
   1. Image Removed
10. Close the Preferences window and return to the IGB App Manager
11. Note that your App should now appear in the left pane of the IGB App Manager. Select it and click the Install button. This will cause the OSGi run-time to instantiate your new menu item and add it to IGB.
    
    1. Image Removed

Run your new App

To run your app:

• Open the Tools menu in IGB. Observe your Hello World App menu item is an option.

Image Removed

• Select Tools > Hello World App to run your App; observe the message that appears:

Image Removed

Next step: Make README.md for your App (optional)

Dissecting the Hello World IGB App

The rest of the information found on this page aims to give the developer a deeper understanding of the different pieces that allow the Hello World IGB App to hook into IGB.

Directory Structure

The Maven build system assumes that every Java project conforms to an expected directory structure. Here, the maven project includes

• pom.xml - located at the top level of the project. In IGB, an App's pom.xml file specifies which services the App needs to import from the IGB code base as well as any 3rd party libraries used by your App.
• src - contains source code, organized as shown. Every maven project contains src/main/java, which contains java packages organized as directories in the usual way. The example shows a single Java source code file/

To see the directory structure for your project in NetBeans, select the Files tab (next to the Projects tab).

Image Removed

HelloWorld pom.xml

***Need explanation of what the app's pom.xml file is for***

...

Build the App

To build your App, open the igb-app-hello-world project into Netbeans, select your project in the Projects tab, and then select Run > Build.

Alternatively, you can build it from the command line by entering:

mvn clean install

...

Install the App in IGB

Start IGB and add your target directory as a new plugin repository (local App store)

1. Re-open IGB project (double-click it in the Projects tab or use File > Open Project)
2. Open the IGB "main" sub-project; select IGB Project > Modules > main
3. Select Run to run IGB
4. Within IGB, select the Plug-Ins Tab
5. Select Launch App Manager to open the App Manager window
6. Within the App manager, select Manage Repositories... (top right corner). This opens the App Repositories tab in the IGB Preferences window
   1. Image Added
7. Within the App Repositories tab in the Preferences window, select Add 
8. Enter a name for your repository, and then select the Choose local folder button
   1. Image Added
9. Select the target directory of your maven project and click submit. The target directory is the actual target directory created by maven when you built your App.
   1. Image Added
10. Close the Preferences window and return to the IGB App Manager
11. Note that your App should now appear in the left pane of the IGB App Manager. Select it and click the Install button. This will cause the OSGi run-time to instantiate your new menu item and add it to IGB.
    
    1. Image Added

...

Run your new App

To run your app:

• Open the Tools menu in IGB. Observe your Hello World App menu item is an option.

Image Added

• Select Tools > Hello World App to run your App; observe the message that appears:

Image Added

Next step: Make README.md for your App (optional)

...

Dissecting the Hello World IGB App

The rest of the information found on this page aims to give the developer a deeper understanding of the different pieces that allow the Hello World IGB App to hook into IGB.

Directory Structure

The Maven build system assumes that every Java project conforms to an expected directory structure. Here, the maven project includes

• pom.xml - located at the top level of the project. In IGB, an App's pom.xml file specifies which services the App needs to import from the IGB code base as well as any 3rd party libraries used by your App.
• src - contains source code, organized as shown. Every maven project contains src/main/java, which contains java packages organized as directories in the usual way. The example shows a single Java source code file/

To see the directory structure for your project in NetBeans, select the Files tab (next to the Projects tab).

Image Added

HelloWorld pom.xml

***Need explanation of what the app's pom.xml file is for***

...

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.affymetrix</groupId>
        <artifactId>igb-project</artifactId>
        <version>9.0.0</version>
    </parent>
    <groupId>org.lorainelab.igb</groupId>
    <artifactId>org.lorainelab.igb.menu.api.example</artifactId>
    <version>1.0.0</version>
    <packaging>bundle</packaging>

    <name>IGB Menubar Extension</name>
    
    <dependencies>
        <dependency>
            <groupId>biz.aQute.bnd</groupId>
            <artifactId>bndlib</artifactId>
            <scope>provided</scope>
        </dependency>
          <dependency>
            <groupId>org.lorainelab.igb</groupId>
            <artifactId>org.lorainelab.igb.menu.api</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
        <artifactId>igb-project</artifactId>
        <version>9.0.0</version><artifactId>maven-bundle-plugin</artifactId>
    </parent>
    <groupId>org.lorainelab.igb</groupId>
    <artifactId>org.lorainelab.igb.menu.api.example</artifactId>
    <version>1.0.0</version><extensions>true</extensions>
    <packaging>bundle</packaging>

    <name>IGB Menubar Extension</name>
    
    <dependencies><executions>
        <dependency>
            <groupId>biz.aQute.bnd</groupId><execution>
            <artifactId>bndlib</artifactId>
            <id>build plugin <scope>provided<repository</scope>id>
        </dependency>
                <dependency><goals>
            <groupId>org.lorainelab.igb</groupId>
            <artifactId>org.lorainelab.igb.menu.api</artifactId>
    <goal>
        <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>index
            <plugin>
                <groupId>org.apache.felix</groupId>
</goal>                <artifactId>maven-bundle-plugin</artifactId>
       
         <extensions>true</extensions>
                <executions></goals>
                    <execution>
    <phase>package</phase>
                    <id>build plugin repository</id>
  <configuration>
                      <goals>
      <obrRepository>${project.build.directory}</obrRepository>    
                  <goal>
          <mavenRepository>${project.build.directory}</mavenRepository>                      index
                            </goal>configuration>
                       </execution>
                </executions>
        </goals>
        <configuration>
                <phase>package</phase>
    <instructions>
                    <configuration>
   <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                         <obrRepository>${project.build.directory}</obrRepository>    <Import-Package>*</Import-Package>
                            <mavenRepository>${project.build.directory}</mavenRepository><Export-Package/>
                      
  <Service-Component>*</Service-Component>
                      </configuration>instructions>
                    </execution>configuration>
                </executions>
plugin>     
           <configuration></plugins>
                    <instructions>
                       <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                        <Import-Package>*</Import-Package>
                        <Export-Package/>
                        <Service-Component>*</Service-Component>
                    </instructions>
                </configuration>
            </plugin>     
        </plugins>
    </build>
</project>

parent tag

<parent>
    <groupId>com.affymetrix</groupId>
    <artifactId>igb-project</artifactId>
    <version>9.0.0</version>
</parent>

...

Image Removed

packaging tag

This tag specifies packaging type - e.g., war or jar. In IGB, we use an OSGi-specific packaging structure called a "bundle," which is a jar file with additional metadata. This additional metadata transforms an ordinary jar file into a plug-able module in the OSGi runtime. The IGB project uses the Apache Felix Maven Bundle plugin (BND) to generate this metadata. The BND bundle defines the packaging type "bundle."

<packaging>bundle</packaging>

name tag

This should be a user-friendly name for your App suitable for display in the IGB App Manager list of available Apps. This tag is optional; if you don't include it, then the App Manager will list your App's artifactId.

<name>IGB Menubar Extension</name>

dependency tags (parent tag "dependencies")

The term "dependency" just means: third-party resources your project requires to compile and run, such as library files.

Your pom.xml file should contain a single "dependencies" tag with several "dependency" child tags:

<dependencies>
	<dependency>...</dependency>
	<dependency>...</dependency>
</dependencies>

biz.aQute.bnd:bndlib

This dependency enables the Declarative Services annotations used within the IGB code base that allow easy service consumption and registration with the IGB OSGi component runtime.

Note how that scope tag is "provided" - this is because the parent pom.xml file defines this dependency in its dependencyManagement tag. When mvn compiles your App, mvn will retrieve necessary metadata about the dependency, such as its version and other information, from the parent pom. 

<dependency>
   <groupId>biz.aQute.bnd</groupId>
   <artifactId>bndlib</artifactId>
</build>
</project>

parent tag

<parent>
    <groupId>com.affymetrix</groupId>
    <artifactId>igb-project</artifactId>
    <version>9.0.0</version>
</parent>

This tag specifies packaging type - e.g., war or jar. In IGB, we use an OSGi-specific packaging structure called a "bundle," which is a jar file with additional metadata. This additional metadata transforms an ordinary jar file into a plug-able module in the OSGi runtime. The IGB project uses the Apache Felix Maven Bundle plugin (BND) to generate this metadata. The BND bundle defines the packaging type "bundle."

<packaging>bundle</packaging>

name tag

This should be a user-friendly name for your App suitable for display in the IGB App Manager list of available Apps. This tag is optional; if you don't include it, then the App Manager will list your App's artifactId.

<name>IGB Menubar Extension</name>

dependency tags (parent tag "dependencies")

The term "dependency" just means: third-party resources your project requires to compile and run, such as library files.

Your pom.xml file should contain a single "dependencies" tag with several "dependency" child tags:

<dependencies>
	<dependency>...</dependency>
	<dependency>...</dependency>
</dependencies>

biz.aQute.bnd:bndlib

This dependency enables the Declarative Services annotations used within the IGB code base that allow easy service consumption and registration with the IGB OSGi component runtime.

Note how that scope tag is "provided" - this is because the parent pom.xml file defines this dependency in its dependencyManagement tag. When mvn compiles your App, mvn will retrieve necessary metadata about the dependency, such as its version and other information, from the parent pom. 

<dependency>
   <groupId>biz.aQute.bnd</groupId>
   <artifactId>bndlib</artifactId>
   <scope>provided</scope>
</dependency>

org.lorainelab.igb

***Need description here***

<dependency>
    <groupId>org.lorainelab.igb</groupId>
    <artifactId>org.lorainelab.igb.menu.api</artifactId>
    <scope>provided</scope>
</dependency>

com.affymetrix:igb-services

This module is an API module that contains most of the service interfaces which provide access (hooks) to functions in the IGB platform, such as identifying the currently selected feature or tracks.  build, plugins, and plugin tag

maven-bundle-plugin

This is the most important plugin to be aware of as an IGB module developer.  This plugin is known as the "Swiss army knife of OSGi" and is a wrapper around the BND project described in the previous section.

<dependency>	<build>
       <groupId>com.affymetrix</groupId> <plugins>
       <artifactId>igb-services</artifactId>
       <scope>provided</scope>
</dependency> 

com.affymetrix:igbSwingExt

This module contains custom Swing components used in the IGB graphical user interface. In some cases the interfaces contained in the igb-services modules require the use of some of the custom swing components contained in this module.  We do this because we often have the need to add additional functions to basic swing components, such as the concept of "weights" for menu items to ensure that newly added menu options appear in the correct order. 

<dependency>
     <groupId>com.affymetrix</groupId><plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <extensions>true</extensions>
                <executions>
                    <execution>
     <artifactId>igbSwingExt</artifactId>
     <scope>provided</scope>
</dependency> 

build, plugins, and plugin tag

maven-bundle-plugin

This is the most important plugin to be aware of as an IGB module developer.  This plugin is known as the "Swiss army knife of OSGi" and is a wrapper around the BND project described in the previous section.

	<build>
        <plugins>
     <id>build plugin repository</id>
     <plugin>
                <groupId>org.apache.felix</groupId>
   <goals>
             <artifactId>maven-bundle-plugin</artifactId>
                <extensions>true</extensions><goal>
                <executions>
                index
    <execution>
                        <id>build plugin repository</id>
 </goal>                       <goals>
                            <goal></goals>
                                index<phase>package</phase>
                        <configuration>
    </goal>                       
  <obrRepository>${project.build.directory}</obrRepository>    
                   </goals>
         <mavenRepository>${project.build.directory}</mavenRepository>               <phase>package</phase>
       
                 <configuration>
       </configuration>
                     <obrRepository>${project.build.directory}</obrRepository>execution>
    
            </executions>
                <mavenRepository>${project.build.directory}</mavenRepository><configuration>
                      <instructions>
                        <Bundle-SymbolicName>${project.artifactId}</configuration>Bundle-SymbolicName>
                        <Import-Package>*</execution>Import-Package>
                </executions>
        <Export-Package/>
        <configuration>
                <Service-Component>*</Service-Component>
    <instructions>
                </instructions>
       <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
         </configuration>
               <Import-Package>*</Import-Package>
                        <Export-Package/>
                        <Service-Component>*</Service-Component>
                    </instructions>
                </configuration>
            </plugin>     
        </plugins>
    </build>

There are several important things to understand about the above configuration.

...

• The metadata can optionally include service component definition files as described in the OSGi Declarative Services Specification (See http://wiki.osgi.org/wiki/Declarative_Services for more information)
• We use annotations in our java code which are processed at compile time by the felix maven bundle plugin to generate the service component definition files for a bundle.

...

Adding a new item to the IGB Tools menu 

To demonstrate how an IGB plugin could hook into and expand the IGB toolbar, you can write a new class that implements the MenuBarEntryProvider interface.

This interface is designed to allow App developers to add new menu items to the IGB application's top level menus.

IGB (as of this writing) has seven top-level menus, including:

 Image Removed

The MenuBarEntryProvider interface contains the following methods, shown below. To add a new menu item to IGB, you'll create a class that implements this interface. In other words, you'll create a class that provides an IGB menu item to the OSGi run-time, which will add it to IGB as soon as it becomes available.

public interface MenuBarEntryProvider {
    public Optional<List<MenuItem>> getMenuItems();
	public MenuBarParentMenu getMenuExtensionParent();
 }

...

...

</plugin>     
        </plugins>
    </build>

There are several important things to understand about the above configuration.

• This plugin is responsible for generating all of the OSGi metadata required to build your App "artifact" - a jar file with metadata making it into an OSGi module.
  
  • The metadata can optionally include service component definition files as described in the OSGi Declarative Services Specification (See http://wiki.osgi.org/wiki/Declarative_Services for more information)
  • We use annotations in our java code which are processed at compile time by the felix maven bundle plugin to generate the service component definition files for a bundle.
• This plugin is also configured above in the "build plugin repository" execution to generate OBR (Object Bundle Repository) metadata in the build directory (i.e. the target directory) of the project. This directive is useful because it allows you to add your App's target directory as a local App Store (plugin repository) to IGB so that you can run your new App
  
  

...

Adding a new item to the IGB Tools menu 

To demonstrate how an IGB plugin could hook into and expand the IGB toolbar, you can write a new class that implements the MenuBarEntryProvider interface.

This interface is designed to allow App developers to add new menu items to the IGB application's top level menus.

IGB (as of this writing) has seven top-level menus, including:

 Image Added

The MenuBarEntryProvider interface contains the following methods, shown below. To add a new menu item to IGB, you'll create a class that implements this interface. In other words, you'll create a class that provides an IGB menu item to the OSGi run-time, which will add it to IGB as soon as it becomes available.

public interface MenuBarEntryProvider {
    public Optional<List<MenuItem>> getMenuItems();
	public MenuBarParentMenu getMenuExtensionParent();
 }

package org.lorainelab.igb.menu.api.example;
import aQute.bnd.annotation.component.Component;
import java.util.Arrays;
import java.util.List;
import java.util.Optional;
import javax.swing.JOptionPane;
import org.lorainelab.igb.menu.api.MenuBarEntryProvider;
import org.lorainelab.igb.menu.api.model.MenuBarParentMenu;
import org.lorainelab.igb.menu.api.model.MenuItem;
@Component(immediate = true)
public class MenuBarExtensionExample implements MenuBarEntryProvider {

    @Override
    public Optional<List<MenuItem>> getMenuItems() {
        MenuItem menuItem = new MenuItem("Hello World App", (Void t) -> {
        return    MenuBarParentMenu.TOOLS;
    }
}

@Component(name = IgbToolbarExtension.COMPONENT_NAME, immediate = true, provide = IgbMenuItemProvider.class)
public class IgbToolbarExtension implements IgbMenuItemProvider {...}

JOptionPane.showMessageDialog(null, "Hello IGB World!");
            return t;
        });
        menuItem.setWeight(1000000000);
        return Optional.ofNullable(Arrays.asList(menuItem));
    }

    @Override
    public MenuBarParentMenu getMenuExtensionParent() {
        return MenuBarParentMenu.TOOLS;
    }
}