Diff for "Cytoscape_Plugin_Tutorial"

Cytoscape Plugin Development Tutorial

Cytoscape allows programmers to write plugins that access the core data structures and windows of Cytoscape to do a wide variety of operations. This tutorial explains how to write a plugin and how to get Cytoscape to load and use your plugin.

It is assumed that the reader is familiar with the basics of the Java programming language and has some kind of programming environment available. See the Java Tutorial for an excellent introduction and handy reference guide for Java. You will also want to check out the Cytoscape core API documentation.

Each plugin tutorial includes the Java source code and a jar file containing the compiled classes. To run Cytoscape via Java WebStart with all of these plugins automatically loaded, click here: WEB START. To create your own webstart please read through this tutorial first [“Cytoscape via Java Web Start"].

Plugin_license_policy

The CytoscapePlugin class

The CytoscapePlugin class is very simple. It defines a default constructor A static method also exists that is used by Cytoscape to load plugins. Since the constructor takes no arguments, it is not necessary to explicitly call a parent constructor from your plugin's constructor. The only requirement is that your plugin must have a default (no arguments) constructor, as Cytoscape will call this constructor to instantiate your plugin.

Java only allows a class to inherit from one parent. Since every plugin must extend CytoscapePlugin, this seems to be a severe limitation. The way around this is to define your Cytoscape plugin class as a simple wrapper around your real code. For example:

   1 public class PluginWrapper extends CytoscapePlugin {
   2 
   3     public PluginWrapper() {
   4         RealPlugin plugin = new RealPlugin();
   5     }
   6 
   7 }
   8 

This scheme can also be used to link to more complicated services, like a web server, or to connect to code written in other languages via the JNI mechanism (see the JNI section of the Java tutorial).

Cytoscape Plugin Management

Starting in Cytoscape version 2.5 plugin management has been added to allow users to search for, download, install, update and delete plugins from within Cytoscape. In order for plugins to be integrated into this management scheme a properties file called "plugin.props" must be added to the plugin jar file in the same path location as your class that extends CytoscapePlugin (ie. If your plugin is in the following package 'my.package.MyPlugin' your plugin.props file must be in the jar file under 'my/package'). The following information is in the plugin.props file (this can be copy/pasted into your own plugin.props file and changed appropriately):

#plugin.props

# This props file should be filled out and included in the plugin jar file.  This props file will be used
# to put information into the Plugin Manager about the plugin

# -- The following properties are REQUIRED -- #

# The plugin name that will be displayed to users, white space within name is not allowed
pluginName=MyPlugin

# Description used to give users information about the plugin such as what it does.
# Html tags are encouraged for formatting purposes.
pluginDescription=Information about the plugin that will be displayed to users.<br>Please use html tags for all formatting and do not add newlines.<p>

# Plugin version number, this must be two numbers separated by a decimlal.  Ex. 0.2, 14.03
pluginVersion=1.0

# Compatible Cytoscape version. If there are more than one version, seperate by ",".
cytoscapeVersion=2.5

# Category, use one of the categories listed on the http://chianti.ucsd.edu/cyto_web/plugins/
pluginCategory=Network generation

# -- The following properties are OPTIONAL -- #

# URL to a website that gives more information about your plugin, Ex. http://my-lab-site.org
projectURL=http://my-lab-site.org/myCytoscapePlugin

# List of authors.  Note each author and institution pair are separated by a : (colon)
# each additional author institution pair must be separated from other pairs bye a ; (semicolon)
pluginAuthorsInstitutions=Sarah and Victor:ISB;Mike, Kei and Peng:UCSD

# Date this plugin/plugin version was released
releaseDate=May 1, 2008

# If this plugin is never meant to be downloaded except as part of a plugin (not common) add this property.  Default is "no"
themeOnly=no

Versioning Your Plugin

The Plugin Manager expects your plugin version to be two numbers separated by a decimal (ex. 1.5 or 4.30). Please note that when comparing for newer versions 1.10 is a newer version than 1.1 or 1.9. Any version that does not match this scheme will cause the manager to error and ignore that plugin.

Creating the Jar File

Plugin jar file should not have white space in the name. Cytoscape encourages all plugins to add an attribute to the jar manifest file called “Cytoscape-Plugin” to make loading the plugin faster and easier. This attribute is required in order for automatic installation to work. If you are using an ant build file to create your plugin jar file, add the manfiest tag to your jar step with the attribute name “Cytoscape-Plugin” and the value set to the full class name of the file which extends CytoscapePlugin. Example:

<target name="jar" description="Create MyPlugin jar file" depends="compile">
    <copy file="${basedir}/plugin.props" todir="{$classes.dir}/my/package" />
    <jar destfile="${build.dir}/MyPlugin.jar">
         <manifest>
         <attribute name="Cytoscape-Plugin"
                    value="my.package.MyPlugin" />
         </manifest>

         <fileset dir="${classes.dir}" />
    </jar>
</target>

If you are creating your jar file via the command line, first create a text file with the Cytoscape-Plugin attribute:

myManifest.txt

Cytoscape-Plugin: my.package.MyPlugin

Then run the jar command with the ‘m’ flag and the manifest file name to add the attributes to the manifest file (it is important that the ‘f’ flag is before the ‘m’ flag).

jar -cfm MyPlugin.jar myManifest.txt <input files>

If you are working with Maven, you will need to reference the maven-jar-plugin within the build/plugins section of your pom.xml and enter the manifest details there, like so:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
                <archive>
                        <manifestEntries>
                                <Cytoscape-Plugin>my.package.MyPlugin</Cytoscape-Plugin>
                        </manifestEntries>
                </archive>
                </configuration>
    </plugin>

Sharing Your Plugin

There are two ways to share your plugin with the Cytoscape community. First is to submit your plugin(s) to http://cytoscape.org The other is to set up your own site to offer your plugin(s) from. Please read the Plugin_Download_Site_Tutorial to learn how to set up your own site.

Example Plugins (these do not yet include the plugin.props file)

Hello_World_Plugin

Neighbor_Node_Selection_Cytoscape_Plugin

Multi-Network_Node_Selection_Cytoscape_Plugin

Important Plugin Design Note

Cytoscape is designed to allow plugins to communicate with each other only through Cytoscape core data structures. It is recommended (but not required) that all plugins be independent of each other except for data sharing through the Cytoscape API. One reason for this is that it is impossible to guarantee that any specific plugin will be loaded, so dependencies among plugins should not exist.

Plugin Themes

A theme is a set of plugins that should be installed together, such as a set of plugins that depend on each other. Please note that at this time is is not possible to create a them that is dependent on any plugins but your own. That functionality is currently reserved for the core developer's group. Any plugin can be part of a theme and/or installed by itself. All plugins still require the plugin.props file as outlined above with one special rule. If the plugin is never supposed to be downloaded singly the property "themeOnly=yes" must be set. This means your plugin will not be listed separately within the Plugin Manager. The following steps will create a theme:

1. Package each of your plugins with the required files (see above).
2. Submit the plugins to the Cytoscape site.
3. Create the following theme definition file (saved as a .txt file)
4. Contact a core developer to assist in submitting your theme.

Theme Definition File:

Cytoscape theme definition
themeName=ThemeNameNoWhitespace
# Must be two digits separated by a decimal
themeVersion=0.2 
themeDescription=A description, can include html tags.  Do NOT add carriage returns.
# Compatible version, note that all the included plugins must also be compatible with these versions
cytoscapeVersion=2.6,2.7
releaseDate=2008-01-11
# Each plugin in the theme needs a line the format is:
# plugin=Category:Name:Version #
plugin=Analysis:MCODE:1.2
plugin=Other:GroupTool:1.0
themeAuthor=Name, Institution
contactEmail=your email