IDL 7.1 Plug-in Wizard (Not available in IDL 8)

Topic:

 Note: Plug-ins are not supported in IDL 8.0 and 8.1. However, they are supported  in IDL 8.2. The link below takes you to an article with more information about how to install plug-ins with IDL 8.2:

 http://www.exelisvis.com/Support/HelpArticleDetail/ArticleId/5212.aspx

Introduction

The IDL Plug-in Wizard provides a simple method for IDL users to distribute IDL code or SAVE files to other users. The Plug-in Wizard converts an IDL project into an IDL Workbench feature, and also creates all of the files needed for an update site used to distribute the feature. Other IDL users can use the IDL Workbench update mechanism to locate, download, and install the feature. After a feature is installed, the encapsulated IDL project can be executed.

Table of Contents

• Plug-ins and Features
  • Plug-ins
  • Features
• The Update Site
  • Update Site Structure
  • Site.xml File
  • Update Site File Encoding
• Using the Plug-in Wizard
  • Dialog Options
  • Controlling Properties from the Plugin Wizard and Property Page
  • Including External Code in your Plug-in
  • Distributing DLMs inside a Plug-in
  • Distributing IDL Workbench Actions inside a Plug-in
  • Upgrading Features
  • Removing Previously-installed Features
• Establishing an Update Site
• Downloading Features from an Update Site

Discussion:

Plug-ins and Features

The IDL Workbench is built upon the open-source Eclipse development environment. The Eclipse framework defines an application as a collection of plug-ins to the base Eclipse platform. Each plug-in is a collection of resources — source code, object code, documentation content, or almost any other type of file — that defines what the plug-in does and how it does it. The IDL Workbench itself consists of a set of plug-ins that extend and modify the Eclipse development environment.

Eclipse is designed to easily incorporate plug-ins; you can install a plug-in manually by simply dropping it into the appropriate directory. In IDL's case, this means that you drop plug-ins containing IDL source code (.pro) and save (.sav) files into the directory that contains the IDL Workbench plug-ins (the idlde/plugins subdirectory of the IDL installation directory). This directory is included in IDL's default search path for .pro and .sav files. Once you have installed a new plug-in, you can immediately execute the plug-in's IDL code.

If you want to distribute your plug-in over the Internet, you can use the IDL Workbench Update Manager, whi ch is responsible for downloading new Workbench functionality. However, the Update Manager does not download individual plug-ins; instead, it downloads features, which contain one or more plug-ins, along with several ASCII files that describe the plug-in(s).

To distribute your IDL code plug-in to other IDL users, you would wrap the plug-in inside a feature, and copy the feature to a special Update Site. At this point, an Update Manager can connect to the Update Site and download the feature.

Plug-ins

A plug-in is simply a directory that contains various resource files. For convenience, a plug-in directory is often zipped up into a single file with a .jar extension. When IDL plug-ins are installed, the JAR files are unpacked so the source code files can be found and read by IDL.

A plug-in created by the Plug-in Wizard consists of the following:

The manifest.mf file is a text (UTF-8) file that describes the packaging and prerequisites of your code, and is created by the IDL Plugin Wizard. It consists of a list of name-value pairs, as in the following example:

Manifest-Version: 1.0 
Bundle-ManifestVersion: 2 
Bundle-Name: NewProject 

Bundle-SymbolicName: com.idl.newproject 
Bundle-Version: 2.3.2.v20081002 
Bundle-Vendor: Exelis Visual Information Solutions 

The following table explains the manifest.mf file values:

A plug-in JAR filename has the following syntax:

_.jar 

For example, if a project has a Plug-in ID of purple.rain and a Plug-in Version of 1.9.84, the plug-in JAR file is named purple.rain_1.9.84.jar.

The Plug-in ID and Plug-in Version values are taken from the properties of the project that was selected when the Plug-in Wizard was opened. See IDL Plugin Properties Page for a description of these project properties.

The Plug-in Wizard creates a plug-in to encapsulate the main project code. A plug-in is also generated for each project that is referenced by the main project.

Features

A feature is a wrapper around one or more plug-ins. Physically, it is a directory (or JAR file) that contains two files:

A feature JAR filename has the following syntax:

.feature_.jar 

For example, if the Plug-in ID is purple.rain and the Plug-in Version is 1.9.84, the feature JAR file is named purple.rain.feature_1.9.84.jar.

The Plug-in ID and Plug-in Version values are taken from the properties of the project that was selected when the Plug-in Wizard was opened. See IDL Plugin Properties Page for a description of these project properties.

Feature.xml

The feature.xml file is created by the IDL Plugin Wizard, and has the following structure:

 

id="com.idl.newproject.feature" 
label="NewProject" 
version="2.3.2.v20081002" 
provider-name="Exelis Visual Information Solutions"> 
 
 
 
 
This is a nice little test of the Plugin Wizard. 
 
 
 
(c) 2008 by Exelis Visual Information Solutions, Inc.  
 
 
 
 
 
 

id="com.idl.newproject" 
version="2.3.2.v20081002"/> 
 
 

The following table describes the Feature.xml tags:

com.rsi.idldt.idl.plugin.install.handler.jar

The com.rsi.idldt.idl.plugin.install.handler.jar file is an install handler that contains Java code to be run when the feature is installed. The specific contents of this file are unimportant; at this stage, what matters is that the file contents work as expected.
- back to top -

The Update Site

While you can distribute your IDL code in plug-in form, to do this you must transport the files and the end user must drop the plug-in into the correct IDL directory. There is an alternate method of distributing plug-ins that uses features, Update Sites, and the Workbench Update Manager.

