Purpose

This document will guide you through the first basic steps of building your own WSRP portlet. This document is of a technical nature and is mainly of interest to EPiServer developers.

Table of Contents

Introduction

    - Window States

WSRP Interaction

    - Interact Through the Portal

    - Adding Interaction to HelloWorld

    - Resources

Summary

Introduction

A good way to start learning about how to implement WSRP is to create a small WSRP sample portlet. This technical note guides you through a short "hello world" example and illustrates the basic functionality of a WSRP portlet.

Create the Hello EPiServer Portlet

Registration

All portlets that are available in an EPiServer application must be registered. It is recommended that you do this during the Application Start Event. The minimum code needed to do the registration is displayed below.

If the producer is added to another EPiServer the following services will be displayed: 

The User Control

The user control defined when the portlet is registered will be used to create the markup sent to the consumer. In this first Hello World sample, the user control is very simple. It only contains the text “Hello World!”. No code behind is required.

Of course the sample will not be useful in real life, because it does not support any functionality or graphic design specified by the WSRP standard.

Styles

As mentioned above, the user control will generate a block of markup that will be displayed in the portal when the portal calls getMarkup. Add some more HTML elements to the control. To follow the WSRP specification, each element should be based on a valid CSS class defined in WSRP. Read more about the approximately 40 predefined styles in the WSRP Specification (http://www.oasis‑open.org/committees/download.php/3343/oasis‑200304-wsrp-specification-1.0.pdf).

Because of the standardized styles used in the markup, the final output will be according to the graphical standard defined in the portal. This will give the end user a homogenous site, even if all parts are produced through different producers.

Modes and States

Modes

The WSRP standard defines four different modes – view, edit, preview and help. During registration, each portlet will be able to define which modes it supports. The portal will then display a toolbar accordingly. The selected mode can “behave” differently.

The normal mode of a portlet is wsrp:view mode. In this mode content is shown or a service is used. The end user can also enter data and follow hyperlinks in wsrp:view mode. Typically this is done when a service needs interaction from the end user, such as entering form data or when the end user navigates within a set of information.

Normally a portlet has a wsrp:edit mode in which the end user can do personalized settings of the service. For example, he or she can define how information from behind should be shown, enter configuration data of a service or enter a personalized title of the portlet.

The wsrp:preview mode can be used to give a preview of content or a service related to the settings done in the wsrp:edit mode. The wsrp:preview mode is seldom used.

Each portlet can present its own help function and it is shown in the wsrp:help mode.

Window States

Each portlet can be shown in different window states – normal, maximized, minimized and solo. The portlet can often have different content (markup) in the different states. The portal gives the end user a possibility to gain an overview of a service when it is in normal state (small). When the user wants to start working with the service and maximizes it, it will then show a complete set of tools and information.

When a portlet is shown in wsrp:normal window state, the area showing information is often limited. A typical use of the wsrp:normal window state is to show an overview or a short summary of the information/service of the portlet.

In wsrp:maximized window state, the portlet will use the whole area of the portal workspace.

When a portlet is in wsrp:minimized window state, it will make room for other portlets on the portal page.

The wsrp:solo window state is implemented differently in different portal environments. In some cases it uses the full browser window and in some cases the portlet opens itself in a new window. The wsrp:solo window state is seldom implemented.

WSRP Interaction

Interact Through the Portal

One of the most important things with the portal concept based on WSRP is that all interaction to a portlet is handled through the portal. Every click on a navigational link (referring to a local resource) and every form posting will result in a call to the portal. The portal will then call the portlet based on the arguments in the URL. The action described is called a Blocking Interaction. The portal will now contact the producer and tell it that a Blocking Interaction has been initiated for the specific portlet. The portal also sends another request to the producer asking for new markup (getMarkup) for the portlet.

Adding Interaction to HelloWorld

Add the following line to HelloWorld.ascx and save the file.

When you now click the View mode button in the portal, it will communicate with the producer portlet and will result in an update of the new time-tag in the portlet.

When you click the button, however, nothing happens. This is because EPiServer has not converted the URL – it is not a relative URL. All relative URLs in a markup, generated by the user control, will be converted to WSRP links. All other links are left as they are. Add the following lines to HelloWorld.ascx:

When you now look at the content in the portal, the first “Internal link” has been converted to a WSRP link. Clicking the link will result in an update of the time-tag indicating that the portlet has received a Blocking Interaction call. Clicking the "External link” will instead open the site, as external links are not converted.

Resources