Customizing Quickr Places

Transcription

1 Customizing Quickr Places Prepared by Bryan Daniel April 21, 2009 Copyright IBM Corporation All Rights Reserved.

2 Contents OVERVIEW A...3 INTRODUCTION...3 REQUIREMENTS...3 PART 1 WCM QUICKR CUSTOMIZATION CREATE A TEAM BLOG PLACE CUSTOMIZE BLOG ENTRY TEMPLATES ACCESS WCM BLOG LIBRARY CUSTOMIZE BLOG WELCOME PAGE INTEGRATE PERSONALIZATION RULES...26 Overview Page 2

3 Overview This lab document will help you understand how Quickr Places can be customized by altering the underlying Lotus Web Content Management (WCM) objects. Persons who have a WCM background and are looking to see how Quickr leverages WCM will find this document very beneficial. Some steps in this document was based on information I learned from the following article: Customizing components in IBM Lotus Quickr services for IBM WebSphere Portal 8.0, by Jonathan Brunn and Axel Sab. Requirements Some knowledge of Lotus Web Content Management (WCM) will be extremely beneficial in learning all concepts covered. The lab is portable and only requires a clean install of Lotus Quickr 8.1 Services for IBM WebSphere Portal. The document refers to lab files (i.e. for copy-pasting/importing values) that I had on the Quickr VM I created. However, if you do not have access to these lab files, you may still complete the lab by manually typing in the content yourself (or copy-pasting the text from this lab document). Overview Page 3

4 Part 1 WCM Quickr Customization ( ~ 40 min ) In this part, you will learn how to customize a Lotus Quickr Place by altering the underlying Web Content Management objects. You will accomplish this by: Starting with a new Team Blog place Customize blog entry templates (authoring and presentation) Access WCM blog library (using Web Content Authoring portlet) Customize blog welcome page Integrate personalization rules (bonus / optional) When complete, the Team Blog place will be customized to allow users to specify the importance (high or normal) of a blog entry. In addition, the default Recent Posts section will be replaced by personalization rules that will display recent Important Posts (only blog entries of high importance). Lab 2 Page 4

5 1.1 Create Team Blog Place In this section, you will create a new team blog place. This place will be further customized in the later sections From the Quickr server, open a browser and go to Login as the administrator (quikradm/password). Click the Create a Place button. Choose Team Blog as the type of place to create: 5. Enter Lotus Team Blog as the name of the place and click the Create button. 6. Click on the Go to Lotus Team Blog button to go to your new place. Lab 2 Page 5

6 7. Observe the default layout of a team blog place: The blog page is composed of components from the underlying Web Content Management (WCM) libraries. The following sections will take you behind the scenes, into these WCM libraries. 1.2 Customize Blog Entry Templates In this section, you will customize the form, or authoring template, that is used when entering a new blog entry. More specifically, a new field will be added that allows the user to specify if this blog entry is important enough to have added attention. You will also customize the presentation template (used to render or present a blog entry) to display the user-specified importance level. 1. From the welcome/main page of the Lotus Blog Place, click the Settings button: 2. Click on the link labeled Advanced Appearance Settings. Lab 2 Page 6

7 3. Click the Customize link located next to the Blog Entry Authoring Template, as shown in the figure below: 4. Enter Lotus Blog - Entry as the template name and click OK. 5. Update the Display Title value to also be Lotus Blog Entry and then click on the Default Content Settings link: 6. Add a new field to the authoring template by completing the following steps: a. Click on the Manage Elements button. Lab 2 Page 7

8 b. Select Option Selection as the element type. Enter Importance as the name and display title, and click the Add button: c. Click the OK button to return to the default content settings screen. 7. Define options for the newly added field by completing the following steps: a. Expand the section named Content to reveal the newly added field: Lab 2 Page 8

9 b. Click the properties icon for the Importance field, as shown in the figure below: c. Check the box labeled Identify this as a required field. d. In the text for specifying choices, enter Normal and High (each on their own line). e. For the User Interface, select Dropdown list. f. Verify the properties appears as follows, and click the Apply button: g. Verify that the field has been updated and now appears as follows: Lab 2 Page 9

10 8. Save the customized authoring template by click the Save button and selecting Save and Close from the drop-down menu. 9. Click on the link labeled Advanced Appearance Settings once more, and verify that the Lotus Blog Entry authoring template is shown. 10. The default presentation template named Blog Entry controls how content will be displayed when the user clicks on a specific blog entry/item. Click the Customize link located next to the Blog Entry Presentation Template, as shown in the figure below: Lab 2 Page 10

11 11. Enter Lotus Blog - Entry as the template name and click OK. 12. Update the Display Title to also be Lotus Blog Entry. 13. Scroll down to the section named Presentation Template. Here you will find the HTML that controls how content is rendered. Content entered via the Authoring Template is referenced by special WCM Tags (ie <Element>). Lab 2 Page 11

