Don't miss out Virtual Happy Hour this Friday (April 26).

Try our conversational search powered by Generative AI!

AI OnAI Off

WSRP Configuration

Product version:

EPiServer CMS 4.62

Document version:

1.0

Document creation date:

07-06-2006

Document last saved:

26-10-2007

Purpose

The process of defining and configuring portlets for WSRP producers based on EPiServer CMS was significantly changed in EPiServer 4.60. This document briefly describes the model before EPiServer 4.60 and gives a detailed description of the changed model in EPiServer 4.60 and later. This document also contains instructions for registering the seven sample portlets included in the sample site.

Table of Contents

 

Introduction

Model before EPiServer CMS 4.60

Model from EPiServer CMS 4.60  

Appendix – Register WSRP Portlets


Introduction

The process of defining and configuring portlets for WSRP producers based on EPiServer CMS was significantly changed in EPiServer CMS 4.60. Previously all portlet definitions were done by writing code against the ElektroPost.Wsrp APIs. The APIs are still supported, but the recommended method is to use the declarative method by putting the portlet definitions in web.config.

Model before EPiServer CMS 4.60

The portlet definition code was placed in the file templates/wsrp/core/ProducerBaseSupport.cs / method InitializePortlets(). This method was called at startup from Application_Start in global.asax. Sample portlet registration code:

// Registrer portlets on the server - path to the user control is

// relative to the ASP.NET application root

IPortlet portlet;

portlet = UserControlPortletInvoker.RegisterPortlet("templates\\wsrp\\portletcontrols\\wsrpInfoServiceControl.ascx");

portlet.AddStringResource(Constants.PortletTitle, "Informationsvisningsportlett", "sv");

portlet.AddStringResource(Constants.PortletDescription, "En informationsvisare", "sv");

portlet.AddStringResource(Constants.PortletDisplayName, "Informationsvisaren", "sv");

portlet.AddStringResource(Constants.PortletShortTitle, "Infovisare", "sv");

portlet.AddStringResource(Constants.PortletTitle, "Information Viewer Portlet", "en");

portlet.AddStringResource(Constants.PortletDescription, "An information viewer", "en");

portlet.AddStringResource(Constants.PortletDisplayName, "The Information Viewer", "en");

portlet.AddStringResource(Constants.PortletShortTitle, "Info viewer", "en");

ModifyMarkupType(portlet.DefaultDescription.markupTypes[0]);

portlet.DefaultDescription.groupID = "group1";

portlet.Save(); 

The basic portlet type was a Web user control portlet (a regular .ascx file). To define the portlet you entered the path to the portlet as the name parameter in RegisterPortlet.

Model from EPiServer CMS 4.60

Starting with EPiServer CMS 4.60 you now do the following:

1. Add a configuration handler for elektropost.wsrp to <configSections> in web.config: 

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

       <configSections>

                    <section name="elektropost.wsrp"

                    allowDefinition="MachineToApplication" allowLocation="false"

                    type="ElektroPost.Wsrp.ConfigurationHandler,ElektroPost.Wsrp" />

       -

       -

       -

 

2. Create the elektropost.wsrp section: 

<elektropost.wsrp>

    <exceptionDebugMode>false</exceptionDebugMode>

    <producer>

        <removeUndefinedPortlets>false</removeUndefinedPortlets>

        <portlet name="templates\wsrp\portletcontrols\wsrpInfoServiceControl.ascx">

        <groupID>group</groupID>

        <strings language="en">

            <title>EPiServer Information Viewer Portlet</title>

            <description>View information from EPiServer</description>

            <shortTitle>Information Viewer</shortTitle>

            <displayName>Info Viewer</displayName>

            <keywords>EPiServer</keywords>

            <keywords>Information</keywords>

        </strings>

        <MarkupType>

            <mimeType>text/html</mimeType>

            <modes>wsrp:view</modes>

            <modes>wsrp:edit</modes>

            <windowStates>wsrp:normal</windowStates>

            <windowStates>wsrp:minimized</windowStates>

            <windowStates>wsrp:maximized</windowStates>

            <windowStates>wsrp:solo</windowStates>

            <locales>en</locales>

            <locales>sv</locales>

        </MarkupType>

        </portlet>

    </producer>

</elektropost.wsrp> 

 

Settings

Under <elektropost.wsrp>:

<exceptionDebugMode>

This setting is set to false by default to avoid exposing sensitive information. If set to true, you will get full error messages from the producer side. Enabling this function may help to diagnose producer-based issues.

Under <elektropost.wsrp><producer>

<removeUndefinedPortlets>

