You can configure Flex client applications as local portlets on a portal server. You enable Flex client applications for consumption by a portlet consumer by using portal servers that support WSRP.

You enable a Flex application as a portlet on a local portal server by creating a portlet definition that uses the portlet class, flex.portal.GenericFlexPortlet. The GenericFlexPortlet class handles all WSRP requests and returns an HTML-snippet wrapped SWF file for the requested portlet. When using a portal that supports WSRP, the WSRP implementation sends the snippet back in a WSRP supported SOAP message. LiveCycle Data Services ES also provides three default JSP pages, one for each portlet view mode: view, edit, and help. The GenericFlexPortlet class uses these JSP pages by default to satisfy requests for corresponding view modes of a portlet. You can customize the look of each view mode by specifying a custom JSP page for any of the view modes.

Enabling a portlet

You enable a Flex application as a portlet on a local portal server by creating a portlet definition that uses the flex.portal.GenericFlexPortlet class. Each portlet-name value must be unique. The code in the following example portlet.xml portal deployment descriptor file makes a Flex application available as a local portlet:

<portlet>
    <portlet-name>CRMPortlet</portlet-name>
        <portlet-class>flex.portal.GenericFlexPortlet</portlet-class>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>VIEW</portlet-mode>
            <portlet-mode>EDIT</portlet-mode>
        </supports>
        <init-param>
            <name>wsrp_folder</name>
            <value>http://SERVER:PORT/samples</value>
        </init-param>
        <portlet-info>
            <title>CRM Portlet</title>
        </portlet-info>
        <portlet-preferences>
            <preference>
                <name>full_app_uri</name>
                <value>http://SERVER:PORT/samples/samples/dataservice/crm/mini
                </value>
                <read-only>true</read-only>
            </preference> 
        </portlet-preferences>
</portlet>

To expose the same portlet when using web-tier compilation, you change the full_app_uri preference value to http://SERVER:PORT/samples/dataservice/crm/mini.mxml.

To expose the portlet for WSRP consumption, you usually include a remoteable element in the portlet definition in the portlet-server-specific configuration file and set its value to true, as the following example shows:

<portlet-app>
    <portlet>
    <remotable>true</remotable>
    <portlet-name>CRMPortlet</portlet-name>
    </portlet>
</portlet-app>

This enables the Flex application for WSRP consumption by any consumer portal server that has specified the WSDL of your server in its WSRP configuration file.

The wsrp_folder parameter is the only initialization parameter (init-param) that is required for each Flex portlet in the portlet.xml file. You must set this parameter to the fully qualified location of the wsrp-jsp directory that you copy from the lcds\resources\wsrp directory of the LiveCycle Data Services ES installation, as described in Deploying on a portal server. You also must set the full_app_uri preference in the portlet.xml file.

The following preferences are supported by all Flex application portlets:

In addition to these preferences, you can define custom preferences. Custom preferences are ignored by the default JSP files, but can be used in custom JSP pages. Custom preferences must include a cust_ prefix.

View modes

You can view a portlet in one of three modes, VIEW, EDIT, and HELP. By default, the GenericFlexPortlet uses a specific template JSP page corresponding to each of these modes.

Default view modes

The default VIEW mode JSP page simply wraps the reference to the specified SWF file or MXML file in an <object> tag, which sets the width and height to the values specified in the configuration file for this portlet. The default EDIT mode JSP page lets users modify any of the non-read-only preferences and view the values of the read-only preferences. The default HELP mode JSP page displays basic help text. An administrator can specify custom JSP pages for any view mode by setting configuration preferences in the portlet metadata file.

If the producer and consumer servers do not both support the Portlet Management interface, all preferences appear as read-only. For a remote portlet being consumed through WSRP to have modifiable preferences, the consumer must be able to clone the producer portlet. To do so, the implementations of WSRP that the consumer and producer use must implement the optional Portlet Management interface. If one of the implementations does not, all preferences of a remote portlet appear as read-only.

Custom view modes

Portal servers can also support custom view modes. You enable specific portlets for these custom view modes by setting configuration parameters in the portlet deployment descriptor (portlet.xml) file. Because the set of supported custom view modes for a particular installation is not known ahead of time, the GenericFlexPortlet class and default JSP pages do not have any logic for custom view modes. To customize wrappers based on custom view modes, you use custom JSP pages. For details on custom view modes, see the JSR 286 portal specification at http://jcp.org/en/jsr/detail?id=286.

Window states

An incoming markup request from a portlet consumer contains information that indicates whether the portlet in context is MAXIMIZED, MINIMIZED, or NORMAL. This lets the portlet server adjust the markup based on the size of the portlet window. When the GenericFlexPortlet processes a markup request for a portlet that is in the MINIMIZED state, it does not return a SWF file; there is no reason to cause extra network traffic and potential SWF compilation if the user cannot interact with the Flex application. In this case, the GenericFlexPortlet returns text notifying the user that the Flex application is not available in MINIMIZED state. When configuring the portlet for a Flex application, the administrator can specify the width and height of the embedded SWF by using the portlet preferences previously described.

You might require an application to appear differently between MAXIMIZED and NORMAL window states. For example, it might make more sense for a particular panel or widget to be hidden in the NORMAL state and displayed in the MAXIMIZED state. To support such customization, a PORTLET_WS flashvar, which contains the current window state, is returned in SWF file URLs. You can access the value of this variable in your MXML or ActionScript code as Application.application.parameters.PORTLET_WS. Its value corresponds to one of the window states defined in the javax.portlet.WindowState class: normal, maximized, or minimized.

Adaptability to a window state requires that you design a Flex application with portlets in mind, and you use the PORTLET_WS variable in Flex application logic.

EOLAS support

From a February 2006 upgrade to Microsoft Internet Explorer forward, SWF files are not immediately interactive in Internet Explorer unless you specify them through the object or the <embed> tag by using JavaScript in a file external to the main file. If an object tag specifies a SWF file inline in an HTML file, the user sees a Click To Activate message when hovering over the Flex application. To avoid this, the default view JSP page uses a JavaScript library to create the wrappers around Flex applications. The required JavaScript library, AC_OETags.js, is located in the same directory as the three default JSP pages. If you use your own JSP pages outside of the default directory, you must copy the JavaScript library to the correct directory.

Flex AJAX Bridge and Ajax Client Library for LiveCycle Data Services ES

You can use the Flex Ajax Bridge and the Ajax client library for LiveCycle Data Services ES in the portlet-generated JSP pages as long as the necessary parts of FDMSLib.js, FABridge.js and FDMSBridge.as are included in the JSP page. Other non-Flex-based portlets running in the same portal page can communicate with Flex portlets by using the Flex Ajax Bridge and subscribing to the same destinations as the Flex portlets.

Because JavaScript libraries are loaded from the producer server in separate requests from the portlet markup, the <script src=> tags must specify the full URL of the library on the producer server.

Logging

The GenericFlexPortlet writes log messages under the category WSRP.General.

Caching of producer portlets

When the producer server returns markup to the consumer for a particular portlet, it can specify a cache markup time in seconds. If the consumer server has to get the portlet markup for an identical portal page URL during this time, it returns the markup from cache and does not communicate with the producer. The markup_cache_secs preference lets you customize the time. For this property to be meaningful, you must configure the consumer and producer servers to support markup caching in general. If you do not specify the markup_cache_secs preference, there is no markup caching.