12 14. To display the importance value, an additional WCM Element tag must be added to the presentation template. Locate the line <div class="content-container"> and insert the following HTML code immediately before it: <b><br/> Importance: <Element context="current" type="content" key="importance"/> </b> The completed code should appear as follows: 15. Save the customized presentation template by click the Save button and selecting Save and Close from the drop-down menu. Lab 2 Page 12

13 16. Click on the link labeled Advanced Appearance Settings once more, and verify that the Lotus Blog Entry presentation template is also shown Click the OK button to save the updated appearance settings. Test the customized authoring template by completing the following steps: a. Click the New Post button. b. Enter values of your choice for the title and body of the blog entry. c. Observe that the newly added field, Importance, also appears. Leave the value at the default setting of Normal. d. Click OK to save the new blog entry Repeat the previous step and create two more blog entries. This time, se the Importance value of these two new entries to High. When done, you should have three blog entries (one with Normal importance and the other two with High importance). Click on one of the blog entries. Observe that the customized presentation template is used to render the blog item (which shows the Importance field): Lab 2 Page 13

14 21. Click on the Back to Blog link to return to the welcome page of the Lotus Team Blog. 1.3 Access WCM Blog Library A Team Blog place consists of common/shared content (i.e. default blog entry templates) from a shared WCM library and private content (i.e. blog entries, customized templates) from a private WCM library. In this section, you will learn how to use the Web Content Authoring Portlet to access these behind the scenes WCM libraries. This will allow you to perform more advanced customizations (which will be demonstrated in the next section). Lab 2 Page 14

15 1. From the welcome/main page of the Lotus Team Blog, click on Customize link (located in topright corner): 2. Click on Pages and then Advanced Layout Click the New Page button. Enter WCM as the title and click OK. Click the Edit Page Layout button for the WCM page. Lab 2 Page 15

16 5. Click the Add Portlet button on the left. Search for and add the Web Content Authoring portlet: 6. Click Done to save the layout change, and click Done once more to return to the blog welcome page. Lab 2 Page 16

17 7. Click on the newly created WCM page to see the Web Content Authoring portlet. The portlet will provide you access to the underlying WCM libraries used by this team blog place. By default, the Web Content Authoring portlet will only show objects from the Shared Resources WCM library. In order to see objects specific to this team blog, you must configure the portlet (as described in the next steps). 8. Move your mouse pointer towards the top-middle and click on the Click for options link that appears: Lab 2 Page 17

18 9. Click on the Edit Shared Settings link (located in the top right corner). 10. Expand Library Selection and move both Blog and Shared Resources to the right column. Click OK to save. 11. Observe that you can now select the WCM library via the drop-down combo box located in the top-left corner of the portlet: Lab 2 Page 18

19 12. Select the Blog library and then click on Authoring Templates. Observe that the customized authoring template you previously created can be found in this library. 13. Click on Presentation Templates. Observe that the customized presentation template you previously created can also be found in this library: 14. Click on Content By Authoring Template Lotus Blog - Entry. Observe that the blog entries you previously created can also be found in this library: Lab 2 Page 19

20 Important! Special care should be taken when directly modifying objects, particularly those within the Shared Resources library. This library contains components that are referenced by multiple Quickr places. 15. Select the Shared Resources library and then click on Authoring Templates. Observe that the default templates (used by other Quickr places) are found here. 1.4 Customize Blog Welcome Page The Shared Resources library contains a default presentation template for displaying the welcome/main page of a team blog. Modifying this presentation template within the shared resources library will result in a change being made to all team blog spaces. In this section, you will learn how to modify the welcome page for a specific place. 16. From Content Authoring Portlet, select the Shared Resources library and then click on Presentation Templates. Lab 2 Page 20

21 17. Check the box next to the presentation template named Blog - Main. 18. Click the More Actions button and select Copy from the drop-down menu: Select the library named Blog and click OK. From Content Authoring Portlet, select the Blog library and then click on Presentation Templates. Lab 2 Page 21

22 21. Check the box next to the presentation template named Blog - Main, and then click the Edit button. 22. Update the display title to be Lotus Blog - Main. Lab 2 Page 22

23 23. Scroll down to the section named Presentation Template. Append the following lines to the end of the existing HTML code: <br/><b>for questions on this place, please see Bryan Daniel.</b> The completed code should appear as: Save the customized presentation template by click the Save button and selecting Save and Close from the drop-down menu. Click on the Team Blog page to navigate back to the Lotus Team Blog. Observe that the changes you made to the presentation template do NOT appear. This is because the blog is still referencing the default/shared presentation template. Complete the following steps to configure the Lotus Team Blog so that it uses the customized Lotus Blog Main presentation template when rendering the main/welcome page: a. Click on the WCM page to navigate back to the Content Authoring portlet. Lab 2 Page 23