If set to true, all producer-offered portlets that are not defined by a <portlet> tag in the <producer> section will be removed, i.e. if you previously had a definition of a portlet in web.config which is now removed, the portlet will be removed from the list of producer-offered portlets. This setting should be false (or removed, default value is false) if you still want to define portlets by code (the old way).

<portlet name=”” type=””>

The following attributes are available

- name
For a regular user control-based portlet this is the path to the .ascx file relative to the root of the Web site. This is a required attribute.

- type
If you want to use a different type of portlet invoker, enter the type name of the portlet here. Note that the type needs to implement the IPortletInvoker interface and it should also have a static method with the following signature:

public

static IPortlet RegisterPortlet(String portletName)

The RegisterPortlet method should create a new instance of the portlet invoker and call the DefaultPortlet.RegisterPortletHelper method, passing the portletName and the portlet invoker instance. I e a typical implementation should look like this:

public static IProducerOfferedPortlet RegisterPortlet( String userControl )

{

    return RegisterPortletHelper(

        userControl,

        new LDAPUserControlPortletInvoker());

}

The type attribute is optional. If not entered it will default to UserControlPortletInvoker.

Tags under <portlet>

<multiLanguage>

A Boolean value (true / false, default false) that indicates if the portlet should use the new globalization support in EPiServer 4.60 / 4.61 to generate markup for the requested locales. (See the WSRP 1.0 specification, section 5.1.10, locales for further information).

<groupID>

Defines the grouping for portlets. See the WSRP 1.0 specification, section 5.1.11 for details. Note that in order for GroupSession (see templates/wsrp/core/WsrpUserControlBase.cs) to work, you must define a groupID.

<defaultMarkupSecure>

A Boolean value (true / false, default false) that indicates if this portlet requires secure communication on its default markup.

<onlySecure>

A Boolean value (true/false, default false) that indicates if the portlet requires secure communication for all its markup.

<strings language=””>

The strings tag is used to define string resources for a portlet. The language attribute is required. You can define strings as shown in WSRP 1.0 specification, section 5.1.11, i.e. you can define <description>, <shortTitle>, <title>, <displayName> and <keywords>. Note that you can define multiple <keywords>. See the example above.

If no <strings> tags are defined for a portlet, the system will use EPiServer's language files to provide localized strings. The strings defined in section /languages/language/wsrp/portlets/<portlet name>/<text> will be used, i.e. the following is a snippet from the LanguageEN.xml file with texts for the portlet

<language name="English" id="EN">

-

-

-

    <wsrp>

        <portlets>

            <wsrpinfoservicecontrol>

                <title>EPiServer Information Viewer Portlet</title>

                   <description>View information from EPiServer</description>

                   <shorttitle>Information Viewer</shorttitle>

                   <displayname>Info Viewer</displayname>

                   <keywords>EPiServer</keywords>

                   <keywords>Information</keywords>

            </wsrpinfoservicecontrol>

            <wsrpiframecontrol>

                   <title>EPiServer IFrame Portlet</title>

                   <description>View information in an IFrame</description>

                   <shorttitle>IFrame Portlet</shorttitle>

                   <displayname>IFrame</displayname>

                   <keywords>IFrame</keywords>

            </wsrpiframecontrol>

            <wsrprsscontrol>

                   <title>EPiServer RSS Portlet</title>

                   <description>View information from RSS source</description>

                   <shorttitle>RSS Portlet</shorttitle>

                   <displayname>RSS</displayname>

                   <keywords>RSS</keywords>

                   <keywords>Rich Site Summary</keywords>

                   <keywords>Real Simple Syndication</keywords>

            </wsrprsscontrol>

            <wsrpnewschannelcontrol>

                   <title>EPiServer News Channel Portlet</title>

                   <description>View news from EPiServer</description>

                   <shorttitle>News Channel Portlet</shorttitle>

                   <displayname>News Channel</displayname>

                   <keywords>News</keywords>

            </wsrpnewschannelcontrol>

            <wsrpusersettingscontrol>

                   <title>EPiServer User Settings Portlet</title>

                   <language>

                   <description>Configure User Settings</description>

                   <shorttitle>User Settings Portlet</shorttitle>

                   <displayname>User Settings</displayname>

            </wsrpusersettingscontrol>

        </portlets>

    </wsrp>

<MarkupType>

Define the different markup types supported by the portlet. You can have multiple <MarkupType> for each portlet. The default is one markup type with the following definition:

<MarkupType>

    <mimeType>text/html</mimeType>

    <modes>wsrp:view</modes>

    <windowStates>wsrp:normal</windowStates>

    <windowStates>wsrp:minimized</windowStates>

    <windowStates>wsrp:maximized</windowStates>

    <locales>en</locales>

