How to add a layout and style to the toolbar

In this article we learn how to inject a new 4 column layout template and an ocean-colored style into the existing toolbar in IBM WebSphere Portal 8.5. The resulting page at the end of this article will look like this:

When you are creating your own theme you have two options when it comes to adding layouts and styles. You can either add your layouts and styles to your existing theme’s layouts.json and styles.json files (which are located in WebDAV in the system sub folder of your theme) or you can use an independent file and inject your new layouts and styles into the system without modifying the existing json files.

For this article we are going to use the latter approach and inject a new layout and a new style. In order to do this we will create a new layout and a new style, create descriptor json files for each of those and add a theme metadata referencing those descriptors.

Layout

1. Create a new folder called demo inside of your theme’s root folder in WebDAV, for instance <WebDAV>/themes/Portal8.5/demo
   Note: The default WebDAV entry point for IBM WebSphere Portal is: http://<host>:10039/wps/mycontenthandler/dav/fs-type1/
   
2. Inside of that folder create a sub folder called 4ColumnEqual and create two files inside of it. An icon.png and a layout.html file. The icon has been attached to this article and can be downloaded by clicking this link. The layout.html file has the following content:
   

   <style type="text/css">
    .wptheme4Col .wpthemeCol {width:220px;}
   </style>
   <div class="hiddenWidgetsDiv">
     <div class="component-container hiddenWidgetsContainer ibmDndRow 
                 wpthemeCol12of12 wpthemeFull" name="ibmHiddenWidgets"></div>
     <div style="clear:both"></div>
   </div>
   <!-- this layout contains 4 equally size columns -->
   <div class="wptheme4Col wpthemeEqual">
     <div class="component-container wpthemeCol wpthemeSecondaryContainer ibmDndColumn
                 wpthemeLeft wpthemeCol3of12 wpthemeNarrow" name="secondary"></div>
     <div class="component-container wpthemeCol wpthemePrimaryContainer ibmDndColumn
                 wpthemeLeft wpthemeCol3of12 wpthemeNarrow" name="ibmMainContainer"></div>
     <div class="component-container wpthemeCol wpthemeTertiaryContainer ibmDndColumn
                 wpthemeLeft wpthemeCol3of12 wpthemeNarrow" name="tertiary"></div>
     <div class="component-container wpthemeCol wpthemeQuaternaryContainer ibmDndColumn
                 wpthemeLeft wpthemeCol3of12 wpthemeNarrow" name="quaternary"></div>
   </div>

   
   Please note that for this article we are using inline styles for demonstrational purposes only. You should create a separate css resource and make it available as module for production. This is described in the last section of this article.
3. Once the layout is created we can proceed to register it with the toolbar so that a business user can select the layout and apply it to any page. To register please create a json file within the previously created demo folder called additionalLayouts.json with the following content:
   

   {
     "items": [{
       "id":"demo_4ColumnEqual",
       "url":ibmCfg.themeConfig.themeWebDAVBaseURI + "demo/4ColumnEqual/",
       "thumbnail":ibmCfg.themeConfig.themeRootURI + "/demo/4ColumnEqual/icon.png",
       "titles": [{
         "value":"4 column equal",
         "lang":"en"
       }],
       "descriptions": [{
         "value":"Layout that contains 4 equally distributed columns",
         "lang":"en"
       }]
     }]
   }

   At this point your demo folder should look like this:
   
4. Lastly, in order for the toolbar to pick up the new layout we need to add a theme metadata. The following xml access script demonstrates how you can add a theme metadata to the Portal 8.5 Theme. To adopt this to your custom theme please replace the unique name ibm.portal.85Theme to your custom theme’s unique name. The last part of the name of the metadata, demoLayout,  should also be adapted and must be unique within your theme.

   <?xml version="1.0" encoding="UTF-8"?>
   <request build="wp85" type="update" version="8.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PortalConfig_8.5.0.xsd">
     <portal action="locate">
       <theme action="update" uniquename="ibm.portal.85Theme">
         <parameter name="ibm.portal.shelf.layout.json.demoLayout" type="string" update="set"><![CDATA[demo/additionalLayouts.json]]></parameter>
       </theme>
     </portal>
   </request>

   Import the above file by using the Import XML portlet which can be found by navigating to Administration > Portal Settings > Import XML.
   At this point your toolbar layout selection should contain the 4 column equal layout like shown below
   
5. We are done!
   You can apply this new layout now on every page and drop portlets into the columns. Below screenshot depicts how this may look like with various portlets on the page:
   

Style