24 b. Verify that the Blog library is currently selected: c. Navigate to Site Areas By Site. Check the box next to the site named Blog and click the Edit button: d. Scroll down to the section named Site Properties. This section maps authoring templates to presentation templates. Note that content created from the Welcome authoring template will be rendered using the Blog Main presentation template. Click on the Edit Mapping button to change this to the customized Lotus Blog Main presentation template. Lab 2 Page 24

25 e. Select the Welcome / Blog Main mapping and click Edit. f. For the Authoring Template, choose the Shared Resources library and select the Welcome authoring template. For the Presentation Template, choose the Blog library and select the Lotus Blog Main presentation template. Click OK to accept the mapping. g. Click OK once more to save the mapping. h. Verify that the Welcome Authoring Template now maps to the customized Lotus Blog Main presentation template: i. Save the changes to the Blog site by clicking on the Save button and selecting Save and Close from the drop-down menu. Lab 2 Page 25

26 26. Click on the Team Blog page once again to navigate back to the Lotus Team Blog. This time, observe that the customized changes now appear: 1.5 Integrate Personalization Rules ( Bonus / Optional ) Thus far, you have customized the team blog to allow users to specify which entries have high importance. However, the importance value is only shown when viewing a specific blog entry. In this section, you will update the Recent Posts section of the main page to show only entries that have high importance (as opposed to just showing all recent entries). This will be accomplished by defining and integrating personalization rules. 1. From the Lotus Team Blog, click on the WCM page to navigate back to the Content Authoring portlet. Lab 2 Page 26

27 2. Verify that the Blog library is selected: Click the New button and select Component Personalization from the down-down menu. Enter lotus_blog_pzn as the name and Lotus Blog PZN as the display title. 5. Scroll down to the section named Personalization Element and click the Search button. Clicking the New button will embed the rule within the personalization component, and as a result will not make it available for reuse by other components. For the purpose of this lab, we will click Search and then define a new rule that will be stored within the personalization workspace Click the New button and select Rule from the drop-down menu. Enter Select Important Lotus Blog Entries as the name and choose Select Action as the rule type. Lab 2 Page 27

28 8. Click the content* link and choose Web Content. 9. There are no predefined attributes for determining the site area of a blog entry. Fortunately, there is a method to define custom attributes. Complete the following steps to define a request attribute for holding the site area id. (You will later use a custom JSP to determine the site area id and store it in the request for use by this personalization rule.) Lab 2 Page 28

29 10. Click the value link for site area. Select Request Manage Properties from the popup menu Click the Add Dynamic Property button. Enter siteid as the name for the dynamic property, select text as the type of attribute, and enter siteid as the name to use in the rule editors. Click Save to save the new property. Lab 2 Page 29

30 13. Verify that the siteid attribute is listed as a dynamic property and click the Done button to return to the rule definition screen. 14. Click the value link for site area once again. This time, select Request siteid from the popup menu. Verify that the rule appears as follows: 15. Click the is link next to Site Area and choose is included in. Lab 2 Page 30

31 16. Click the attribute link and select Lotus Blog Entry Importance from the menu. (You may have to scroll down on the popup menu.) 17. Click on the > symbol next to the value link and select High from the popup menu. 18. Click the order as is link complete the rule so it appears as order by Creation Date descending, as shown in the following figure: 19. Lastly, click the show all items link enter 5 as the value (click the submit link that appears to save the value). Lab 2 Page 31

32 20. Verify that the rule appears as shown in the following figure and then click the Save button. Due to the manner in which the rule is defined, the Preview tab/page will NOT work. Remember, the required site id will be passed at runtime as a request attribute. If you click on the preview tab/page now, the site id will be null, and as such, no content will be returned. Lab 2 Page 32

33 21. Check the box for Select Important Lotus Blog Entries and click OK. 22. Verify that the rule now appears within the Personalization Element section: Lab 2 Page 33

