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

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

Share:

Liu Jun, Software Engineer, IBM, Software Group

Liu Jun is a software engineer from the IBM Software Services for Lotus team at the IBM China Development Lab in Beijing. His working experience includes IBM Lotus Forms, IBM Lotus Connections, composite applications, and IBM Lotus Mashups. You can reach him at liujunsh@cn.ibm.com.



Deanna Drschiwiski, Information Developer, IBM, Software Group

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.



13 February 2007

Also available in Russian

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:

<Viewer Installation Folder>\2.6\API\70\java\classes\pe_api.jar
<Viewer Installation Folder>\2.6\API\70\java\classes\uwi_api.jar

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

<API Installation Folder>\Lib\Java

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:

Listing 2. Example of FciFunctionCall declaring two custom methods
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:

Listing 3. Example of how to register a FunctionCall object
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.


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.
Figure 1. Embedding extensions
Embedding extensions

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.

Table 1. Security features corresponding to extension location
Location of installed extensionSecurity features
Installed as a JAR or ZIP file in the Extensions folder of Workplace Forms ViewerThe extension has full access to the user’s system resources.
Packaged as a JAR or ZIP file and enclosed directly within a formThe extension has access only to the form that encloses it. The extension cannot access other parts of the user’s system or cause any damage.

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.

Figure 2. XFDL form
XFDL form

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.

Figure 3. Sample form with file information
Sample form with file information

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."
Listing 5. Sample Extension 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.


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.
Listing 6. Sample Browse button
<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>

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.


Download

DescriptionNameSize
FCI sample applicationFCI_Sample.zip1664 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=195149
ArticleTitle=Extending the functionality of IBM Workplace Forms with the Function Call Interface
publish-date=02132007