An Update Site is a small collection of files in a set directory structure, located either on a local directory or on a remote machine running a web server. However, the Update Site does not distribute plug-ins. Instead, it hosts features, which are small collections of files that virtually wrap around one or more plug-ins. You can use the Plugin Wizard to package your IDL code into features and create an Update Site to host them. IDL Workbench users can then import or download the features using the Workbench Update Manager.

There are some advantages to distributing IDL code in features, using an Update Site. While a plug-in adds one new module of functionality, a feature can encompass multiple modules of functionality, which makes it an ideal package for wrapping an entire feature set. By distributing code through an Update Site and the IDL Update Manager, you can automate the distribution process and let IDL handle the low-level details. Hosting features on an Update Site is also a convenient way to distribute your IDL code to a large number of users at once.

Update Site Structure

In the directory specifed by the Output Location field on the IDL Plugin Wizard dialog, the Plugin Wizard creates the <plug-in_id>_updatesite directory. All of the Update Site components are inserted into this directory. These components include:

Site.xml File

The site.xml file is created by the IDL Plugin Wizard and contains the information necessary to identify the directory structure as an Eclipse Update Site. It contains a short description of the update site and a list of all features that are available for download through the site. In this case, the file describes a single feature.

The site.xml file has the following structure:

 
 
 
This is a nice little test of the Plugin Wizard. 
 

url="features/com.idl.newproject.feature_2.3.2.v20081002.jar" 
id="com.idl.newproject.feature" version="2.3.2.v20081002"> 
 
 
 
 

The following table describes the Site.xml tags:

Update Site File Encoding

All of the XML files created for the Update Site are required to be saved with UTF-8 encoding. Additionally, the manifest.mf file in a plug-in JAR file is also saved with UTF-8 encoding. All files are created with the correct encoding if you use the IDL Plugin Wizard. If you generate or modify files by hand, be sure to save the files with UTF-8 encoding.
- back to top -

Using the Plug-in Wizard

To start the Plugin Wizard, select a project folder in the Project Explorer and either select Project ? Create Plugin Update Site or right-click and select Create Plugin Update Site from the context menu.

After you enter values in the dialog fields and click Finish, the wizard uses the contents of the selected project (and any other linked projects) and takes the following actions:

Dialog Options

The following table describes the Plugin Wizard dialog options.

Controlling Properties from the Plugin Wizard and Property Page

The IDL Plugin Properties page is almost identical to the IDL Plugin Wizard dialog, and in fact the two are closely associated. If you specify a project's plug-in properties on this page, the IDL Plugin Wizard will use those property values. Conversely, if you specify a project's plug-in properties on the wizard, the values are saved when the wizard is executed, and will be displayed on the IDL Plugin Properties page.

Including External Code in your Plug-in

By default, the Plugin Wizard packages all of a project's files into the resulting plug-in. You can also include external files in a plug-in by linking to the files inside the project. When the Plugin Wizard is run, these linked files will be added to the plug-in.

Linking to external files in a project has several advantages:

Distributing DLMs inside a Plug-in

You can include DLMs (Dynamically Loadable Modules) inside of a plug-in. Refer to Packaging and Installing DLMs for more information.

Distributing IDL Workbench Actions inside a Plug-in

When you create a custom IDL Workbench action, you can distribute it to other users inside a plug-in. A custom action can be exported from the Workbench as a .vexp (Visualization Export) file, which can be installed by another IDL installation.

If you create a plug-in with the Plugin Wizard that includes a .vexp file, the wizard will automatically include the extra installer code inside of the plug-in.

For more information on importing and exporting actions, see Sharing Tools and Actions.

Upgrading Features

IDL allows you to install multiple versions of a feature or plug-in, which are normally installed in the /idlde/features and /idlde/plugins directories.

Note
You must have write permission on the /idlde/plugins directory in order to install IDL plug-ins in that location.

You can also install features and plug-ins to different directories, as long as you add the directories to the IDL path. Due to restrictions imposed by the Eclipse update mechanism, whenever a newer version of a plug-in is installed, it must be installed in the same directory as the previous version of that plug-in.

However, due to the way in which IDL builds its path cache, it is possible that when loading the code within a plug-in, IDL may not use the latest version. To avoid this potential problem, whenever a new version of a plug-in is installed in the Workbench, all previous versions of that plug-in are converted from directory structures into ZIP files bearing the same name as the plug-in directory. This process hides the contents of the old plug-ins (IDL source code and SAVE files) from IDL, ensuring that only the latest version of a plug-in is used.

Removing Previously-installed Features

If you install a new version of a previously-installed feature, the Update Manager does not give you the option to automatically uninstall the older version. While it is not necessary to remove older versions of a feature, you can use the following procedure to uninstall a feature from the IDL Workbench.

Establishing an Update Site

The IDL Plugin Wizard creates an Update Site to host the plug-ins and features it generates. This collection of files in a set directory structure is written to a local directory, along with the generated plug-in(s) and feature, by the Plugin Wizard. This local Update Site is complete, and its feature is ready to be imported or downloaded by an IDL Update Manager.

You can also establish a remote Update Site that is accessable by other IDL users over the Internet. To create a remote Update Site, you must host the Update Site files on a web server in order to make the site directories web-accessible. In addition, you must assign your site a valid URL.
- back to top -

Downloading Features from an Update Site

Use the following procedure to select an Update Site and download a feature through the IDL Workbench Manager.