Sun Java System Portal Server 7.1 Community Sample Guide

Chapter 7 Community Template

This chapter contains the following sections:

Overview of the Community Template

This section contains the following:

What Is A Community Template?

A community template is comprised of a set of services (channels) and the visual layout. However, the layout is not always dictated by the community template as in the case with wiki community template where the layout is dictated by the wiki itself. Community templates define (in the role display profile document) the type of services available for the community, the default settings for each service, and the containers that bind the services.

Physically, a community template is a properties file, and image, plus one or more display profile documents. There may be up to three display profile documents, one per community role (such as OWNER, VISITOR or MEMBER). Each role template defines services and the layout associated with the particular role. The content of the role template is represented in a display profile document. In essence, a community template contains the logic for handling different roles (one display profile document per role) and depending on the role, you get a different set of services and a different layout.

Communities are created from a community template. The system may have any number of community templates. In the Community Sample, end users choose a community template when they create a community.

What Are the Available Templates?

The Portal Server software includes:

Two Column: A two column table layout with thin channels on the left and wide channels on the right.
Left Navigation: A menu navigated content layout with menu on the left and selected content on the right.
Wiki: A WYSIWYG layout to allow users to create wiki-like content and page layout including support for wiki plugins, attachments, editing, syntax, and the such

Custom templates can be added to the system. See Creating and Modifying a Template for more information.

How Are The Templates Stored?

The community templates are stored on filesystem. Community templates are stored in PortalServer-DataDir/portals/portal-ID/communitytemplates directory (referred to as communityTemplateBaseDir). Note that this means that each Portal (in a multi-portal deployment environment) will/must have its own set of community templates. The resource bundle in communityTemplateBaseDir defines the meta-data associated with each template. In addition, each template has its own directory where the role templates are stored.

Example 7–1 Sample `communityTemplateBaseDir`

communityTemplateBaseDir     -+-- template1 -+-- owner.xml
                            |              |
                            |              +-- member.xml
                            |              |
                            |              +-- visitor.xml
                            |
                           -+-- template2 -+-- owner.xml
                            |              |
                            |              +-- member.xml
                            |              |
                            |              +-- visitor.xml
                            |
                           -+-- template3 -+-- owner.xml
                            |              |
                            |              +-- member.xml
                            |              |
                            |              +-- visitor.xml
                            |
                            +-- template1.properties
                            |
                            +-- template1_en.properties
                            |
                            +-- template1_fr.properties
                            |
                            +-- template2.properties
                            |
                            +-- template3.properties
                            |
                            +-- template3_en_US.properties
                            |
                            +--       ...

How Are The Templates Managed?

The portal administrator can add a new community template, update an existing community template, archive and restore community templates on the system, and export community templates from one portal instance to others and/or keep them in sync.

Template Syntax and Semantics

Each template is made up of one or more role templates (member.xml, owner.xml, visitor.xml) in XML format. The template directory includes the XML files for the roles that it will serve; for example, member.xml for the community member, owner.xml for the community owner, and visitor.xml for the community visitor.

Each role template is a display profile document for community users in that role. The file must be based on the display profile DTD.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<DisplayProfile version="1.0" priority="%COMMUNITY_DP_PRIORITY%">
	<Properties/>
	<Channels>
		<Container name="%COMMUNITY_CONTAINER%" provider="JSPTableContainerProvider">
			<Properties>
				<String name="title" value="%COMMUNITY_NAME%"/>
				<String name="description" value="%COMMUNITY_DESCRIPTION%"/>
				<Boolean name="compileToRealPath" value="true"/>
			</Properties>
			<Available>...</Available>
			<Selected>...</Selected>
			<Channels>...</Channels>
	</channels>
	<Providers/>
</DisplayProfile>

The tokens (surrounded by %), described below, in the display profile are dynamically replaced by actual values by the template engine when a community is created.

%TOKEN_COMMUNITY_NAME%: Specifies the (user-friendly) name given to the community. For example, tourists.
%TOKEN_COMMUNITY_ID%: Specifies the unique string identifying the community. This name is strictly an internal representation and does not get exposed in the user interface. For example, jdo__tourists.
%TOKEN_COMMUNITY_DESCRIPTION%: Includes a description of the community.
%TOKEN_COMMUNITY_CONTAINER%: Specifies the top-level container for the community. For example, jdo__touristsContainer.
%TOKEN_COMMUNITY_DP_PRIORITY%: Specifies the display profile merging priority given to the resulting community display profile. Each role is given a different value. By default, 1000 for the visitor role, 1005 for the member role, and 1010 for the owner role.
%TOKEN_COMMUNITY_SEARCH_URL%: Specifies the Search server URL for the community.
%TOKEN_COMMUNITY_CONTENTS_SEARCH_DB%: Specifies the search database for the community content.
%TOKEN_COMMUNITY_DISCUSSIONS_SEARCH_DB%: Specifies the discussions database.