34 So far, the Personalization Component is only half-way complete. A rule has been defined that will search for the five most recent blog entries that have been marked as high importance. The remaining steps will configure the personalization component on how the matching items should be displayed. The HTML you will be entering/importing was obtained from the Blog Recent Entries Menu Component (found in the Shared Resources library). 23. Scroll down to the Header field. HTML entered in this field will be displayed before any content. (Think of this as the header of a table.) Click the Import button and import the file <Lab_Files_Dir>\QuickrWCM\pzn_table_header.html. The content of this file included here, for your reference: <div class="info-section"> <h3><label class="sectionheader"> <font color="red">important Posts</font> </label></h3> <div> <ul class="property-list"> 24. Scroll down to the Design for each menu search result field. HTML entered in this field will be displayed for EACH content item to be displayed. (Think of this as the rows of a table.) Click the Import button and import the file <Lab_Files_Dir>\QuickrWCM\pzn_table_rows.html. The content of this file included here, for your reference: <li> <a class="item-link" href="<placeholder tag="href"/>" id="<placeholder tag="idnum"/>_<placeholder tag="listnum"/>_recent_post" title="<placeholder tag="title"/>" > <Placeholder tag="title"/> </a> </li> 25. Scroll down to the Footer field. HTML entered in this field will be displayed at the end of any content. (Think of this as the last row of a table.) Click the Import button and import the file <Lab_Files_Dir>\QuickrWCM\pzn_table_footer.html. The content of this file included here, for your reference: </ul> </div> </div> Lab 2 Page 34

35 26. Save the new Personalization Component by clicking on the Save button and selecting Save and Close from the drop-down menu. Recall that the personalization rule you just defined relies on a parameter named siteid to be defined within the request. In the next series of steps, you will define a JSP Component that will use the WCM APIs to determine the site id and save it into the request object (so the personalization rule can later obtain it). 27. Create a directory named customized within <quickr_root>\portalserver\installedapps\wcm_teamspace_portlet_11qc1dzm.ear\11qc1dzm. war\teamspace\jsp\html. Lab 2 Page 35

36 28. Copy the jsp file named currentsite.jsp from <Lab_Files_Dir>\QuickrWCM to <quickr_root>\portalserver\installedapps\wcm_teamspace_portlet_11qc1dzm.ear\11qc1dzm. war\teamspace\jsp\html\customized. The content of this file included here, for your reference: page import="com.ibm.portal.um.*, com.ibm.workplace.wcm.api.*, com.ibm.workplace.wcm.api.exceptions.*" %> <%--Initialize the WCM workspace with the current users context--%> <wcm:initworkspace user="<%=(java.security.principal)request.getuserprincipal()%>" > </wcm:initworkspace> <% try { /* Get rendering context from request */ RenderingContext renderingcontext = (RenderingContext)request.getAttribute("wcmRenderingContext"); if (renderingcontext!= null) { /* Retrieve the site id from rendering context */ String siteid= renderingcontext.getsite().getid().getid(); /* Add siteid to the request */ request.setattribute("siteid", "uuid:"+siteid); System.out.println("siteid="+siteid); } } catch (Exception e) { System.out.println("Custom JSP error occurred. Msg=" + e.getmessage()); } %> 29. From the Web Content Authoring portlet, verify that the Blog library is selected: 30. Click the New button and select Component JSP Component from the down-down menu. Lab 2 Page 36

37 31. Enter site_id_jsp as the name and Site Id JSP as the display title Scroll down to the section named JSP Element. For the Path, enter /teamspace/jsp/html/customized/currentsite.jsp. Save the new JSP Component by clicking on the Save button and selecting Save and Close from the drop-down menu. At this point, you have created a personalization component that runs a personalization rule to select the five most recent highly important blog entries. You ve also defined the JSP component that passes the required site id attribute to the personalization rule. In the last set of steps, you will modify the main/welcome presentation template of the Lotus Blog to render these components. 34. Navigate to Presentation Templates. Check the box next to Lotus Blog Main and click the Edit button. Lab 2 Page 37

38 35. Scroll down to the section named Presentation Template. Insert the following to the top of the existing HTML code: <Component name="site_id_jsp"/> This line will render the JSP Component (which will determine the site id and save it as an attribute in the request for the personalization rule). The HTML code should now appear as: Lab 2 Page 38

39 36. Locate the component tag which renders the Recent posts section: <Component id="c126aa8042fd9a679215f671a :nc9zagfyzwqgcmvzb3vyy2vzl2jsb2dfcmvjzw5 0X3Bvc3Rz" name="shared resources/blog_recent_posts"/> Replace this entire tag so it appears as follows: <Component name="lotus_blog_pzn"/> Lab 2 Page 39

40 37. Click the Save button and selecting Save and READ from the drop-down menu. Verify that an id parameter has been added the component tags you entered (which signify that the component names were found in the library). 38. Click the Close button to close the presentation template. Lab 2 Page 40

41 39. Click on the Team Blog page to navigate back to the Lotus Team Blog. Observe that the Recent posts section has been replaced by an Important Posts section. In addition, only blog entries which have high importance are shown on the list: In this part, you learned how to customize a Quickr Place by configuring objects located within the underlying Web Content Management library. Customization of a blog entry authoring and presentation template was initially accomplished via the place settings screen. More advanced customizations, such as changing the welcome/main blog window and leveraging personalization rules required you to use the Web Content Authoring portlet. Concepts learned in this section can also be applied to other types of Quickr places. END OF LAB Lab 2 Page 41