This blog (my first one 😉 is about how to enhance the portal with a user customizable navigation node structure.
Similar to what the Portal Favorites provide, the user can now build up his own navigation tree, starting from an extra node added by this example's portal application. However, this example also enables inclusion of navigation structure subtrees. The developed portal app can be downloaded and used/built upon for future improvements. It is rather small sized (4 classes), so don't fear you'll get mad reading the code.
From a rather architectural point of view, this blog serves as a hint on how to use (or misuse) the Knowledge Management APIs to persist complex, user-dependent data structures. Typically, when it comes to persisting user-dependent data in a portal/web application, you'll get involved with coding JDBC or EJB far to soon. Especially EJB requires additional expertise and some modeling around, while you just want to get something working with little effort no matter how generic or reusable the result will be.
So let's just get first to the
Requirements
I was thinking of initially, the choices I thought of and how to fulfill them, and afterwards I'll explain how it works and have a little user manual handed over to you.
First I thought of giving the user a chance to customize the navigation tree. So I had three sub tasks to think of:
- How to store the customized navigation trees
- How to create a UI for editing the navigation
- How to add the navigation tree to the navigation
Regarding task 1. and 2., there are, of course, lots of possibilities. As a good architect, already knowing your business classes (in this case, a tree structure) you'll first think of the persistence layer, I suspect.
1. Persistence. OK, let's list some programming approaches you could consider - JDBC, SQLJ, CMP Entity Beans, XML files stored in a DB, XML files stored in the KM, XML stored in the PCD, and, of course, POJOs stored as binary data in a database, the KM or the PCD. Aside from the POJOs, all the other approaches are rather too complex for just a little user dependent information, aren’t they? As I do not need to query over any two user’s datasets, I chose to store the data in the Knowledge Management user home directory (aka collection). Persistence of the tree structure is achieved by storing text and parsing the tree information from the text right before display.
This choice was made, I must admit, merely because of my final decision regarding the UI. If I had had the patience to create sort of UI for editing a tree structure, I'd chosen XML as the 'physical' persistence model.
Creating a UI that enables editing tree data structures in the portal. There are various possibilities I will not list here. With a focus on creating as little coding as possible, I reduced this blog's .par editing UI to just 'Editing ASCII text', reusing the KM editing facilities.
Adding the tree to the navigation. Only two possibilities are available here: Add a navigation connector to the portal navigation service or edit the portal content model using the PCM and/PCD APIs (By the way, the PCM/PCD portal applications also add a navigation connector to the navigation service, and this is why the top level nodes in the portal navigation are called roles most of the times.)
Finally, I had two viable approaches at hand:
- Create a UI that enables the user to edit a delta link of his own PCD roles. This means much of UI programming, unless you favor to use unpublished classes of the portal that exactly do this job (See Portal Content Studio Role Editor). This approach would have provided the persistence and the navigation tree display at no programming cost. However, generating a UI that lets you comfortably edit a tree means hard work.
- Create a navigation connector of my own that parses its tree structure stored as ASCII text. As KM already provides the possibility to open a text editor on a given KM resource, using KM as persistence API provides the editing UI part and persistence part at no cost in this case.
So my final choice was the KM text resource based approach. And now, elaborating the
how-it-works
is rather short:
- The .par contains a portal service that adds a navigation connector to the portal navigation service.
- The navigation connector retrieves the KM user home for each user that plays around in the portal.
- In the KM user home repository, it looks up a .txt file resource, generating it with some initial content if necessary.
- The text file is parsed with a loop, creating an object tree structure implementing the necessary navigation API interfaces. The grammar of the text file mimics a Wiki table of contents syntax. Find a description of the grammar below.
- The object tree structure is cached per user until either the resource is changed or a time limit expires. This is done using KM cache facilities.
- For editing, an extra node is added to the root of the navigation tree which points at the KM Online Resource Editor (I’m glad this one exists).
That's all. Still missing are the
Administrator and End User Manuals
Administrator:
- Deploy the .par file to your portal. However never do this in a productive environment, as this is just-for-fun coding and neither your boss nor I will guarantee that I didn't weave any bugs, viruses or Trojan horses into it.
End User:
- Open the portal. Choose Personal Navigation -> Edit Navigation
- Edit the text file. Grammar explanation:
Each line with trailing '+'s represents a tree node. The number of '+'s defines the tree node's level. Following the '+'s, you can write the node name that shows up in the portal, and a '|' sign followed by the link. The link may either be an absolute http address (like http://www.sap.com) or a navigation path (like pcd:portal_content/administrator/content_admin/content_admin_role/com.sap.portal.content_admin_ws/com.sap.portal.portal_content). If you omit the '|', the whole line content will be taken as link and for display.
- Save the file and press Confirm in the portal. You can close the text editing application now. Refresh the browser window by pressing key 'F5'. Have your extra entries.
Appendix
Example of a navigation tree file:
+Google|http://www.google.com ++Yahoo|http://www.yahoo.com +SAP|http://www.sap.com ++SDN|http://www.sdn.sap.com ++Service Marketplace|http://service.sap.com ++Help Portal|http://help.sap.com +KM Content|pcd:portal_content/administrator/content_admin/content_admin_role/com.sap.portal.content_admin_ws/com.sap.km.AdminContent/com.sap.km.AdminContentExplorer and a link to another navigation file in the KM would look like this: ++TOC:othertree|/userhome/Administrator/wikistylenavigation2.txt
Download
Download a .zip file containing a .par which in turn contains the source code from here (You need to be registered to SDN)
