VisualWorks Plugin Help
Developing a Plugin Applet
The process of developing an applet is the same as for building any other application in VisualWorks. The application model is typically defined by installing a UI Painter canvas, and then additional methods and classes are defined using the system browsers.
There is a new ApplicationModel subclass for applets, AppletModel, and a new debugging tool for interactive development and debugging, both of which are described in subsequent section.
Building a New Plugin Application
You build an applet, a small application that runs in a web browser, by subclassing AppletModel. AppletModel is a subclass of ApplicationModel that provides the essential API for communicating with a browser and accessing browser services.
When you install a new application class in the UI Painter, select AppletModel as the superclass, to ensure that is works properly as an applet.
Adapting an Existing Application to AppletModel
To use an existing application as an applet, you can either:
Move the application model class to be a subset of AppletModel, or
File-in applet-api.st into your application model class.
If you choose the file-in approach, your applet will behave properly, but will not have access to HTTP GET and POST operations. Refer to the Plugin Application Developer's Guide for details about what the file-in adds.
Debugging an Applet
The Plugin Debugger enables the same interactive debugging capabilities for a applet running in a browser that you have for debugging a normal VisualWorks application running in the development environment. For example, you can:
Press Ctrl-Y to interrupt processing
Set self halt to invoke a debugger
Inspect and change variable values and source code
Starting a Pluggin Debug Session
The Plugin Debug tools allows you to interactively debug a VisualWorks applet while it is running in a web browser. To start a session:
Prepare an HTML document with an EMBED tag to launch the applet. Do not open the page yet.
In your VisualWorks Plugin Development environment, load the applet parcel(s).
In the VisualWorks launcher, select Tools->Plugin Debug Tool.
Check Suppress Loading Plug-in Parcels, and click Enable Debug. See Debugging a Deployed Applet for an alternative procedure.
Open the HTML document in a Web Browser.
In the Debug Tool, click Connect.
The applet is now running in the browser but under the control of the development environment.
Disabling a Debug Session
When you are finished debugging an applet:
Click Disable Debug in the Debug Tool.
This resets the Windows registry entry so VisualWorks applets can launch in a normal session.
Debugging a Deployed Applet
While still under development, you will be debugging the applet while it is already loaded in the development environment, and so choose to suppress loading parcels while launching the applet. This approach does not allow you to verify that the parcels load properly when deployed. To check this, you need to debug the deployed applet.
Copy the HTML page and applet parcel(s) to the web server.
Start the VisualWorks Plug-in Development Environment, and make sure the applet's parcels are unloaded.
In the VisualWorks launcher, select Tools->Plugin Debug Tool.
Uncheck Suppress Loading Plug-in Parcels, and click Enable Debug.
Open the HTML document in a Web Browser.
In the Debug Tool, click Connect.
The applet should now be running using the deployed parcels.
Deploying a VisualWorks Applet
Deploying an Applet involves adding a reference to a web page that embeds the applet in that page, and making the parcel(s) containing the applet available for downloading when that page is accessed.
In the case of a larger application, you also need to build a custom image and provide some mechanism for installing that image on the client systems.
Adding an Applet to a Web Page
You add your application to a web page using the $lt;EMBED> HTML tag. The standard options are supported, and there are a few extension options specifically for the VisualWorks plug-in.
<OBJECT CLASSID="CLSID:FF48278C-094A-4188-95AA-4B1E03F3163C" TYPE="application/x-visualworks-parcel" CODEBASE= "http://mydomain/plugin-install/vwpluginax.cab#version=2,0,X,YYY" WIDTH="500" HEIGHT="300"> <PARAM NAME="PARCEL" VALUE="MyApplet.pcl"> <PARAM NAME="VWOPEN" VALUE="MyApplet"> <B>The ActiveX PlugIn was not installed!</B> </OBJECT>;
The supported attributes are:
CLASSID
The unique GUID identifier of the ActiveX Control.
CODEBASE
The URL which can be used to download and install the plugin if it is not already installed on the machine.
WIDTH
The width of the plug-in window.
HEIGHT
The height of the plug-in window.
TYPE
The MIM type for the plug-in (currently application/x-visualworks-parcel).
PARCEL
The parcel file containing the applet code. This can be an absolute URL or a file name relative to the location of the page containing the applet.
VWOPEN
Name of the class to be opened, eliminating the need for the post-load action.
VWCODEBASE
URL for location of additional parcels. Unless specified, the location is inferred to be the same as that for the SRC.
VWPRELOAD
A list of parcel file names, separated by commas, to be loaded into the image in the specified order.
VWAPPL
The application name associating this instance of the plug-in with a specific image.
Creating a Custom Image
For large, intranet applications, it is often preferrable to install a custom image on the client systems so only a small parcel needs to be downloaded to launch the application. The following is a short version of the procedure to build a custom image. Refer to the Plug-in Application Developer's Guide for more information.
Start the visual.im supplied with VisualWorks.
Load the RuntimePackager and Plugin parcels into the image.
Load the part of your application code that will be permanent in the deployed image.
Unload any unneeded parcels.
In the Settings Tool on the Look and Feel page, set Window placement to Automatic.
Select Tools -> Runtime Packager.
In Runtime Packager, select File -> Load Params, and load vwplugin.rtp, the plugin image removals data file.
In Runtime Packager, select Actions->Set common options, and change the Runtime Image Path Name to the directory path and file name (without the .im suffix) for the deployed image, and click OK. Make sure the name is different than the standard plug-in image name.
In Runtime Packager, select Actions->Strip system.
When the stripping process completes, launch the new image two more times as directed by the text windows. After the second launch, the text window should indicate that the image is ready for use.
Creating the Plug-in Initialization File
The initialization file, VWPLUGIN.INI, is a plain text file that sets attributes for individual instances of the plug-in as well as general attributes.
The supported attributes are:
DIRECTORY
The directory to be "current"
OBJECTENGINE
The path to the executable virtual machine
BASEIMAGE
The directory path and file name of the base image. This is generally needed for custom images.
APPLICATION
A value matching the VWAPPL tag attribute for an applet that starts a section of attributes for this application
EXTRA
Specifies extra information of interest to the application
ALLOW
Specify locations allowed to supply a plug-in parcel
DENY
Specify locations not allowed to supply a plug-in parcel
For example:
BaseImage plugin-win-base.im Application MyApp BaseImage myimage.im Deny all Allow myhost.com Application Debug Directory c:\vw7.3\image ObjectEngine ..\bin\vwntdbg.exe BaseImage mydebug.im Deny all Allow local
Plug-in Security
Security concerns require that applet parcels be certified in some way, to ensure that an applet does not compromise the target system. VisualWorks currently employs a "trusted site" scheme for security.
The Plug-in Security Scheme
Security for applets currently employs a "trusted site" strategy.
You identify trusted sites by defining a filtering scheme in the VWPLUGIN.INI initialization file, using the ALLOW and DENY attributes.
The attribute formats are:
ALLOW < all | local | hostID > DENY < all | local | hostID >
For example, the following sequence of attributes identifies specific sites to be trusted by alternatively allowing and denying access by sites that match the criteria:
Deny all Allow local Allow cincom.com Allow advbool.com Deny pop.advbool.com
Specifying Host IDs
Host IDs can be partial, and can be specified either as IP decimal values or as names.
IP decimal values specify from the network down, and unspecified levels match all values. For example, 216, 216.1, 216.1.2, and 216.1.2.3 all match 216.1.2.3.
Similarly, when specified by name, unspecified levels match all values. For example, com, cincom.com, and www.cincom.com all match www.cincom.com.