EPiServer Relate+ Templates Developer Guide
Product version: | EPiServer Relate+ Templates 1.0 |
---|---|
Document version: |
1.1 |
Document last saved: |
07-01-2009 |
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:
Property Name | Description | |||
---|---|---|---|---|
ActionBlogComment |
The name of the write blog comment action |
|||
ActionBlogEntry |
The name of the write blog entry action |
|||
ActionClubMembership |
The name of the become club member action |
|||
ActionClubWallEntry |
The name of the write on club wall action |
|||
ActionCreateClub |
The name of the create club action |
|||
ActionForumReply |
The name of the write forum reply action |
|||
ActionForumTopic |
The name of the write forum topic action |
|||
ActionFriendship |
The name of the become friends action |
|||
ActionImageComment |
The name of the write image comment action |
|||
ActionImageUpload |
The name of the image upload action |
|||
ActionWallEntry |
The name of the write a wall entry action |
|||
ActionVideoComment |
The name of the write a video comment action |
|||
ActionVideoUpload |
The name of the upload video action |
|||
AdministratorsGroupName |
The name of the administrators group |
|||
ArticlePageTypeName |
The name of the article page type |
|||
BlogRootCategory |
The name of the blog root category |
|||
ClubAssociationPropertyName |
The name of the club association custom property |
|||
ClubRootCategory |
The name of the club root category |
|||
CommunityMembersGroupName |
The name of the general members group |
|||
DefaultUserBirthdate | The default value for birthdates of new users | |||
ForumRoomRootCategory | The name of the root forum category | |||
ImageFormats | The available image formats | |||
ImageGalleryRootCategory | The name of the root image gallery category | |||
MailSender | The mail sender information | |||
MaxBlogImageSize | Max size for blog images | |||
MaxClubImageSize | Max size for club images | |||
MaxImageGalleryImageSize | Max size for image gallery images | |||
MaxPortraitImageSize | Max size for portrait image | |||
MinimumVotesRequired | Minimum votes required for an object to be popular | |||
MsnIntegrationHandlerUrl | The URL to the MSN integration handler | |||
MsnWebSignupUrl | The URL to Microsoft MSN Live ID services | |||
MyPageRootCategory | The name of the root my page category | |||
RootForumId | The id of the root forum | |||
VideoGalleryRootCategory | The name of the root video category |
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