# Packaging Controls for Installation

You can easily package your controls for delivery to users. This topic describes how to do so, and includes the following sections:

- Available Controls: Stubs and Deliverables. Controls may be available to the user without being present in their installation.
- Using Control Stubs as Placeholders. WebLogic Workshop supports just-in-time control installation.
- Making Control Deliverables. You can easily package your control in a control deliverable.
- User-Specified Control Library Locations. Users can specify multiple locations where the IDE should look for control libraries.
- Control Appearance in the Insert Menu. You can configure how and where controls appear in the Insert menu.

## Available Controls: Stubs and Deliverables

WebLogic Workshop supports the idea of available controls. An available control is one that is visible to the user, but whose implementation may not yet be installed or even present on the user's computer. From the users standpoint, a control is available when its name appears on the WebLogic Workshop Insert menu. An available control can take one of two forms on the user's computer:

- A control deliverable is a ZIP file that contains everything the control needs in order to be useful to the user. This includes the control's implementation and, if needed, annotation XML files, help files, and so on. When you're ready to test installation of your control, you can make a control deliverable from your control project. For more information on making a control deliverable, see Making Control Deliverables. Note that the control deliverable may also be digitally signed.
- A control stub is a ZIP file that contains information necessary to make the control visible to the user, but without including the control implementation or other files. To make a control visible as a stub, you include a jc-stub.xml file, along with any GIFs that should accompany the control's name on the IDE Insert menu. The control deliverable is downloaded and installed when the user first chooses to add it to an application. If the control is digitally signed, the user will be prompted to accept it. For information on creating stubs, see Using Control Stubs as Placeholders.

### Control Deliverable Installation Process

Through the features described in this topic, WebLogic Workshop installs control deliverables as described here.

When a control deliverable or stub is found on the External Control Library path (described below) it becomes "available". WebLogic Workshop automatically adds the control title and its icon to the Insert -> Controls menu and the application context (right-click) Install menu. If the user chooses to add an available control to an application, Workshop does the control installation as follows:

1. If the item requested by the user is a control stub, the user is asked whether he or she wants to download the control implementation.
2. If the user answers "yes," WebLogic Workshop attempts to download the control deliverable from the location specifed in the jc-stub.xml (described below).
3. When the download is complete, the ZIP file is checked for a signature and the user is prompted with the results of this check. If the user agrees, the stub file is moved to the <BEA_HOME>/ext_components/.installed_subs directory and installation now proceeds as if the control deliverable itself were found on the External Control Library path.
4. Any JAR files found under the /controls directory are copied to the current application's Libraries folder (APP-INF/lib). This may include associated JARs needed by the control.
5. If this is the first time the user has installed the control into any application, the contents of the "help" folder will be copied to <BEA_HOME>/<WEBLOGIC_HOME>/workshop/help/.
   Also, the contents of the "samples" folder will be copied to <BEA_HOME>/<WEBLOGIC_HOME>/samples/partners/
6. WebLogic Workshop starts a rebuild of the help index to incorporate the control's help content.

## Using Control Stubs as Placeholders

A control stub JAR file contains a jc-stub.xml file that describes the control and provides a URL from which the implementation can be downloaded. It should also contain GIF files that will appear with the control's name in IDE menus.

The following is an example of a jc-stub.xml file.

    <stub xmlns="urn:workshop-control/external-stub.xsd">
        <downloadURL>http://www.mycompany.com/controls/MyControl.zip</downloadURL>
        <control>
            <display-in-palette>true</display-in-palette>
            <label>My Control</label>
            <icon-16>myControl16.gif</icon-16>
            <icon-32>myControl32.gif</icon-32>
            <version>1.0</version>
            <palette-priority>3</palette-priority>
            <group-name>My Company's Controls</group-name>
            <group-priority>100</group-priority>
            <interface-class>MyControl</interface-class>
            <implementation-class>MyControlImpl</implementation-class>
            <description>Makes every application run faster and more reliably.</description>
        </control>
    </stub>

The <downloadURL> element must be a valid URL that points to a ZIP file. Other elements have the same meanings as their counterparts in the jc-jar annotation for JCS files.

For the schema on which this XML is based, see ExternalControlStub.xsd.

## Making Control Deliverables

When you are ready to package your control project for testing or delivery, you can make a control deliverable. Remember that a control deliverable is a ZIP file that contains all of the files needed for your control, including its implementation files.

Note: Developing your controls in a control deliverable project greatly simplifies the task of delivering a control that includes documentation and/or samples. For more information, see Control Deliverable Projects.

To make a deliverable, right-click the project folder, then click Build Control Deliverable. WebLogic Workshop will package all the required files into a ZIP file and put the ZIP in the folder that contains your application (the one with the application's WORK file). Note that the ZIP file won't be visible from within the WebLogic Workshop Application view — you'll need to browse the file system to get it. You can also specify the location where WebLogic Workshop should place the control deliverable; you can do this in the control project's properties.

To test the deliverable, you can add it to a folder that's specified as a control library location (see User-Specified Control Library Locations), then add the control to an application.

## User-Specified Control Library Locations

Users can specify multiple locations at which the IDE should look for controls. They do this through the IDE Properties dialog (shown here) by adding external control library paths. User can add paths to ZIP files, JAR files, or merely paths to folders. Control stubs or deliverables

##

## Control Appearance in the Insert Menu

A described previously in this topic and in the core WebLogic Workshop documentation, you can configure how and where your controls appear in WebLogic Workshop's Insert menu. You do this by setting group-name and group-priority values. For control deliverables, you can set these values as attributes of your control's JCS file. For control stubs, you set these values in the jc-stub.xml file.

group-priority

Optional. A number indicating where in the Insert menu the group named in the group-name attribute should appear. Higher numbers (relative to other groups) place the group higher in the menu. Default is 0.

group-name

Optional. The name of the submenu under which this control should appear. If the group-name atribute value ends with the string "Menu" (such as "MyGroupMenu"), then the groupname, stripped of the word Menu, always becomes a submenu name, and all controls sharing that group appear on the submenu. If the group name does not end in the word Menu, then controls in that group appear as top-level items in the Insert Controls menu, unless there are more than five controls in that group. In that case, the group name becomes the top level menu name and all controls in that group appear as sub-menu items.

The following table lists the various sources from which the IDE integrates controls, along with their group-name and group-priority values.

Control Source | group-priority Value | group-name Value | Label
--- | --- | --- | ---
Workshop built-in controls | -900 | Workshop | Database, EJB, JMS, Timer, Web Service
Built-in integration controls | -600 | IntegrationMenu | BEA supplied
Built-in portal controls | -300 | PortalMenu | BEA supplied
Control projects in an application | default 0 | <ProjectName> | User specified
Application’s Libraries folder | default 0 | <ApplicationName> | User specified
User controls in current project | default 0 | Local Controls | User specified
External libraries | Recommended: 100 | Specified by control author | Specified by ctrl author in jc-jar.xml

For more information about JCS attributes, see the @jcs:jc-jar Annotation topic in the core WebLogic Workshop documentation. You can reach this topic quickly by selecting the attribute in the IDE, the pressing F1.

##

Related Topics

None.