Extending the functionality of IBM Workplace Forms with the Function Call Interface

Document options Document options requiring JavaScript are not displayed Discuss Sample code New site feature Check out our new article design and features. Tell us what you think. Rate this page Help us improve this content

Level: Intermediate

Liu Jun, Software Engineer, IBM
Deanna Drschiwiski, Information Developer, IBM

13 Feb 2007

Extend the functionality of IBM Workplace Forms applications by using the powerful Workplace Forms Server API and Function Call Interface (FCI) Library tools.

The IBM Workplace Forms Server API offers powerful tools for extending the capabilities of Workplace Forms. Using the Function Call Interface (FCI), you can easily add custom functionality to your Workplace Forms applications.

The FCI is part of the Workplace Forms Server API. It provides a framework, in both Java and C, that allows you to extend the functionality of your forms by creating custom components called extensions. These extensions contain packages of functions that you can call from inside Extensible Forms Description Language (XFDL) forms. By using these custom functions, not only can you return a calculated value, but you can also manipulate the form directly. After you set up the framework for your custom functions, you can use Java system methods, Form Library methods, or even other FCI methods to implement the details of each function.

For detailed information regarding the FCI, see the Workplace Forms Java API User's Manual, which you can download from the developerWorks Workplace Forms documentation page. This article applies to Workplace Forms V2.5 and later.

This article is intended for Workplace Forms developers familiar with IBM Workplace Forms Viewer and Designer.

Creating extensions using the FCI Library

To create an extension with the FCI library, you follow six steps, which are described in detail in the following sections.

Set up the development environment

To use the FCI Library, you must configure your integrated development environment by adding the following files to your CLASSPATH:

If you have Workplace Forms Server API installed on your computer, the two JAR files are also available at the following location:

NOTE: The pe_api.jar file is used for compiling applications that use the API (including the Form Library and the FCI Library), and the uwi_api.jar file is used to compile applications that require backward compatibility.

Create the Extension class

The Extension class contains the extensionInit method, which initializes extensions and provides services for function calls. When a Workplace Forms application is initialized, the API checks for existing extensions both in the Extension folder of Workplace Forms Viewer and in the opened form itself. If it finds any, it calls the extensionInit method in each Extension class.

The Extension class must implement the Extension interface provided by the FCI Library. There are several methods defined in this interface, but extensionInit is the only one you need to implement to create a new FCI extension. This method is used for the instantiation of the FunctionCall object that contains the definition and realization of custom packages and functions. To simplify the creation of the Extension class, you can extend the pre-defined superclass ExtensionImplBase, which implements some methods for you. In this way, you need only to implement the extensionInit method.

To create an Extension class called FCIExtension, follow these steps:

1. In Workplace Forms Designer, create a new Java file called FCIExtension.java.
2. Define the Java package, such as com.IBM.extensions.
3. Import the files listed below (and any other files required by the Java files that call the FCI Library). The list of imported files must come before any class or interface definitions:
• import com.PureEdge.ifx.IFX;
• import com.PureEdge.ifx.ExtensionImplBase;
• import com.PureEdge.ifx.Extension;
• import com.PureEdge.xfdl.FunctionCall;
• import com.PureEdge.xfdl.FunctionCallManager;
• import com.PureEdge.xfdl.FormNodeP;
• import com.PureEdge.IFSUserDataHolder;
• import com.PureEdge.error.UWIException;
4. Implement the extensionInit method as part of the Extension class.
5. Create a new FunctionCall object inside the extensionInit method. To do this, you must call a FunctionCall class constructor and pass it to the IFX Manager as shown in listing 1:
   
   Listing 1. Example of a new FunctionCall object
   

   public class FCIExtension extends ExtensionImplBase implements Extension { public void extensionInit(IFX IFXMan) throws UWIException { this.theFunctionObject = new FciFunctionCall(IFXMan); } }

   
   

The IFXMan object represents the IFX Manager. This object lets you access the other services and objects that you want to use with your extension. UWIException is a generic exception.

Create the FunctionCall class

Now you create the FunctionCall class, which is called by the Extension class and contains your custom methods. It also registers the FunctionCall object and each of the custom functions it supports. The FunctionCall class must implement the FunctionCall interface provided by the FCI. There is no need to implement all the functions defined in the FunctionCall interface. Usually, the FunctionCall class extends the pre-defined superclass FunctionCallImplBase and merely implements the necessary methods.

