EPiServer Relate+ Templates Developer Guide

Introduction

The EPiServer Relate+ templates package provides a starting point for an integrated EPiServer Community/CMS Web site solution. The templates package includes best practice code solutions and feature examples enabling developers to quickly get started creating customer solutions.

This document provides technical information aimed at developers when using the Relate+ templates.

Table of Contents

• Integration - CMS and Community
• Features
• Templates
• Controls
• Attributes
• Forgot Your Password
• Language
• Page Access Rights
• Web config
• Authentication and Authorization
• Web Browser Support
• Known Limitations
• Further Information

Integration - EPiServer CMS 5 R2 and EPiServer Community v3.2

Community Tab in EPiServer CMS 5 R2 Edit Mode
No steps are required to configure EPiServer Community version 3.2 and EPiServer CMS 5 R2 to work together, as they are integrated as part of Relate+ templates package. In order to view the EPiServer Community Main Menu enter the EPiServer CMS Edit Mode and select the Community tab. User information can be found in the Relate+ User Guide and the EPiServer Community User Guide.

Community Tags

In the News page type there is a property named Community Tags. In this field the user can enter tags separated with a comma. It can either be tags that already exist in the community or new tags. When a News page is displayed, it will also display clubs that are tagged with the same tags under the news item. On the news page there is also a custom property that displays Forum Rooms in from the community. If the user chooses one of the rooms, the News page will then display topics from that room in the right margin.

Articles

On the Article page type there is a custom property for choosing a Club from the community. When the page is saved, it will be saved to the club and the club will be saved to the page, this is carried out by CmsIntegrationModule (Class that listens to publish events of the EPiServer CMS and hooks up clubs to pages). When viewing a club you can see all the articles coupled to that particular club, each of these articles has a link back to the club.

Relate+ Features

MSN Integration

In My Settings (View Mode) the user can add their MSN Live ID, by selecting a link in the right margin. The user will be redirected to Microsoft where approval needs to be performed. The URL for the Microsoft page can be found in the MsnWebSignupUrl setting in the applicationSettings section of the Web.config file. You need to provide a privacy link to the Microsoft page, specified under the SiteSettings tab. When the user accepts, a redirect will occur to MsnIntegrationHandler.aspx - not an EPiServerCMS page. This page will save the returning parameters, mainly the unique MSN identifier of the user for this specific site. The ID that is returned from the Microsoft Web site is provided in the query string parameter "id". Since this parameter is handled by EPiServer CMS a special work around has been implemented in the MsnIntegration class to retrieve the parameter.

Skype Integration

Skype integration is performed by linking to an image at Skype, see http://www.skype.com/share/buttons/.

Security Module

This is an http module that handles group access rights for registered users, club members and sets owner of the MyPage ImageGallery with a custom attribute.
A general Community group called CommunityMembers will be created on installation. The security module will make sure that each new user will be part of this group.
Each time a club is created, a group will be created corresponding to that club. This is handled by the security module. Each new member of a club will be added to the club’s group. 

Extension Methods

All the static information needed about objects, such as URI to an image or utility functions are placed in extension methods in the file ExtensionMethods.cs.

Video Player

In order to use the Video Player feature on a Web site you are required to order a unique access key from EPiServer AB. The access key is to be added to the episerver.community section in the Web.config file:

<episerver.community>
  ...
    <videoGallery pollingIntervalSeconds="60">
     ...
    </videoGallery>
  ...
</episerver.community> 

Redirects

When errors occur, such as a non existent query string parameter, the user will be redirected by the GeneralErrorRedirect() method in the PageBase class. If there is an access violation, such as tampering with query strings, the user will be redirected by the AccessViolationRedirect() method in the PageBase class. If anonymous users attempt to access pages which they do not have access rights to, they will be redirected by the NotLoggedInRedirect() method in the PageBase class. The calls to these functions are made in subpages and user controls that detects the errors.

CurrentUser and DisplayUser

In both PageBase and UserControlBase there are the properties CurrentUser and DisplayUser.

• The CurrentUser will simply return the logged in user, if it exists, otherwise a null value will be returned.
• The DisplayUser is a property that is set by each of the pages and passed to the user controls. The display user is the user, which information we are looking at – e.g. an image gallery. The display is usually set by looking at the user Id in the query string.

AjaxControlToolkit

We use the Ajax Control Toolkit and some of its controls, see http://ajaxcontroltoolkit.com/.

Site Settings

URIs to each of the pages are specified under the SiteSettings tab in the edit mode. The URI:s to the pages are available in code through static properties in the PageBase class.

Categories

The installer will create a root category for each of the modules and three example sub categories under each root. The names of the root categories are stored In the Web config file application.Settings section.

