Friday, February 8, 2013

Building Social Media Toolbars on WebSphere Portal 8

The Business Case
Social Media Toolbars are a popular user interface pattern for many websites today. Providing links to your social media channels helps promote your brand, connects users to your social venues, and can aid both the user and the site owner in communicating information through additional channels and formats. This article discusses an approach to building social media toolbars that can be re-used in your WebSphere Portal 8 themes. You can optionally allow business stakeholders some ability to manage the social media links including; changing the order of links within the toolbar or activating and deactivating individual media links. This solution may also allow you to leverage the features of Portal security and personalization to allow for advanced targeting scenarios.

In the simplest implementation you might implement the html markup for the social media toolbar directly in your theme html or a dynamic content spot using a JSP file. The hard coded solution is extremely simple and may be acceptable if you have no need to for any of the following: - You have no need to share the links across themes. - You don’t need any personalization capabilities or security authorization. - You are comfortable with a development and deployment cycle to manage the links.

However there is an alternative approach that is nearly as simple to implement and allows much greater flexibility and re-use. We want to store the social media bar links in our portal page taxonomy under a hidden page label. When we do this, we can then preserve the same links across themes and allow the theme to read and display the social media links.

The Implementation
First let’s setup some basic custom theme helper code.

In the dynamic content of a your custom theme locate the file includePortalTaglibs.jspf and add the JSTL core taglib.

Next, we want to be able to locate all external links under our hidden portal label. To do this we are going to use a custom uniquename for our label so we can find this label using the Navigation Model SPI. In order to get the navigation node for the uniquename we create a helper function in the helper.jspf called “getNodeByUniqueName”.

Add the import statements highlighted below in the file named “helper.jspf”:

Next, we’ll use a JSP Init method to perform the JNDI lookup of the navigation model home. We also declare the instance members for “navModelHome” and “ctx”.

To complete our helper code we implement our helper method in the JSP static block.

Now we have a helper method to return a NavigationNode for a given uniquename string. Keep in mind this method may throw runtime exceptions in certain scenarios. Later for our case we want to invoke this method in a way that catches any additional exceptions beyond the checked ModelException. Users of this helper method should also check for a null return value.

Next we need a new dynamic content JSP page to render our social media bar.

The code listing is given below:

The above code listing deserves some explanation. In the declarations at the top we include our helper and common tag library includes.

Next we look for two parameters. The first is the uniquename of social media label from Portal - Manage Pages portlet that contains our external links and metadata. The second is an optional parameter for a separator markup we optionally may place between groupings of items in our social media bar. When possible you should try to achieve this using CSS instead of the separator markup parameter.

In the next section we call our helper function “getNodeByUniqueName” in order to get the NavigationNode to iterate over. We conditionally process the lookup of children under the navigation node if the social node is not empty.

We initialize a category variable to track changing from one grouping of social links to the next. This is our indicator to output the separator markup.

Next, we use the Portal EL Beans to get the metadata for each external URL managed by the portal:

  • link.css.classname
  • link.category
  • “Page Icon” property

With this we conditionally output the separator markup, and finally we output a link using the CSS class name from the page properties.

The image icon URL is optional and changes the content of the anchor tag. Depending on how you wish to implement the social media icons. You can use CSS for the anchor tag alone to render the images. If you provide the icon URL the tag is used. Using CSS only may be preferable as you can use glyphicons.

Now that we have a JSP to render our social media toolbar, we can place this into the static resource(s) of our theme as a dynamic content spot. You can register the dynamic content spot as a theme resource environment provider property per – “Creating a dynamic content spot”. For the purpose of this article we’ll simply use the resolver URI directly.

The code listing below shows adding the social media bar dynamic spot to the “theme_en.html” file:

Note the protocol and URI resolves to our JSP in the anchor with relation attribute of “dynamic-content.” We also give the uniquename parameter in the query string.

This is total code needed to implement the solution aside from site specific css.

Portal Page Management
We need to create our Portal Label and add some links. To do this; navigate Portal Administration and select Manage Pages.

Navigate to Content Root > Hidden Pages. Create a new Label under Hidden Pages.

Enter “Social Media Links” under the title, and give the label the same uniquename you used when creating the dynamic content spot.

Next, add a new URL under the Social Media Links label

In this example, I used an image for Page Icon property. If you wish to set page parameters for link.category or link.css.className you must first click Ok to Save the URL. You then return to edit the URL and can modify the page metadata. An example of this appears below:

The screen capture below shows a representative URL’s Page Parameters being set.

Repeat the URL creation process for each link you wish to show in the toolbar.

The Rendered Output
The social links created in Page Management will now be presented in the theme(s) that render the social media bar dynamic content spot.

This is one possible solution to building social media bars in WebSphere Portal 8 Themes. The solution allows a Portal administrator or business user to create new toolbar items (excluding the supporting CSS or images.) The same user can activate and deactivate a link. The links in the toolbar can be reordered. The links could be different for authenticated users based on a user’s identity by using “assign permissions” or by using personalization rule mappings. Most importantly the link data is decoupled from a particular theme and its presentation of the links.

Tim Reilly is a Technology Manager with Prolifics. He has led the implementation of many global projects using IBM WebSphere Portal and has extensive background in design and development of enterprise portals. He specializes in providing Enterprise Java and Portal solutions leveraging WebSphere Portal, Content Management, Tivoli and 3rd party integrations. He has over 10 years of experience with Websphere Portal and is a former Apache Software Foundation committer.