Inside the FunctionCall class, you must declare each of the custom functions you want to create. Because a FunctionCall class can contain more than one custom function, you should define a unique identification number for each custom function.

To implement the FunctionCall class, follow these steps:

1. In Workplace Forms Designer, create a new Java file called FciFunctionCall.java.
2. Define the Java package.
3. Import the following API packages and any other required files:
• com.PureEdge.ifx.IFX
• com.PureEdge.xfdl.FormNodeP
• com.PureEdge.xfdl.FunctionCallManager
• com.PureEdge.xfdl.FunctionCallImplBase
• com.PureEdge.xfdl.FunctionCall
• com.PureEdge.error.UWIException
4. Create the FunctionCall class. It should extend the superclass com.PureEdge.xfdl.FunctionCallImplBase and implement the FunctionCall interface.
5. Declare a unique identification number for each custom function that you will create with the FCI. In this example, we create two custom functions: functionA and functionB.
6. Define a FunctionCall class constructor that uses the IFX Manager.
7. Declare the evaluate method. This method contains your custom function and is described in further detail later in this article.
8. Add help to your custom function by calling the help method. This method contains your custom function and is also described in further detail later.

In the following example, FciFunctionCall declares two custom methods, functionA and functionB, which have an ID number of 1 and 2, respectively:

                
public class FciFunctionCall extends FunctionCallImplBase 
_implements FunctionCall { 
public static final int FUNCTIONA = 1; 
public static final int FUNCTIONB = 2;

public FciFunctionCall(IFX IFXMan) throws UWIException 
{ 
/* Additional code removed */
} 

public void evaluate(……) 
{ 
/* Additional code removed */
}

public void help(……) 
{ 
/* Additional code removed */
}
}

Create the FunctionCall Class constructor

Before your custom functions can made be available to a Workplace Forms application, you must register the FunctionCall object and each of the custom functions that it supports so that the functions and packages that it contains are recognized.

The FunctionCall class constructor takes the IFX Manager as its parameter. During the process of class constructing, all the registration work is done, including extension and function registration. Essentially, the IFX Manager controls Workplace Forms extensions.

To register the FunctionCall object, do the following:

1. Retrieve the Function Call Manager using the getFunctionCall object. It handles services specific to function calls, such as handling requests for a particular function, and is represented by a FunctionCallManager object.
2. Call the registerInterface method of the IFXMan object to register your extension.
3. Register your packages of custom functions with the registerFunctionCall method of the FunctionCallManager object.