</MarkupType> 

If you define one or more markup types, the default markup type will be replaced, i.e. default is only used if no other markup type is defined.

- <mimeType>
The mime type of the markup fragments returned by the portlet. Should almost always be text/html.

- <modes>
Defines portlet modes as per WSRP 1.0 specification, section 5.1.10, section 6.8 and section 6.8.5.

- <windowStates>
Defines possible window states for the portlet as per WSRP 1.0 specification, section 5.1.10, section 6.9 and 6.9.5.

- <locales>
Defines the possible locales that this mime type is available in. See WSRP 1.0 specification, section 5.1.10 for more information.

Appendix – Register WSRP Portlets

The EPiServer CMS sample site comes with seven sample portlets that illustrate how you build portlets using the EPiServer CMS WSRP support. In order to register the portlets included in the sample site, first make sure that you have added a configuration handler for elektropost.wsrp to <configSections> in web.config, as described in the "Model from EPiServer CMS 4.60" chapter.

Add the following to web.config to make the portlets that are included in the sample site available for consumption:

<elektropost.wsrp>

    <producer>

      <removeUndefinedPortlets>true</removeUndefinedPortlets>

      <portlet name="templates\wsrp\portletcontrols\wsrpImageViewer.ascx">

        <groupID>group</groupID>

        <strings language="en">

          <title>EPiServer Image Viewer</title>

          <description>View images from an EPiServer folder</description>

          <shortTitle>Image Viewer</shortTitle>

          <displayName>ImageViewer</displayName>

        </strings>

        <strings language="sv">

          <title>EPiServer bildvisare</title>

          <description>Visa bilder från en EPiServer katalog</description>

          <shortTitle>Bildvisare</shortTitle>

          <displayName>Bildvisare</displayName>

        </strings>

        <MarkupType>

          <mimeType>text/html</mimeType>

          <modes>wsrp:view</modes>

          <modes>wsrp:edit</modes>

          <windowStates>wsrp:normal</windowStates>

          <windowStates>wsrp:minimized</windowStates>

          <windowStates>wsrp:maximized</windowStates>

          <windowStates>wsrp:solo</windowStates>

          <locales>en</locales>

          <locales>sv</locales>

        </MarkupType>

      </portlet>

      <portlet name="templates\wsrp\portletcontrols\wsrpSudokuControl.ascx">

        <groupID>group</groupID>

        <strings language="en">

          <title>EPiServer Sudoku</title>

          <description>Solve a sudoku puzzle</description>

          <shortTitle>Sudoku</shortTitle>

          <displayName>Sudoku</displayName>

        </strings>

        <strings language="sv">

          <title>EPiServer Sudoku</title>

          <description>Ett simpelt tidsfördriv</description>

          <shortTitle>Sudoku</shortTitle>

          <displayName>Sudoku</displayName>

        </strings>

        <MarkupType>

          <mimeType>text/html</mimeType>

          <modes>wsrp:view</modes>

          <windowStates>wsrp:normal</windowStates>

          <windowStates>wsrp:minimized</windowStates>

          <windowStates>wsrp:maximized</windowStates>

          <windowStates>wsrp:solo</windowStates>

          <locales>en</locales>

          <locales>sv</locales>

        </MarkupType>

      </portlet>

      <portlet name="templates\wsrp\portletcontrols\wsrpInfoServiceControl.ascx">

        <groupID>group</groupID>

        <strings language="en">

          <title>EPiServer Information Viewer Portlet</title>

          <description>View information from EPiServer</description>

          <shortTitle>Information Viewer</shortTitle>

          <displayName>Info Viewer</displayName>

          <keywords>EPiServer</keywords>

          <keywords>Information</keywords>

        </strings>

        <strings language="sv">

          <title>EPiServer Informationsvisningsportlett</title>

          <description>Visa information från EPiServer</description>

          <shortTitle>Informationsvisaren</shortTitle>

          <displayName>Infovisare</displayName>

          <keywords>EPiServer</keywords>

          <keywords>Information</keywords>

        </strings>

        <MarkupType>

          <mimeType>text/html</mimeType>

          <modes>wsrp:view</modes>

          <modes>wsrp:edit</modes>

          <windowStates>wsrp:normal</windowStates>

          <windowStates>wsrp:minimized</windowStates>

          <windowStates>wsrp:maximized</windowStates>

          <windowStates>wsrp:solo</windowStates>

          <locales>en</locales>

          <locales>sv</locales>

        </MarkupType>

      </portlet>

      <portlet name="templates\wsrp\portletcontrols\wsrpIframeControl.ascx">

        <groupID>group</groupID>

        <strings language="en">

          <title>EPiServer IFrame Portlet</title>

          <description>View information in an IFrame</description>

          <shortTitle>IFrame Portlet</shortTitle>

          <displayName>IFrame</displayName>

          <keywords>IFrame</keywords>

        </strings>

        <strings language="sv">

          <title>EPiServer IFrame-portlett</title>

          <description>Visa information i en IFrame</description>

          <shortTitle>IFrame-portlett</shortTitle>

          <displayName>IFrame</displayName>

          <keywords>IFrame</keywords>

        </strings>

        <MarkupType>

          <mimeType>text/html</mimeType>

          <modes>wsrp:view</modes>

          <modes>wsrp:edit</modes>

          <windowStates>wsrp:normal</windowStates>

          <windowStates>wsrp:minimized</windowStates>

          <windowStates>wsrp:maximized</windowStates>

          <windowStates>wsrp:solo</windowStates>

          <locales>en</locales>

          <locales>sv</locales>

        </MarkupType>

      </portlet>

      <portlet name="templates\wsrp\portletcontrols\wsrpRssControl.ascx">

        <groupID>group</groupID>

        <strings language="en">

          <title>EPiServer RSS Portlet</title>

          <description>View information from RSS source</description>

          <shortTitle>RSS Portlet</shortTitle>

          <displayName>RSS</displayName>

          <keywords>RSS</keywords>

          <keywords>Rich Site Summary</keywords>

          <keywords>Real Simple Syndication</keywords>

        </strings>

        <strings language="sv">

          <title>EPiServer RSS-portlett</title>

          <description>Visa RSS-information</description>

          <shortTitle>RSS-portlett</shortTitle>

          <displayName>RSS</displayName>

          <keywords>RSS</keywords>

          <keywords>Rich Site Summary</keywords>

          <keywords>Real Simple Syndication</keywords>

        </strings>

        <MarkupType>

          <mimeType>text/html</mimeType>

          <modes>wsrp:view</modes>

          <modes>wsrp:edit</modes>

          <windowStates>wsrp:normal</windowStates>

          <windowStates>wsrp:minimized</windowStates>

          <windowStates>wsrp:maximized</windowStates>

          <windowStates>wsrp:solo</windowStates>

          <locales>en</locales>

          <locales>sv</locales>

        </MarkupType>

      </portlet>

      <portlet name="templates\wsrp\portletcontrols\wsrpNewsChannelControl.ascx">

         <groupID>group</groupID>

        <strings language="en">

          <title>EPiServer News Channel Portlet</title>

          <description>View news from EPiServer</description>

          <shortTitle>News Channel Portlet</shortTitle>

          <displayName>News Channel</displayName>

          <keywords>News</keywords>

        </strings>

        <strings language="sv">

          <title>EPiServer nyhetskanal</title>

          <description>Visa nyheter från EPiServer</description>

          <shortTitle>Nyhets-portlett</shortTitle>

          <displayName>Nyheter</displayName>

          <keywords>Nyheter</keywords>

        </strings>

        <MarkupType>

          <mimeType>text/html</mimeType>

          <modes>wsrp:view</modes>

          <modes>wsrp:edit</modes>

          <windowStates>wsrp:normal</windowStates>

          <windowStates>wsrp:minimized</windowStates>

          <windowStates>wsrp:maximized</windowStates>

          <windowStates>wsrp:solo</windowStates>

          <locales>en</locales>

          <locales>sv</locales>

        </MarkupType>

      </portlet>

      <portlet name="templates\wsrp\portletcontrols\wsrpUserSettingsControl.ascx">

        <groupID>group</groupID>

        <strings language="en">

          <title>EPiServer User Settings Portlet</title>

          <description>Configure User Settings</description>

          <shortTitle>User Settings Portlet</shortTitle>

          <displayName>User Settings</displayName>

        </strings>

        <strings language="sv">

          <title>EPiServer användarinställningar</title>

          <description>Ändra information om användare i EPiServer</description>

          <shortTitle>Användarinställningar</shortTitle>

          <displayName>Användarinställningar</displayName>

        </strings>

        <MarkupType>

          <mimeType>text/html</mimeType>

          <modes>wsrp:view</modes>

          <modes>wsrp:edit</modes>

          <windowStates>wsrp:normal</windowStates>

          <windowStates>wsrp:minimized</windowStates>

          <windowStates>wsrp:maximized</windowStates>

          <windowStates>wsrp:solo</windowStates>

          <locales>en</locales>

          <locales>sv</locales>

        </MarkupType>

      </portlet>

    </producer>

  </elektropost.wsrp>