Skip to main content
IBM Developer
Sign In | Register dW
IBM Digital Experience Developer
  • Samples
  • Downloads
  • Additional documentation
  • Blog
  • Forum
  • Get Help
  • Events

Contents

  • Additional documentation
    • Tutorials and Labs
      • Lab – Building your Site with IBM Digital Experience
      • Lab – Building your Site with IBM Digital Experience and CTC
    • Themes
      • Adding Bootstrap to a Portal Theme
      • Creating an IBM Digital Experience v8.5 theme from a WordPress theme
      • Moving WebSphere Portal Themes into Watson Content Hub
      • Leveraging the Power of Web Content Manager Within a Portal Theme
      • Portlet scoped theme modules in IBM WebSphere Portal 8.5
      • Debugging cacheability issues with theme resource aggregator requests
      • How to show the site toolbar for administrative users only
      • How to render portlet window actions in a skin
      • How to add a layout and style to the toolbar
      • Displaying dynamic portlet titles in IBM WebSphere Portal 8.5
    • Script Portlet
      • Inter-Portlet Communication in IBM Script Portlet Using Public Render Parameters
      • Using a ReactJS Single Page Application as a Script Portlet
      • Using an Angular (Angular 4) Single Page Application as a Script Portlet
      • Business Process Manager Sample for IBM Script Portlet in WebSphere Portal
      • Using Node.js Build Tools with Script Portlet
      • Using an AngularJS (Angular1) Single Page Application as a Script Portlet
      • Using a Backbone.js Single Page Application as a Script Portlet
      • Accessing Server-Side Data in Script Portlet Using a Web Content Manager JSP Component
      • Script Portlet and Source Code Management across Environments
      • Using Single Page Applications with Script Portlet
      • Script Portlet Development Best Practices
      • Using Command Line Push to Deploy Script Portlet Applications
      • Script Portlet Support for External Editors
    • Responsive, Mobile, and Worklight
      • Integrating WebSphere Portal 8.0.0.1 and IBM Worklight 6.2
      • Providing Worklight to Windows Phone hybrid applications from WebSphere Portal
      • Worklight integration samples
    • Administration
      • A Guide to Troubleshooting Portal Performance Issues
      • A Step-By-Step Guide to performing a silent installation of WebSphere Portal 9.0
      • A Step-By-Step Guide to performing a standalone WebSphere Portal 9.0 installation
      • Administering IBM WebSphere Portal 9.0: A comprehensive workshop
      • DX Performance Testing Substitution Patterns for Reusable Test Suites
      • General Guidance For DX Performance Testing
      • IBM Digital Experience on Docker Containers
      • Installing WebSphere Portal V9 on Portal 8.5 CF13
      • Step by Step Guide, Portal 8.5 CF13 Upgrade
      • WebSphere Portal 8.5 and 9 Log maintenance best practices
      • WebSphere Portal 9.0 Step-by-Step Cluster Guide
      • WebSphere Portal Migration Planning Guide
      • Hints and Tips for Implementing a Search Crawler with the WCM Seedlist
      • WebSphere Portal 8.5 Step-by-Step Cluster Guide
      • Setting up a Portal Cloned Farm Configuration
      • WebSphere Portal Migration from V6.1 to V8.5
      • Step by step guide to implement SAML 2.0 for Portal 8.5
      • Administering IBM WebSphere Portal 8.5: A comprehensive workshop
    • Web Content
      • Creating Maps with Google Static API and IBM Web Content Manager
      • Moving Web Content Management Content to Watson Content Hub
      • Programmatically Displaying IBM Web Content Manager (WCM) Content
    • Application Development
      • PAA file Creation Best Practices
      • Display Spinning Wheel in a WEF Portlet for File Download
      • Building JSR-286 Portlets Using AngularJS and IBM Web Experience Factory
      • Portal Application Development Tools: Overview and Considerations for Selecting Tool
    • Integration
      • Domino Database integration with IBM Digital Data Connector
      • Google OpenID Connect with IBM Digital Experience
      • Watson Content Hub Integration into Digital Experience version 9
      • Integrating CRM into IBM WebSphere Portal with Digital Data Connector (DDC)
      • IBM WebSphere Portal and Bluemix Integration
  • Product Documentation Resources

How to add a layout and style to the toolbar

Stephan Hesmer / July 14, 2014 / 4 comments

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:
Page with ocean style


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:
    Demo Folder View 1
  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
    Layout Demo Toolbar View
  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:
    Page with 4column layout

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:
    Demo Folder View 2
  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
    Style Demo Toolbar View
  5. We are done!
    You can apply this new style now on every page. Below screenshot depicts how this may look like:
    Page with ocean style

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:
    Demo Folder View 3
  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:
    Responsive Tablet Layout View

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.

Tags: 8.5 / example / layout / layouts / responsive / responsive design / sample / style / styles / theme / themes

4 Comments

  1. Michele Buccarello says:
    July 15, 2014 at 9:44 am

    Thanks for this great example, on my company we work to integrate bootstrap with a module, there is a way to integrate layout and skins via a Theme Module?

    Reply
    • Stephan Hesmer says:
      July 15, 2014 at 1:10 pm

      Yes there is and we will shortly release something about this. Stay tuned!

      Reply
      • Shine.Ravindra says:
        October 16, 2014 at 12:12 am

        Stephan, thanks for this nice tutorial. I’m using Bootstrap for creating HTML prototypes. Can I simply replace the ‘wptheme4Col’ class with corresponding bootstrap class ‘col-sm-3’ and if including bootstrap.css, it should work right? or Do I have to add anything more? Thanks

        Reply
  2. Karim says:
    August 22, 2016 at 6:12 am

    Stephan, Very thanks for this great tutorial.

    Keep forward!

    Reply

Leave a comment

Click here to cancel reply.
Tell us who you are

Follow us on Twitter RSS Feed
  • Contact us
  • Report Abuse
  • Terms of Use
  • Third Party Notice
  • IBM Privacy
IBM