The following example retrieves the Function Call Manager, registers the extension, and registers our two custom functions, functionA and functionB. Note that one of the parameters for each function contains the custom function's unique ID:

                
public FciFunctionCall(IFX IFXMan) throws UWIException
{ 
FunctionCallManager theFCM; 
// retrieve the Function Call Manager
if ((theFCM = IFSSingleton.getFunctionCallManager()) == null)
throw new UWIException("Needed Function Call Manager"); 

//register extension to the IFX Manager
IFXMan.registerInterface(this,   
	FunctionCall.FUNCTIONCALL_INTERFACE_NAME, 
	FunctionCall.FUNCTIONCALL_CURRENT_VERSION, 
	FunctionCall.FUNCTIONCALL_MIN_VERSION_SUPPORTED, 
	0x01000300, 0, null, theFCM.getDefaultListener( ));

//register FUNCTIONA functions to Function Call Manager
theFCM.registerFunctionCall(this, "my_package", "functionA",
 	FciFunctionCall.FUNCTIONA, FunctionCall.FCI_FOLLOWS_STRICT_
	CALLING_PARAMETERS, "S,S", 0x01000300, "Here is functionA’s 
	description"); 

//register FUNCTIONB functions to Function Call Manager
theFCM.registerFunctionCall(this, "my_package", "functionB",
	FciFunctionCall.FUNCTIONB, FunctionCall.FCI_FOLLOWS_STRICT_
	CALLING_PARAMETERS, "S,S", 0x01000300, "Here is functionB’s 
	description"); 
}

NOTE: For detailed information about the registerInterface and registerFunctionCall methods, including descriptions of their parameters, refer to the Workplace Forms Java API User's Manual.

Create your custom functions

There are two methods you must use to create your custom functions:

• Evaluate. This method is called whenever a custom function needs to be executed. When a custom function is called from a Workplace Forms application, the Forms Library retrieves its package and function name. Then it calls the evaluate method, which checks the function’s unique ID and executes the corresponding code segment. Within the method, you can either return a value or manipulate the form in memory directly. The following is an example of the evaluate method:
  
  Listing 4. Sample evaluate method
  

  public void evaluate(String thePackageName, String theFunctionName, int theFunctionID, int theFunctionInstance, short theCommand, FormNodeP theForm, FormNodeP theComputeNode, IFSUserDataHolder theFunctionData, IFSUserDataHolder theFunctionInstanceData, FormNodeP[] theArgList, FormNodeP theResult) throws UWIException { //execute following procedure when a function is run if (theCommand == FunctionCall.FCICOMMAND_RUN) { //check which custom function is called by the unique ID if (theFunctionID == FciFunctionCall. FUNCTIONA_ID) { /* Additional code removed */ } if (theFunctionID == FciFunctionCall. FUNCTIONB_ID) { /* Additional code removed */ } } }

  
  NOTE: For detailed information about the evaluate method, including a description of its parameters, refer to the Workplace Forms Java API User's Manual.
  
  
• Help. This method is used to provide help information to form designers within a development environment, such as Workplace Forms Designer. You should explain your custom function in detail so that the form designer can choose and use the function correctly. The following is an example of the help method:
  
  Listing 5. Sample help method
  

  public void help(String thePackageName, String theFunctionName, int theFunctionID,IFSUserDataHolder theFunctionData, StringHolder theQuickDesc, StringHolder theFunctionDesc, StringHolder theSampleCode, StringListHolder theArgsNameList, StringListHolder theArgsDescList, ShortListHolder theArgsFlagList, StringHolder theRetValDesc, ShortHolder theRetValFlag) throws UWIException { /* Additional code removed */ }

  
  

Build and package the extension

After you create the Extension and FunctionCall classes, you must do the following:

1. Compile the source code to create your class files.
2. Create a manifest file. It should indicate which classes in the Java Archive (JAR) file are part of your extension. The following sample displays a typical manifest:
   
   Manifest-Version: 1.0
Name: com/yourcompany/samples/FCIExtension.class
IFS-Extension: True


3. Package the class files into a single JAR file for distribution. The following example shows the syntax used to build the JAR file, where com is the top package name of the class files:
   
   jar -cvfm FCI.jar manifest.mf com

NOTE: For more information about creating JAR files and manifest files, refer to your Java documentation.

Back to top

Testing and distributing your extension

After you are finish creating your extension, install it for testing. If you are satisfied with its performance, you can distribute it for use in one of the two following ways:

1. Copy the JAR file to the Extensions folder of Workplace Forms Viewer. It is <Viewer Installation Folder>\extensions.
   
   OR
   
   
2. Embed extensions in XFDL forms using Workplace Forms Designer as shown in figure 1. On the Enclosures tab, expand the JAR item, right-click PAGE1, and choose Enclose File from the menu.

Enclosing the extension in Workplace Forms Designer

JAR files that are enclosed in forms must have the MIME type set to application/uwi-jar. For more information about Workplace Forms Designer and MIME types, see the Workplace Forms Designer User's Manual available on the developerWorks Workplace Forms documentation page.

The location at which an extension is installed determines how much access the extension has to the user’s system resources, such as system files. Table 1 summarizes the security features that are set when an extension is installed in a particular location.

Back to top

Creating a sample FCI extension

We now demonstrate how to create extensions with FCI methods and how to use custom functions in XFDL forms. We create a sample extension that retrieves file information from the local file system and displays it in the form. This sample application can also be used to integrate with a database. To achieve this, use the Java API to access file information from the local system and the Form API to manipulate XFDL forms in memory directly.

Figure 2 displays the XFDL form that is used with your extension. A sample JAR file is embedded inside it for distribution.

To access the extension's functionality, click the Browse button and select a file on your computer. The sample custom function accesses the file information and displays the results in the form. Figure 3 shows the form displaying file information that was retrieved by the extension from the local file system.

Creating the sample FunctionCall class

To begin, you must create your FunctionCall class, which includes:

• Importing all the necessary packages.
• Extending FunctionCallImplBase class and implementing the FunctionCall interface.
• Defining a unique ID for your custom function.
• Registering your FunctionCall object.
• Registering your custom function.
• Creating the evaluate method that will contain your custom function.

In the sample FunctionCall class in the side file, "Sample FunctionCall class," the registerFunctionCall method passes the following information to the FunctionCallManager:

• The function package is sample_package.
• The function name is readFile.
• The readFile accepts only one parameter.

For detailed information about the registerFunctionCall method, including a description of its parameters, refer to the Workplace Forms Java API User's Manual.

Creating the Extension class

Next, you need to create your Extension class, as shown in listing 5, which includes:

• Importing all the necessary packages.
• Creating your extensionInit method and passing the IFX Manager to it.
• Calling the FunctionCall class constructor you created in the section, "Creating the sample FunctionCall class."

                
package com.ibm.wpforms.samples;

import com.PureEdge.error.UWIException;
import com.PureEdge.ifx.Extension;
import com.PureEdge.ifx.ExtensionImplBase;
import com.PureEdge.ifx.IFX;

public class FCIExtension extends ExtensionImplBase implements Extension {
public void extensionInit(IFX IFXMan) throws UWIException {
new FciFunctionCall(IFXMan);
}
}

Distributing your custom function

Because your custom function is used to access file information on the local system, you cannot embed it in an XFDL form. Workplace Forms Viewer considers the form insecure and throws Java exceptions. Therefore, you must distribute your custom function to your users in other ways, such as by means of a shared file system, email, download, or administrator installation. Once on the user's system, the JAR file must be saved in the Extensions folder of the Workplace Forms product that uses the extension, for example, <Workplace Forms Viewer program folder>\extensions.

Creating the sample XFDL form

Before you can use your custom function, you must create the XFDL form that triggers the function as shown in the side file, "Sample XFDL form." A sample FCI Extension Eclipse Project with demo form is included in the Download section of this article. To learn more about creating XFDL forms using the Workplace Forms Designer, see the Workplace Forms Designer User's Manual.

Back to top

Using the custom function inside the form

After you embed the custom function, you can use of it inside the form. In this example, let's create a Browse button that allows users to search for files on their computer and triggers the custom function. To do this, follow these steps:

1. Open the sample form in Workplace Forms Designer.
2. Create an XFDL button item in the sample form by selecting a button from the palette and placing it on the form page.
3. With the button selected, click the Source tab.
4. In the form's source code, add a custom option to the button: <custom:onSelect></custom:onSelect>
5. Add a compute attribute to the custom option, ensuring that it is in the XFDL namespace: <custom:onSelect xfdl:compute="">
6. Next, create the compute that will trigger your custom function when the user clicks the Browse button. If the button is activated, then set the file location using the Workplace Viewer fileOpen function. If a file is selected, then run the custom function; otherwise, do nothing. See listing 6.

                
<button sid="BUTTON1">
	<itemlocation>
		<x>750</x>
		<y>70</y>
		<height>24</height>
	</itemlocation>
	<value>Browse</value>
	<bgcolor>#C0C0C0</bgcolor>
	<custom:onSelect xfdl:compute="toggle(activated,'off','on') == '1' ? 
	set('fileLocation.value', viewer.fileOpen('C:\\', '*.*'))  +. 
	(fileLocation.value != '' ? sample_package.readFile(fileLocation.value) : '')
 	: ''"></custom:onSelect>
	<fontinfo>
		<fontname>Verdana</fontname>
		<size>10</size>
	</fontinfo>
</button>

Back to top

Conclusion

The Workplace Forms Server API and the Function Call Interface Library are powerful, flexible tools for extending the functionality of Workplace Forms applications. We hope that by using the step-by-step instructions provided by this article, moderately experienced developers can develop their own custom functions.

Back to top

Download

	Information about download methods

Resources

• developerWorks Workplace article, "Introducing IBM Workplace Forms"
  
  
• developerWorks Workplace white paper, "Overview of IBM Workplace Forms"
  
  
• developerWorks Workplace article, "Introducing IBM Workplace Forms Server API 2.5"
  
  
• developerWorks Workplace Forms product documentation page
  
  
• developerWorks Workplace Forms page
  
  

• Download a trial version of Workplace Forms Designer and Viewer V2.6.1.

• Participate in the discussion forum.

About the authors

		Liu Jun is a software engineer with the FormsCentral team at the IBM China Software Development Lab. He designs and develops IBM Workplace Forms and Forms-related assets for customer applications. He has more than one year of experience with Workplace Forms.

		Deanna Drschiwiski is an Information Developer with the IBM Workplace Forms team in Victoria, BC, Canada. She has been writing about the Workplace Forms product suite since 2000.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top