# Installation and Development Guide

# Portlet Development -
AquaLogic Interaction

The.NET Application Accelerator provides ease-of-use features that make it easy to author ALI portlets. All the features available in the IDK are still available, but some of them are much simpler to use, requiring only a single line of code to accomplish tasks that previously took four or five lines. The .NET Application Accelerator has ALI portlet project templates, file templates for portlet and preference editing pages, and a class library that provides easy access to preferences, user properties, profile information, and other portlet information.

- Getting Started with ALI Portlet Project and File Templates
- Using Preferences with ALI Portlets
- Accessing User Profile Information
- Creating ALI Preference Pages
- Accessing Additional Portlet Information
- Deploying Portlets in AquaLogic Interaction

## Getting Started with ALI Portlet Project and File Templates

The .NET Application Accelerator includes VisualStudio.NET integration for easy authoring of portlets. The provided project templates are pre-configured to include references to required BEA assemblies, including the IDK and new Portlet API libraries. The template is also configured for integration with the ALI PTSpy logging infrastructure and the IDK user profile provider. These settings are available in the site's Web.config file.

A new portlet project also includes a simple portlet page in the Default.aspx / Default.aspx.cs files. This page extends the ALIPortletPage base class, which provides access to preference and user information and also provides easy access to IDK resources such as the PortletRequest and PortletResponse.

Follow the steps below to create a new portlet using the ALIPortletPage template.

1. Create a new ALI Portlet project in VisualStudio.NET:

1. Start VisualStudio.NET.
2. Click File | New | Web Site to create a new project.
3. Select the C# language option.
4. In the My Templates list, select ALI Portlet Project.
5. Name the project "simpleAliWeb".

2. Create a new ALI portlet page:

1. In the Solution Explorer, right-click on the root of the project and select Add New Item...
2. In the My Templates list, select ALI Portlet Page.

The ALIPortletPage class provides access to functionality described in the sections that follow.

## Using Preferences with ALI Portlets

The .NET Application Accelerator provides an easy way to read and write preference values provided to a remote portlet by AquaLogic Interaction. For details on the various levels of preferences, see the AquaLogic User Interaction Development Documentation: http://download.oracle.com/docs/cd/E13174_01/alui/devdoc/docs60/index.html#Overview_of_the_Portal_Architecture/Plumtree_Settings/PlumtreeDevDoc_Integration_SettingsModel.htm

The .NET Application Accelerator allows portlets to manipulate preferences in two ways. First, PortletAttributes corresponding to preference types can be applied to fields in an ALIPortletPage class. The preference types correspond to attributes as follows:

Table 4-1 PortletAttributes
Preference Type | Attribute Name
--- | ---
Admin | AdminPreference
Portlet | PortletPreference
Community | CommunityPreference
CommunityPortlet | CommunityPortletPreference
Session | SessionPreference
User | UserPreference

Preference attributes can be applied to fields with public, protected, or internal visibility with a type of String, int, float, bool, or DateTime. For developers familiar with the IDK, use of a preference attribute on a field in a page replaces calls to read preferences from the IPortletRequest object. The following examples use the UserPreference attribute, but this attribute could be replaced with any of the attributes listed above to read preferences of the corresponding type. Most preferences can be set from a portlet page, but Admin preferences must be set from an ALIPreferencePage (see Creating ALI Preference Pages below).

Fields marked with preference attributes will have their values set after the OnLoad() page event and will have changes persisted during the OnUnload() page event.

The code below reads the "userName" field value from the preference "UserName":

    [UserPreference(Key = "UserName")]
    protected String userName;

Note: | The *permissions modifier* of the variable you are binding must be either public or protected. Private variables (including those with no modifier) cannot be seen by reflection. The binding will not work and you will not know why. For example, the following code will fail:

WARNING: | `[UserPreference(Key = "UserName")] String userName;`

If you do not include a "Key" attribute, the name of the preference defaults to the name of the variable. The code below reads the "usefulValue" portlet preference.

    [PortletPreference()]
    protected String usefulValue;

To set the default value for a preference, use the "DefaultValue" attribute of the preference. The following code sets the "userName" preference to "Anonymous" in the absence of any available user preference value.

    [UserPreference(Key = "UserName", DefaultValue="Anonymous")]
    protected String userName;

Once you bind a variable in your C# class to an ALI preference, it is set when the request is first processed, and any changes to the value of the bound variable are persisted in ALI automatically.

If you must read and write dynamic preferences, use the PreferenceCollection in the ALIPortletPage base class. To access preferences, use the preference name as shown below:

    String dynamicPrefValue = this.PortletPreferences["DynamicPrefName"];
    this.PortletPreferences["DynamicPrefName"] = dynamicPrefValue;

## Accessing User Profile Information

ASP.NET 2.0 introduced the Provider model as a design pattern for plugging data providers into the framework. The .NET Application Accelerator Portlet API uses the ProfilerProvider API to expose user profile information sent by AquaLogic Interaction to an ASP.NET web application that exposes portlets. More information about the ProfileProvider model can be found in the MSDN documentation: http://windowssdk.msdn.microsoft.com/en-us/library/014bec1k.aspx

The Web.config file for an ALI portlet project contains a `<profile>` element that defines a Provider to support reading user profile properties from the portal. To use specific profile properties in a page, add the following XML to the `<profile>` definition:

    <properties>
    <add name="Title" type="String" defaultValue="Test" readOnly="true"/>
    <add name="Age" type="Int32"/>
    </properties>