Attributes

See below in the attributes section of this document for the custom attributes that are used. 

Templates

Master Pages

Two Master Pages are included in the Relate+ templates package: ClubMasterPage.master (used by the different club page templates) and RelatePlus.Master.

Page Templates

The page templates included in the Relate+ templates all inherit from the implementation of the PageBase class included in the project.

Code-Beside

In order to separate logic from the html mark up, the Relate+ templates follow the code-beside model.

AutoEventWireup

One approach that was employed when constructing the page templates was to set the AutoEventWireup in the page templates mark-up files to "false" and to override the Onload() function in the code-behind.

Controls

User Controls

ListingBoxControlBase is the base class for all boxes containing a list. ListingBoxControlBase extends EPiServer.UserControlBase.
ListBox filter - most used or most recent.

Web Controls

Included in the Relate+ template package are specially created custom web controls. They are easy to reuse throughout the project.  See below for information regarding these Web controls:

AverageRate.cs
The AverageRate class calculates and displays the average rating and presents it as a series of images.

Button.cs
This is the default button for the Relate+ templates. It renders a LinkButton containing a span tag.

LinkedTags.cs
The class that renders all the tags for an entity in the form of links.

MsnIcon.cs
The class that shows MSN Live status if the user has submitted an MSN Live ID.

Pager.cs
Represents a pager for lists. It takes a page size and an item count and creates a pager on the page. Through the CurrentPageChanged event it alerts the hosting page or control of a page change.

TemplateBox.cs
Defines the default box layout. Set the BoxStyle to decide how the box should render. It is possible to add or delete the types of boxes in this class.

SkypeIcon.cs
Displays a call me icon for Skype for the given user if the user has supplied it's Skype username.

Story.cs
The class that prints the user's story that is given to it. A Story in the contect of the Relates+ templates is a history of the user's actions in the community Web site (for example the user's blog posting history).

PopUp.cs
Creates a modal pop-up control on the page that can be shown and hidden dynamically.

Utils
In the Utils namespace some utility classes exists.

CacheTimeOut.cs
This file includes explicit cache time out intervals for the Relate+ package. In the standard installation all of the values are set to TimeSpan.MinValue for demo purposes, it is strongly recommended to change these to more appropriate values in a live Web site.

Enums.cs
All the enumerators in the project are gathered in this file, such as listing modes and image sizes.

ItemsChangedEventArgs.cs
This is the custom event argument used by the pager.

Validation.cs
This file contains custom static validation methods used throughout the project.

Attributes

The EPiServer Community Attribute system allows developers to set attributes and their values to any object. In the Relate+ package access methods to the custom attributes has been implemented in the ExtensionMethods.cs file.

Add or delete Attributes for different object types by selecting the community tab (EPiServer CMS edit mode) and clicking on Attributes:

Below are the Attributes for the object EPiServer.Common.Security.IUser:

Below is the Attribute of the object EPiServer.Community.Club.Club:

Below is the Attribute of the object EPiServer.Community.Forum.Topic:

Language

Language handling in the Relate+ templates is handled through resource expressions. The English language resource file (relatePlusEN.xml) is delivered with the Relate+ templates. Create language resource files according to the language requirements of your Web solution.

Forgot Your Password

The functionality Forgot your Password requires a relaying smtp server (a mail list handler) to be set up in the mailSettings section in the web.config file.

Page Access Rights

As you would expect access rights to the pages in the Web site are handled through the EPiServer CMS Access Rights function, see the EPiServer CMS 5 R2 Administrator’s Manual for further information. For information regarding handling of the EPiServer Community administrative rights see the Relate+ User Guide and the EPiServer Community User Guide (versions 3.2 or later).

Web.config

In the Relate+ package we have made use of Application Settings that will be stored in the applicationSettings section in the Web.config. The following application settings exists:

Authentication and Authorization

The authentication and authorization system in Relate+ package uses the EPiServerCommonRoleProvider as the default membership and role system.

Web Browser Support

The Relate+ templates are compatible with the following browsers:

• Microsoft Windows Internet Explorer 7
• Mozilla Firefox
• Netscape
• Google Chrome, Opera, Safari

Known Limitations

Microsoft Windows Explorer 6
Is not currently fully supported for the Relate+ templates package.

Source code
Any known source code limitations are listed as comments in the template projects code-beside files.

Further Information

EPiServer Community and Relate+ Get Started
EPiServer CMS 5 R2 SDK API and developer guide
EPiServer Community SDK
EPiServer CMS 5 Get Started - Introductory Information and guidance to developing with EPiServer CMS 5
EPiServer Relate+ User Guide
EPiServer Community User Guide
EPiServer Relate+ Installation Instructions