In this section we are adding a style on top of the previously added style. It is going to be very similar in that we need a descriptor file and a directory with the icon and the styles itself.

1. Navigate to the previously created demo folder inside of your theme’s root folder in WebDAV.
2. Inside of that folder create a sub folder called ocean and create two files inside of it. An icon.png and a style file called style.css. The icon has been attached to this article and can be downloaded by clicking this link. The style.css file has also been attached to this article and can be downloaded by clicking this link (Ocean Styles).
3. Once the style is created we can proceed to register it with the toolbar so that a business user can select the style and apply it to any page. To register please create a json file within the previously created demo folder called additionalStyles.json with the following content:
   

   {
     "items": [{
       "url": "demo/ocean/style.css",
       "id":"demo_oceanStyle",
       "thumbnail":ibmCfg.themeConfig.themeRootURI + "/demo/ocean/icon.png",
       "titles": [{
         "value":"Ocean",
         "lang":"en"
       }],
       "descriptions": [{
         "value":"Ocean based color style",
         "lang":"en"
       }]
     }]
   }

   At this point your demo folder should look like this:
   
4. Lastly, in order for the toolbar to pick up the new style we need to add a theme metadata. This is an extension to the previous xml access script. Below I have printed the complete xml access script and highlighted in bold the new line.

   <?xml version="1.0" encoding="UTF-8"?>
   <request build="wp85" type="update" version="8.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PortalConfig_8.5.0.xsd">
     <portal action="locate">
       <theme action="update" uniquename="ibm.portal.85Theme">
         <parameter name="ibm.portal.shelf.style.json.demoStyle" type="string" update="set"><![CDATA[demo/additionalStyles.json]]></parameter>
         <parameter name="ibm.portal.shelf.layout.json.demoLayout" type="string" update="set"><![CDATA[demo/additionalLayouts.json]]></parameter>
       </theme>
     </portal>
   </request>

   Import the above file by using the Import XML portlet which can be found by navigating to Administration > Portal Settings > Import XML.
   At this point your toolbar style selection should contain the ocean style like shown below
   
5. We are done!
   You can apply this new style now on every page. Below screenshot depicts how this may look like:
   

Responsive Features and additional resources

Above layout defines inline styles which works but is not the recommended approach. Furthermore it has no responsive capabilities and looks the same on smartphones and tablet devices. Below link provides a set of styles that will enable the 4 column equal layout with responsive capabilities on smartphones and tablets. Please click the following link to download said file: CSS file that applies responsive capabilities to the 4 column layout

In order to leverage this new css file create your own simple module as described below.

1. Create a new folder named demoLayouts within the WebDAV’s modules folder, for instance <WebDAV>/themes/Portal8.5/modules, and create the following subfolders and files within:
   
   • head (folder)
   • additionalLayouts.css
     This contains the styles for desktop

     .wptheme4Col .wpthemeCol {
       width:220px;
     }

   • smartphone (folder)
   • additionalLayoutsResponsive.css
     Place the downloaded file in this folder (CSS file that applies responsive capabilities to the 4 column layout).
   • tablet (folder)
   • additionalLayoutsResponsive.css
     Place the downloaded file in this folder (CSS file that applies responsive capabilities to the 4 column layout).
   
   After this is done, your WebDAV directory should look like this:
   
2. The new module needs to be added to your profile that you use to render the current page. This is most likely the Deferred profile. Simple add the “demoLayouts” string at the end of the non-deferred section like shown below

   ...
     "wp_sametime_proxy",
     "demoLayouts"
   ],
   "deferredModuleIDs": [
   ...

3. It is very important that you remove the inline style from your layout.html file at this point, otherwise the rendering will not look correct when looking at the page on a mobile device.
   Please note that IBM WebSphere Portal will store the actual layout markup inside of every page and as a side effect even if you take the inline styles out of the layout.html you will not have removed it from the existing pages.
   For the individual page that we created as part of this article you can however switch the layout to another one such as the 1 column layout and switch back to the 4 column equal. This will cause the layout.html to be re-applied on the given page.
4. Before we can test everything you need to invalidate the theme caches by clicking the Administration menu icon in the toolbar. Then, click Portal Analysis > Theme Analyzer > Utilities > Control Center > Invalidate cache.
   
   
5. We are done!
   Below screenshot depicts how the responsive layout looks like on a tablet:
   

Summary

In this article we learned a number of things:

• How to use theme layouts and styles within Portal
• How to inject additional layouts and styles into an existing theme
• How to use responsive features with a module
• How to define a new module using Simple Modules

Stay tuned for our next “How To” article.