Note: | AquaLogic Interaction does not allow user profile properties to be modified in a portlet. If this happens, a warning will be logged and the new property value will be dropped. To avoid suprises, add `readOnly="true"` as an attribute in the `<add...>` node in the properties definition as shown above.

Each property is defined with a name and a type. If you provide a default value, it will be used if the profile property was not found in the current request or if the current request is running outside of the portal gateway.

Profile property values can be read in the page using the following code, which reads the "Title" property from the Profile object in the ALIPortletPage super class:

    String title = Profile.Title;

The name of the profile property must match the name sent by AquaLogic Interaction. For details on user profile properties (also called User Information Settings), see the AquaLogic User Interaction Development Documentation: http://download.oracle.com/docs/cd/E13174_01/alui/devdoc/docs60/index.html#Overview_of_the_Portal_Architecture/Plumtree_Settings/PlumtreeDevDoc_Integration_SettingsModel.htm

## Creating ALI Preference Pages

The .NET Application Accelerator integration with VisualStudio.NET and the Portlet API also provides features to easily create portlet preference pages. For more information on ALI preference pages, see the AquaLogic User Interaction Development Documentation http://download.oracle.com/docs/cd/E13174_01/alui/devdoc/docs60/index.html#Portlets/Basics/PlumtreeDevDoc_Integration_Portlets_Settings.htm

To create a new ALI preference page, add a new item to your web site using the steps below:

1. In the Solution Explorer, right-click on the root of the project and select Add New Item...
2. In the My Templates list, select ALI Preference Page.

The ALIPreferencePage template provides the same functionality as an ALIPortletPage and includes additional features for rendering and editing a preference page.

By default, the page renders a title bar with "Finish" and "Cancel" buttons that match the standard ALI preference page style. The appearance and functionality of the title bar can be changed by overriding the `DrawTitleBar()` method from the base class. To complete the preference page, you must implement four methods:

Table 4-2 ALIPreferencePage Methods
Method Name | Description
--- | ---
`GetTitleBarText()` | Read-only property to get the text for the title bar.
`GetFinishButtonText()` | Read-only property to get the text for the finish button.
`GetCancelButtonText()` | Read-only property to get the text for the cancel button.
`SavePreferences()` | Method implemented to update preference values for any preferences changed on the page.

When building portlets in non-English locales, be sure to provide internationalized messages in the three methods that return text labels.

## Accessing Additional Portlet Information

The .NET Application Accelerator Portlet API also exposes some basic functionality from the Plumtree.Remote.Portlet package. In addition to preferences, a variety of other portlet-specific objects are available from a portlet page that extends the ALIPortletPage.

The IRemoteSession portal session can be accessed using the following code:

    IRemoteSession session = this.RemotePortalSession;

The user's name can be accessed using the following code:

    String name = User.Name;

The host page URI can be accessed using the following code:

    URI hostPage = HostPageURI;

More advanced functionality is still available from the IDK classes, which are present in the project's dependencies.

## Deploying Portlets in AquaLogic Interaction

To deploy portlets developed with the .NET Application Accelerator in AquaLogic Interaction, follow the normal steps for configuring the associated portal objects: Remote Server, Web Service - Remote Portlet, and Portlet. For detailed information on portlet configuration, see the Developing Portlets section in the AquaLogic User Interaction Development Documentation: http://download.oracle.com/docs/cd/E13174_01/alui/devdoc/docs60/index.html#Portlets/Basics/PlumtreeDevDoc_Integration_Portlets_Configuration.htm.

## Using Logging with the .NET Application Accelerator

ALI Logging Spy is a logging utility that is automatically installed with AquaLogic Interaction or installed as part of the ALI Logging Utilities, a stand-alone package available for download on dev2dev. ALI Logging Spy listens for log messages transmitted using network broadcast. By configuring a list of message senders, you can listen in on log traffic from multiple BEA applications, live, in a single console.

To add a message listener to your Spy installation, run Spy, select View | Set Filters. In the Filter Settings dialog, click Edit | Add Message Sender and choose a message sender.

The .NET Application Accelerator has three logging message senders:

- .NET WSRP Producer: This is the stand-alone web application designed to serve as a WSRP producer for WLP. It surfaces ASP.NET web applications in WLP by transforming WSRP SOAP requests into HTTP requests, and transforming content so it works in WLP. This name is not configurable and transmits all messages related to the WSRP Producer.
- ALI .NET Application Accelerator: Name reserved for future use. No logging traffic is sent by this sender. The WSRP producer web application also has a "loggingName" entry in web.config that is not currently used.
- WSRPPortletProjectXX: This name is defined in the web.config file of the ASP.NET application built using the .NET Portlet API (the templates installed in Visual Studio .NET 2005). The following line in web.config configures this logging application name:
  `<add key="ptedk.LoggingApplicationName" value="WSRPPortletProjectXX"/>
  `This message sender transmits log messages from the Web Control Consumer and the .NET Portlet API, as well as the IDK.

For more information on configuring ALI Logging Spy, see the ALI Logging Utilities section of the AquaLogic User Interaction Development Documentation: http://download.oracle.com/docs/cd/E13174_01/alui/devdoc/docs60/index.html#Plumtree_Development_Environment/Debugging/PlumtreeDevDoc_DevEnvEDK_Debugging_Intro.htm