www.ibm.com.au Prosphero Intranet Sample Websphere Portal / Lotus Web Content Management 6.1.5 User Guide 7th October 2010 Authors: Mark Hampton & Melissa Howarth
Introduction This document is a user guide for the Prosphero Intranet Sample Site produced by the IBM Lotus Web Content Management development team. The Prosphero Intranet Sample was designed to illustrate in depth how the 6.1.5 version of IBM Websphere Portal and IBM Lotus Web Content Management can be used to build a best practice intranet site. 4/11/2010 Page 2
What s in the sample Custom theme The sample contains a modified version of the Page Builder theme. The theme has been modified to be content-oriented, using the new content context capabilities in Portal 6.1.5 to fill in the page title, page metadata, breadcrumbs, etc. from WCM. It also pulls images and stylesheets from WCM.A set of layouts were built to go with the theme, which utilise the same stylesheet as the theme. The modified files are: Default.jsp GetContext.jsp /js/pagebuildertheme.js /system/layouts.json /system/styles.json /layouts/1column.jsp /layouts/1row2columnunequal.jsp /layouts/1row3columnequal.jsp /layouts/2columnleft.jsp /layouts/2columnleftsplit.jsp /layouts/3columncenter.jsp /layouts/3columnequal.jsp There are also an additional set of JSPs in the theme which are used in WCM JSP components in the sample. See the section below on JSP Component Scripts. Stylesheet A base stylesheet and two overriding colour schemes are in the sample. These were matched up with existing stylesheet schemes in the Page Builder; this was to make it simple to keep the page customisation working. The stylesheet is stored in the WCM library as a set of content items under the path /Intranet/Stylesheets/... BaseStyles.css InternetExplorerStyles.css /lightgreentheme/lightgreentheme.css /orangetheme/orangetheme.css Page hierarchy The sample page hierarchy all hangs off a single node in the Portal hierarchy under Home. The pages are already mapped to the appropriate site areas and the portlets are all set up appropriate to display content Page templates A set of page templates is provided to make it easier to add news pages into the site, with layouts and portlets already added to the page. You only need create a page from the template, map it to a site area and configure the portlets if required. 4/11/2010 Page 3
Sample site hierarchy The sample site hierarchy mirrors the page hierarchy almost exactly, except that some of the pages under the Home page are actually siblings to the Home Site Area in WCM. This was to avoid having these show up in the sitemap. Sample content has been placed in each area to illustrate the usage of the site. JSP component scripts You can store these in any web app you like but the theme is recommended as it keeps all your rendering code in one place. DisplayAttribute.jsp GetSearchQuery.jsp ItemsByDateRange.jsp RelatedLinks.jsp RenderGroupedListCleanup.jsp RenderGroupedListResult.jsp RenderNestedListCleanup.jsp RenderNestedListResult.jsp SetContext.jsp SetCurrentResultContext.jsp SetFeaturedItemContext.jsp 4/11/2010 Page 4
Installing the sample To install this sample, you should be familiar with WebSphere Application Server administration, WebSphere Portal Administration and Lotus Web Content Management administration. Note that the sample was designed to run in it s own virtual portal, though it could be installed in a root portal if you did not have other sites already running. Also note that the site has been setup for anonymous access; restrict access after installation if you do not want anonymous access to the sample. 1. Unzip sample package onto your local machine - ProspheroSample.zip a. This file contains all of the exported data you need to install the sample site: Prosphero_Theme.ear customised theme deploysampletheme.xml deployment script for the theme Prosphero_Content.zip web content library export Prosphero_Pages.xml page export Prosphero_PageTemplates.xml page templates export 2. Install the Prosphero theme EAR a. The first step is to install a theme ear, as detailed in the link below. The EAR file is called Prosphero_Theme.ear : Note: the ear file should be installed with the context root: /ProspheroTheme http://publib.boulder.ibm.com/infocenter/wcmdoc/v6r1/index.jsp? topic=/com.ibm.lotus.wcm.doc/dev/dgn_dep_theme.html 3. Deploy the Prosphero theme a. The theme then needs to be imported into Portal; a deployment XML has been provided in the sample package called deploysampletheme.xml : NOTE: do not follow steps 5. onwards in these instructions http://publib.boulder.ibm.com/infocenter/wcmdoc/v6r1/index.jsp? topic=/com.ibm.lotus.wcm.doc/dev/dgn_import_theme.html 4. Create a virtual portal a. Now create a virtual portal called Sample to contain the sample site: Note: Do not select the Prosphero theme as the default theme for your virtual portal it was not designed to be used for administrative pages http://publib.boulder.ibm.com/infocenter/wcmdoc/v6r1/index.jsp? topic=/com.ibm.lotus.wcm.doc_v615/admin/advptsk.html 5. Import the WCM library a. Copy the content export file called Prosphero_Content.zip onto your server and unzip it into a new directory b. Then follow the instructions below to import the library: Note you must configure the import to use the directory where you unzipped the content, and to enter the import library name as sample http://publib.boulder.ibm.com/infocenter/wcmdoc/v6r1/index.jsp? topic=/com.ibm.lotus.wcm.doc_v615/wcm/wcm_config_wcmlibrary_export.html 6. Import the sample pages and page templates a. Navigate to the Administration of the Sample virtual portal you created b. Note that your virtual portal has a label called Home remove this now as the sample site already has a Home page c. Import the pages in the file called Prosphero_Pages.xml using the Import XML function d. Import the page templates in the file Prosphero_PageTemplates.xml using the Import XML function 7. At this point you can confirm whether the site is working 4/11/2010 Page 5
a. As the admin user, navigate to the Home link and you should see the Prosphero site and be able to navigate around 8. Create search collection To enable search in the site you need a search collection and you need to create a content source in that collection a. Create a collection: i. Navigate back to the Administration of the Sample virtual portal you created ii. Go to Manage Search and create a new collection called WCMCollection b. If anonymous searching is required, grant anonymous access to the collection: i. Go to Resource Permissions and open PSE Sources ii. Locate your new collection and assign User access to the collection c. Trigger creation of a content source: i. Navigate to the Web Content Authoring interface in your virtual portal, and browse down to the Intranet site ii. Edit the Intranet site, first disable the Searchable option and Save, then reenable the Searchable option and Save again disabling and then reenabling will cause a content source to be created inside WCMCollection d. Kick off the site crawler to index the site: i. Navigate back to the Administration ii. Go to Manage Search and open the WCMCollection iii. Initiate a crawl on the content source that will have been created for you press the button Start Crawler Note: If you choose to create your new search collection with a different name, you will need to re-select it in the Intranet site prior to the second save, and you will also need to modify the Search component called Search Site to use the new collection 9. Set up access control a. If you want anonymous access: i. Navigate to the root Portal Administration and grant anonymous User access to the Web Content Viewer (JSR 286) portlet b. If you do NOT want anonymous access: i. Restrict User access to the site by removing Anonymous from the Home page and Sample library and adding your own site user groups instead c. For site authoring, grant Contributor access to the Sample library for your authoring groups 4/11/2010 Page 6
About The Sample Site Page Editing As the sample site does not use skins, you must use the Edit Page Layout command to modify portlet configuration. This is available inline by opening the customisation bar using the Go to Edit Mode link, and then clicking on the More Actions button. The same screen is of course available through the Administration. To modify the hidden content item pages that are used to display content items, you must first navigate to a specific content item link, and then use the Edit Page Layout command. Authoring You can create, modify and delete content directly in the WCM authoring portlet, or through the inline editing tools placed throughout the site. Each area of the site has a master list that has an inline control for creating content in that area. The template that is used is being driven from the portlet configuration on that page, so if you create new templates, you will need to modify these portlet configurations. Note that throughout the site hierarchy in WCM it is important to create content under the Content site areas you see in each main area. Otherwise they will not appear in the pre-built menus and rules. Workflow & Access Control The sample content has all been set to use a shortcut workflow and all anonymous access for viewing. This was done to make it easier to explore and demonstrate the site. For real-life usage, switch to using workflow s with approval stages and set up access control on the library and pages. Note that adding approval stages will mean content contributed through the inline editing will not be visible until it is approved. Styles The site has no non-semantic markup in the theme, templates or components: the markup consists entirely of container tags like <div>, <span> and <p>, a repeated pattern of list markup across all lists including the navigation, and of course the conten. This allows the site to be re-styled in any number of ways just by modifying in the supplied stylesheets, or supplying additional ones. If a change to the overall layout of the page is required, you may be able to achieve this just through style modification. If style modification is not enough (e.g. you require an additional toolbar, or wish to combine areas on the page) then the default theme jsp will need to be modified to alter the main containers for the site. If layout of the body of the page (the main area where the portlets are displayed) is required, once again style modification may be all that is required. If it is not enough (e.g. you required a completely new layout like a 4 column layout), then you will need to modify the supplied layout JSPs, or supply additional ones. Performance The sample site, as installed, is not using any caching at the portlet or servlet level. This was done to ensure you can play with the product without having to concern yourself with cache timeouts. 4/11/2010 Page 7
If you do choose to use this site as a jumpstart you will need to design an appropriate set of performance criteria, and a performance test, and then implement a caching strategy that allows you to fulfil your performance requirements. Component Wrapper Pattern Many of the portlets in the sample site that appear to be components e.g. home page news, essential links,e tc. are actually content items that wrap formatting around a component. This pattern encourages re-use of the components, and gives you a nicer interface for modifying the wrapper, with inline editing. But it does have one drawback you must be aware of one modifying or building pages: you have to set the Advanced Options Receive links from [None] option. As these portlets are set to show content, the default setting for receiving links would mean they changed context when you click on a link; you do not want that to happen. 4/11/2010 Page 8
Interesting Components Featured Articles See Home Page and News & Community Landing Page A common requirement in sites it to be able to mark a news item, or some other type of content, as being a Feature and for it to be displayed prominently in a list on the home page. The featured article is displayed first, and the list must not contain a duplicate entry for this article. When the next item comes along that is the new feature, the old feature will be displaced from its top billing. Typical solutions to this are either to ensure only a single item is marked with a feature category, or using a hard-coded link that must be updated whenever a new feature is to be displayed. A slightly different approach is taken in this sample. A feature category is used, but it does not have to be removed from the article to ensure displacement by the next feature. How this works is that one menu is used to retrieve a single article the latest article marked as a feature. Another menu is then used to display both this article, and the rest of the latest articles available. Just prior to executing this second menu however, the result of the first menu (i.e. the feature article) is set as the current context. The menu can then render the feature article in the header, and then the rest of the top items in it s results. The hide current item flag is used to ensure the feature article only appears once. Date Range Navigator See News & Community Landing Page, and each of the landing pages in that area For date oriented content like News, Events, Training, and Blogs, it is nice to be able to a date based navigation component to users. The sample includes an implementation of this type of navigation. A content item is used to configure the navigation specifying what type of date range (daily, weekly, monthly, yearly), how many ranges, and which direction to go in. A JSP then sets up the start and end dates for the entire result set and executes a Personalization rule to perform the retrieval. The Personalization rule retrieves all the results, and then sorts them into date order. Another JSP in the result design for the rule component is then responsible for implementing the date range groupings i.e. it detects breaks the date ranges, and then renders a new header for the new date range before continuing to render results. This JSP was written to only display headers for date ranges that have results. Essential Links Often a site has a set of essential links or quicklink or something similar, which are a set of links to areas of the site that you expect users to use. These links are shortcuts that bypass the normal navigation Sometimes this is implemented using a categorisation, but this offers no way of grouping or odering the links. So in our sample site, a different strategy was used: there is a mini site contained off the main site that can be used to set up an explicit essential links navigation. Note that this pattern could be repeated to create multiple essential links navigators that may be used in different parts of your site. Related links All articles in the Business Support and Employee Services areas Another common requirement that is often fulfilled using categories. The problem with using categories is that the author of the content has no control over the related links shown, and cannot order them either. 4/11/2010 Page 9
In our sample site we used explicit linking to implement this feature, with each article having up to three related links, and a JSP which only renders a related links breakout box if there are links to display. Random Tip See Home page This was built using a standard function in Personalization to randomly order results that is not often used. Besides tips it could be used as an alternative way to pull a featured article out, or to have randomized advertising. Grid Navigation See landing pages for Our Company, Business Support and Employee Services This is just a simple stylesheet rendering with floating line items. It is a nice way to create a prominent but scalable navigation solution with imagery. 4/11/2010 Page 10
Customizations There are many other things you could do to customise the site that do not require significant development effort, just re-use of existing components or minor modifications of the site set up. Some ideas: Putting the latest executive communications on the home page instead of, or as well as, a featured story Create new authoring templates for specific content types in the business support and employee services areas Create a news archive section: copy the pattern that was used for the events archive, and use an arbitrary cut-off date for the archived news, e.g. 1 year Create essential links maps in other site areas create an essential links area AFTER the Content area in a second level site area, and then create a component configuration using the essential links component as a guide, but root it at the new sub area Spit the news up into multiple categorisations and display these in separate menus Add a categorisation filter into the search form Advanced Customizations The sample was deliberately kept quite simple. If you intend to use it as a jumpstart for development, you may find that you need to modify it to support a more complex site. Flexible mapping over to content hierarchy The sample has a fixed mapping over from pages to content at the 3 rd navigation level in the site. If you need this to be flexible to allow different areas of the site to switch to content and different navigational levels, then you will need to use a page property to indicate when to switch. Note that this means you will need to modify the Title and Breadcrumb creation code to cope with this. Dynamic 2 nd navigation Moving the 2 nd level navigation into a pop-up would be relatively simple. Render all of the 2 nd level navigators at once, with display:none. Use javascript to detect hover and change the style to display:block. It would also be possible to add the 3 rd level and beyond into the pop-up navigation. This would require pulling content from WCM basically the same content as is showing up in the left hand navigation. Would not be prudent to load this initially, load it on demand using AJAX call. You will need to create a portal page with the navigation on it and load that page asynch with the appropriate context passed in. Dynamic 3+ level navigation Making the left hand side navigation dynamic would reasonably simple, but as you would not want to load this all up immediately, use AJAX instead to avoid loading the whole navigational tree every time. Note that the current navigator already takes care of loading the expanded areas for the current path, so you only need to pull in areas that were not expanded automatically. Or you could choose to stop doing the auto-expansion and always show this navigation collapsed. Embedded Media player The executive communications presentation template currently just shows a link for any media that has been uploaded; this could be changed to embed a player. You may need to include more fields in the authoring template too for size, captions, etc. 4/11/2010 Page 11
Known Limitations/Issues Skin-driven Features No skins are being used in the site, which has a number of functional consequences: - Inline configuration of portlets is not available directly on the page, you must go to Edit page layout - Drag and drop of portlets on the page is not enabled - The default analytics gathering is not enabled Skins where not used to the layout issues we had with the out of the box skins. You could develop your own skin that avoided these issues while still enabling the above functions. Internet Explorer 6 Support There is an override stylesheet for Internet Explorer 6 that corrects layout problems, however it also disables the hover expansion for the date range navigation and just permanently expands. If you wished to have the date range navigation expansion work correctly in Internet Explorer 6 you would need to modify the stylesheet to work off <A> tag hover, or use javascript to perform the expansion instead of styles. The sitemap formatting was not compatible with Internet Explorer 6, so only a very simple stylesheet format was implemented for the Internet Explorer 6 override. If good support for Internet Explorer 6 is important to your requirements, you may want to consider redesigning the sitemap so it will look good even with the more limited stylesheet support in Internet Explorer 6. Dynamic Stylesheet Switch There is an issue we have yet to fix in the dynamic stylesheet selection: in Firefox and Opera the selection applies immediately; in Chrome, Internet Explorer and Safari you have to click to a new style, back to the old one, and then to the new one again to get the stylesheet to apply. The issue was not serious enough to prevent release; when the problem is found a new version will be released. Accessibility The site has not been tested for accessibility. Care was taken in ensuring well structure markup was used, but without a thorough accessibility test there is likely to be some issues that will need to be resolved for a production site, depending on the accessibility requirements of your particular company and usage scenario. Search Form When you run a search, the search query is displayed at the top of the results and in the search again form. To ensure the query stays there as the user pages through the results, the query is stored in the session. This is not ideal given they could have multiple windows or tabs open with search results in them, but it was a simple solution to implement. An alternative 4/11/2010 Page 12