Developing ColdFusion MX Applications with CFML
|
|
Building Dynamic Forms
|
Embedding Java applets
The cfapplet
tag lets you embed Java applets either on a ColdFusion page or in a cfform
. To use cfapplet
, you must first register your Java applet using the ColdFusion Administrator Java Applets page (under Extensions on the Server tab). In the Administrator, you define the interface to the applet, encapsulating it so that each invocation of the cfapplet
tag is very simple.
The cfapplet
tag within a form offers several advantages over using the HTML applet
tag:
- Return values Since
cfapplet
requires a form field name
attribute, you can avoid coding additional JavaScript to capture the applet's return values. You can reference return values like any other ColdFusion form variable: Form.
variablename.
- Ease of use Since the applet's interface is defined in the Administrator, each instance of the
cfapplet
tag in your pages only needs to reference the applet name and specify a form variable name.
- Parameter defaults ColdFusion uses the parameter value pairs that you defined in the Administrator. You can override these values by specifying parameter value pairs in
cfapplet.
When an applet is registered, you enter just the applet source and the form variable name:
<cfapplet appletsource="Calculator"
name="calc_value">
By contrast, with the HTML applet
tag, you must declare all the applet's parameters every time you want to use it in a ColdFusion page.
Registering a Java applet
Before you can use a Java applet in your ColdFusion pages, you must register the applet in the Administrator.
To register a Java applet:
- Open the ColdFusion Administrator by clicking on the Administrator icon in the ColdFusion Program group and entering the Administrator password.
- Under Extensions, click Java Applets.
The Java Applets page appears.
- Click the Register New Applet button.
The Add/Registered Java Applet page appears.
- Enter options for the following settings:
Setting |
Description |
Applet Name |
Applet name. |
Code |
Name of the file that contains the applet subclass. Must be relative to the code base URL. The class extension is optional. |
Code Base |
Base URL of the applet: directory that contains the applet components. The applet class files must be located within the web server root directory, such as http://servername/classes . |
Archive |
File name for the applet archive. |
Method |
Method name in the applet that returns a string value. You use the name in the NAME attribute of the cfapplet tag to populate a form variable with the method value. If the applet has no method, leave this field blank. |
Height |
Applet height, in pixels. |
Width |
Applet width, in pixels. |
VSpace |
Measurement, in pixels, for the space above and below the applet. |
HSpace |
Measurement, in pixels, for the space on each side of the applet. |
Align |
Applet alignment. |
Not Supported Message |
Message to display if the user's web browser does not support Java applets. To override this message, specify a different one in the cfapplet tag notsupported attribute. |
Parameter Name |
Name for a required applet parameter, typically provided by the applet. |
Value |
Default value for the parameter. |
- Click Submit.
Applet registration fields
The following table explains the applet registration fields:
Field |
Description |
Codebase |
Enter the base URL of the applet: the directory that contains the applet components. The applet class files must be located within the web browser root directory; for example: http://servername/classes |
Code |
The name of the file that contains the compiled applet. The filename is relative to the code base URL. The *.class file extension is not required. |
Method |
Enter the name of a method in the applet that returns a string value. If you specify the method name in the cfapplet tag name attribute, the value returned by the method is available in the form's action page as Form.name. If the applet has no method, leave this field blank. |
Height |
Enter a measurement in pixels for the vertical space for the applet. |
Width |
Enter a measurement in pixels for the horizontal space for the applet. |
Vspace |
Enter a measurement in pixels for the space above and below the applet. |
Hspace |
Enter a measurement in pixels for the space on each side of the applet. |
Align |
Select the alignment. |
Not Supported Message |
This message is displayed by browsers that do not support Java applets. To override this message, you specify a different message in the cfapplet notsupported attribute. |
Parameter Name |
Enter a name for a required applet parameter. Your Java applet typically provides the parameter name needed to use the applet. Enter each parameter in a separate parameter field. |
Value |
For every parameter that you enter, define a default value. Your applet documentation provides guidelines on valid entries. |
Using cfapplet to embed an applet
After you register an applet, you can use the cfapplet
tag to place the applet in a ColdFusion page. The cfapplet
tag has two required attributes: appletsource
and name
. Because you registered the applet and you defined each applet parameter with a default value, you can invoke the applet with a very simple form of the cfapplet
tag:
<cfapplet appletSource="appletname" name="form_variable">
Overriding alignment and positioning values
To override any of the values defined in the ColdFusion Administrator for the applet, you can use the optional cfapplet
parameters to specify custom values. For example, the following cfapplet
tag specifies custom spacing and alignment values:
<cfapplet appletSource="myapplet"
name="applet1_var"
height=400
width=200
vspace=125
hspace=125
align="left">
Overriding parameter values
You can also override the values that you assigned to applet parameters in the ColdFusion Administrator by providing new values for any parameter. In order to override a parameter, you must have already defined the parameter and a default value for it in the ColdFusion Administrator Applets page, as follows:
<cfapplet appletSource="myapplet"
name="applet1_var"
Param1="registered parameter1"
Param2="registered parameter2">
Handling form variables from an applet
The cfapplet
tag requires you to specify a form variable name for the applet. This variable, referenced like other ColdFusion form variables, Form.
variable_name holds the value the applet method returns when it is executed in the cfform
.
Not all Java applets return values. For instance, many graphical widgets do not return a specific value; they do their flipping, spinning, fading, exploding, and that is all. For this kind of applet, the method field in the Administrator remains empty. Other applets, however, do have a method that returns a value. You can only use one method for each applet that you register. If an applet includes more than one method that you want to access, you can register the applet with a unique name for each additional method you want to use.
To reference a Java applet return value in your application page:
- Specify the name of the method in the Add/Registered Java Applet page of the ColdFusion Administrator.
- Specify the method name in the
name
attribute of the cfapplet
tag when you code your cfform
.
When your page executes the applet, ColdFusion creates a form variable with the name that you specified. If you do not specify a method, ColdFusion does not create a form variable.
Comments