Template Descriptor File

Each template includes a resource bundle properties file which defines the meta-data associated with that template. The resource bundle is referred to as the descriptor file that can be localized. Each template descriptor file (must) define the following properties:

id: Specifies an unique ID of the template. The ID must match the template directory name. For example, Baseball for a template directory named Baseball with role templates (or XML files) for all three supported roles.
name: Specifies an user-friendly name used in the user interface (portal desktop) to identify the template. For example, Baseball Template.
description: Contains a verbose description of the template including the services it offers. For example, Baseball-themed template containing the following services: Player Statistics, Game Discussions, TV Schedule, and Online Chat.
tokens: Includes the list of tokens used in the template role files. This merely serves an informative purpose and is not required. For example, %COMUNITY_ID% %COMMUNITY_DESCRIPTION% %COMMUNITY_CONTAINER%.
previewImageURI: Specifies either the absolute or relative URI to the portal context. For example, http://images.domain.com/images/baseball.jpg. The relative URI must be relative to the portal web-app context path.

Example 7–2 Sample Descriptor File

id=Baseball
name=Baseball Template
description=Baseball-themed template containing the following services: Player Statistics, Game Discussions, TV Schedule, and Online Chat
tokens=%COMUNITY_ID% %COMMUNITY_DESCRIPTION% %COMMUNITY_CONTAINER%
previewImageURI=http://images.domain.com/images/baseball.jpg

Creating and Modifying a Template

To create a new or modify an existing template, following the instructions in this section. You can create a template in one of the following three ways:

Export the template, add content, and import the content using the psadmin utility.
Create content and import the content to overwrite existing template.
Add new files to existing templates.

To Create a New Template for Single Portal Environment

Go to the communityTemplateBaseDir.

Create a:
- New directory for the new template
- Copy an existing template to the new template directory
For example, type:
cd PortalServer-DataDir/portals/portal-ID/communitytemplates mkdir NewTemplate cp 2column/* NewTemplate/

Modify the role based display profile documents in the new template directory as needed.

For more information on the role based display profile documents, see Template Syntax and Semantics.

Create and edit the properties file to include the properties described in Template Descriptor File and save the file.

For example, to create a new properties files for the new template, type:
cp 2colimn.properties NewTemplate.properties
Or,
touch NewTemplate.properties
Note –
In order to see the newly added template, log out of any current portal session and re-login to see the change.

To Customize or Modify an Existing Template for Single Portal Environment

Go to the communityTemplateBaseDir/template directory and open the file you wish to modify.

Log out of any current portal session and re-login to see the change.

To Create a Template for Multi-Portal Environment

In a muti-portal environment (when there are more than one portal on the system), use PAR mechanism (as opposed to directly editing files in communityTemplateBaseDir) so that the change of community templates can be applied across multiple portals. This will allow all the portals to have the same set of community templates. If you do not wish to have synchronized environment across portals, use the instructions outlined in To Create a New Template for Single Portal Environment.

Either use psadmin export --type desktop to export desktop data (which includes community templates) and then export it so the content can be edited or, create a new PAR structure from scratch with only the community templates and no other desktop data.

Follow instructions in To Create a New Template for Single Portal Environment to edit content.

Create a new PAR file which contains:

   -+-- META-INF -- MANIFEST.MF
    |    
    +-- pbfiles -+-- communityTemplateBaseDir -+-- template1 -+-- owner.xml
    |                                          |              |
    |                                          |              +-- member.xml
    |                                          |              |
    |                                          |              +-- visitor.xml
    |                                          |
    |                                          +-- template1.properties
    |                                          |
    |                                          +-- template1_en.properties
    |                                          |
    |                                          +-- template1_fr.properties
    |                                          |
    |                                          +-- ...
    |
    +-- static -- community -- images -- template1.gif

Edit or add content as needed.

Create a new PAR file.

Use psadmin import subcommand to import the PAR content across all portals.

If you exported all desktop data, note that psadmin export subcommand will export all desktop data; if you create a new PAR structure from scratch with only the community templates, the command will only export community templates.

Tip –
For more information, see the psadmin export in Sun Java System Portal Server 7.1 Command Line Reference.