Size: 7293
Comment:
|
Size: 8877
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 4: | Line 4: |
Line 9: | Line 8: |
Each plugin tutorial includes the Java source code and a jar file containing the compiled classes. To run Cytoscape via Java Web``Start with all of these plugins automatically loaded, click here: [http://cytoscape.org/pluginTutorial/webStart/cy.jnlp WEB START]. To create your own webstart please read through this tutorial first [“Cytoscape via Java Web Start"]. |
Each plugin tutorial includes the Java source code and a jar file containing the compiled classes. To run Cytoscape via Java Web{{{}}}Start with all of these plugins automatically loaded, click here: [http://cytoscape.org/pluginTutorial/webStart/cy.jnlp WEB START]. To create your own webstart please read through this tutorial first [“Cytoscape via Java Web Start"]. |
Line 15: | Line 13: |
The {{{CytoscapePlugin}}} class is very simple. It defines a default constructor and one instance method (starting in version 2.5): {{{getPluginInfoObject}}}, which should be overridden to describe what the plugin does as well as other information about it. 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. |
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. |
Line 20: | Line 17: |
{{{#!java |
{{{ #!java |
Line 31: | Line 29: |
Line 35: | Line 32: |
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): | |
Line 36: | Line 34: |
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 |
Line 39: | Line 37: |
{{{#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 |
# 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 |
Line 46: | Line 42: |
# The plugin name that will be displayed to users pluginName=My Plugin |
# The plugin name that will be displayed to users, white space within name is not allowed pluginName=MyPlugin |
Line 49: | Line 45: |
# Description used to give users information about the plugin such as what it does. | # Description used to give users information about the plugin such as what it does. |
Line 56: | Line 52: |
# Compatible Cytoscape version | # Compatible Cytoscape version. If there are more than one version, seperate by ",". |
Line 59: | Line 55: |
# Category, use one of the categories listed on the website or create your own | # Category, use one of the categories listed on the http://cytoscape.org/plugins2.php site |
Line 69: | Line 65: |
pluginAuthorsIntsitutions=Sarah and Victor:ISB;Mike, Kei and Peng:UCSD | pluginAuthorsInstitutions=Sarah and Victor:ISB;Mike, Kei and Peng:UCSD |
Line 74: | Line 70: |
# 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 |
|
Line 75: | Line 74: |
Line 77: | Line 75: |
The {{{PluginInfo}}} object 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. |
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. |
Line 82: | Line 78: |
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: |
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: |
Line 86: | Line 81: |
<target name="jar" description="Create MyPlugin jar file" depends="compile"> | <target name="jar" description="Create MyPlugin jar file" depends="compile"> |
Line 89: | Line 84: |
<manifest> <attribute name="Cytoscape-Plugin" |
<manifest> <attribute name="Cytoscape-Plugin" |
Line 92: | Line 87: |
</manifest> | </manifest> |
Line 94: | Line 89: |
<fileset dir="${classes.dir}" /> | <fileset dir="${classes.dir}" /> |
Line 98: | Line 93: |
Line 102: | Line 96: |
Line 105: | Line 100: |
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). | |
Line 106: | Line 102: |
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). | |
Line 110: | Line 105: |
|
|
Line 113: | Line 106: |
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 [wiki:Plugin_Download_Site_Tutorial Plugin Download Site Tutorial] to learn how to set up your own site. |
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. |
Line 117: | Line 109: |
Line 124: | Line 115: |
=== 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. |
|
Line 125: | Line 118: |
=== Important Plugin Design Note === |
=== 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: |
Line 127: | Line 121: |
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. |
1. Package each of your plugins with the required files (see above). 1. Submit the plugins to the Cytoscape site. 1. Create the following theme definition file (saved as a .txt file) 1. Contact a core developer to assist in submitting your theme. Theme Definition File: {{{ Cytoscape theme definition themeName=ThemeNameNoWhitespace 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 }}} |
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 [http://java.sun.com/docs/books/tutorial/index.html Java Tutorial] for an excellent introduction and handy reference guide for Java. You will also want to check out the [http://www.cbio.mskcc.org/cytoscape/javadoc/ 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: [http://cytoscape.org/pluginTutorial/webStart/cy.jnlp 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://cytoscape.org/plugins2.php site pluginCategory=Scripting/Communication # -- 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>
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:
- Package each of your plugins with the required files (see above).
- Submit the plugins to the Cytoscape site.
- Create the following theme definition file (saved as a .txt file)
- Contact a core developer to assist in submitting your theme.
Theme Definition File:
Cytoscape theme definition themeName=ThemeNameNoWhitespace 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