Moving WebSphere Portal Themes into Watson Content Hub

Sarah Hall WebSphere Portal Lab Services (SEAL) Team | IBM

01/08/2018

1

Contents Contents ................................................................................................................................................................ 1

Purpose ................................................................................................................................................................. 2

Creating a Simple Theme in WebSphere Portal .................................................................................................... 3

Creating a Simple Theme .................................................................................................................................. 3

Accessing Theme Resources ............................................................................................................................. 5

Modifying the WCH Oslo Template ...................................................................................................................... 7

Downloading and installing the Oslo Template ................................................................................................ 7

Start and Run the Oslo Template ...................................................................................................................... 8

Modifying the Template ................................................................................................................................. 12

The ASimpleTheme in WebSphere Portal ................................................................................................... 12

The Oslo Template Structure ...................................................................................................................... 17

Header ........................................................................................................................................................ 19

Footer .......................................................................................................................................................... 23

Javascript .................................................................................................................................................... 26

New Site .............................................................................................................................................................. 32

Pushing the new site to WCH ............................................................................................................................. 33

Summary ............................................................................................................................................................. 34

2

Purpose

Companies using Digital Experience (WebSphere Portal) may also want to use, or move to, Watson Content Hub (WCH) and use the new site functionality now existing in the product. In order to make this conversion, they need to understand how to move their existing Portal themes to WCH. In late 2017 WCH delivered function that allows users to create web sites. A sample “Oslo” site is automatically deployed to WCH Standard Edition tenants. This article details how to change the sample “Oslo” site to look like the Portal V8.5/9 out-of-the-box simple theme. This article was created in December of 2017. It will be updated as updates to Web Content Management and Watson Content Hub are changed.

3

Creating a Simple Theme in WebSphere Portal

Creating a simple theme is easy in WebSphere Portal V8.5/9. The following sections show how to create a simple theme and detail where the relevant resources are stored. Once the theme is created, the subsequent sections will show how to move these resources to WCH.

Creating a Simple Theme

For Administration users, the pulldown menu in the toolbar allows users to access the Theme Development tools.

Once “Theme Development” is selected, the user will see the Theme Manager and the “Create Theme” button on the right can be selected to create a new theme based on the Portal 8.5 OOB theme.

4

The Create Theme dialog allows users to name the theme. In this case, the theme is named “ASimpleTheme”. The template selected in this case is “Simple”, but it could be “Portal 8.5”. The simple theme is a “skinnier” theme that does not contain all of the resources that the Portal 8.5 theme includes. Customers building minimal themes would want to select “Simple” since it will download less resources.

Once the “Create” button is selected, the new theme will appear in the list of themes.

5

Accessing Theme Resources

Creation of the simple theme adds a directory in WebDAV for the theme static resources (CSS, HTML and Javascript). This directory can be accessed using a WebDAV client or with the new DXDashboard (a.k.a the New Web Developer Toolkit for IBM Digital Experience). This tool has a GUI interface and can be used to extract the theme static resources to your local server. The DXDashboard tool is available at this link:

https://developer.ibm.com/digexp/blog/2015/10/01/new-web-developer-toolkit-for-ibm-digital-experience/

Below AnyClient (a downloadable WebDAV client) shows how the theme resources can be accessed at:

/fs-type1/themes/

6

The Manage Pages portlet in the WebSphere Portal administration can be used to create a new page based on the new theme.

When the new page is rendered in WebSphere portal, it looks like this:

7

Modifying the WCH Oslo Template

The following sections detail how to move the static resources in the ASimpleTheme theme from WebSphere Portal to WCH to make the WCH site banner, navigation and footer look like the simple theme. For complete instructions for the application and the tools, see the documentation provided on GitHub. However, this article will give an overview of the basics for starting and running the application in a browser so that the site can be previewed during development of the theme.

Downloading and installing the Oslo Template The Oslo template can be obtained from GitHub at this link:

https://github.com/ibm-wch/wch-site-application

8

Download and unzip the the wch-site-application-master.zip file or clone the repository.

Run

npm install

from a command shell to install the application.

Start and Run the Oslo Template

Download and unzip the wchtools-cli-master.zip or clone the repository of the latest IBM Watson Content Hub Developer Tools. These tools provide a command line interface (CLI) that can be used to access WCH. The latest developer tools can be obtained from GitHub at this link:

https://github.com/ibm-wch/wchtools-cli

Follow the install directions on GitHub to install or update the tools.

9

The Oslo template depends on content stored in WCH to render the site so the tenant information must be made known to the application. The tenant information can be obtained in WCH by selecting “Hub information” from the dropdown under the user name.

10

Edit the src/app/Constants.ts file in the application to add the WCH tenant information.

Run

npm start

from a command shell to start the application. After the application starts the site can be

accessed from a browser at:

http://localhost:4200/

11

The Oslo template will look like this before any changes are made:

Header

Footer

12

Modifying the Template

The ASimpleTheme Structure in WebSphere Portal

In order to modify the Oslo template it is necessary to understand the structure of the WebSphere Portal ASimpleTheme. For more in depth knowledge on WebSphere Portal themes, see this link: https://www-10.lotus.com/ldd/portalwiki.nsf/xpViewCategories.xsp?lookupName=Developing%20Themes%20for%20WebSphere%20Portal%208.5

This article will attempt to give a high level description of where the important theme resources are located. Some or all of the theme resources may be needed when a theme is recreated using the Oslo template.

The simple theme static resources file structure looks like this:

13

Theme.html

The theme.html file contains all of the markup for the page including the <!DOCTYPE html> element and the header, content and footer. A sample of the ASimpleTheme theme.html file looks like:

The important point to note is that the markup for the entire page is defined by the theme.html file. The theme.html file contains dynamic content spots that cause JSPs to be run on the server to generate markup that is injected into the page, but all of the markup for the page is referenced from this file. Some or all of this markup may be needed in the Oslo template.

14

CSS and Javascript

The CSS and Javascript for the theme are included in the theme either directly via a <link> or <script> element included in the theme.html file or by including a module in the theme profile.

The theme profile includes modules which may identify CSS or Javascript files that need to be included in the Oslo template. The diagram below details how the theme profile works with the theme modules.

For more information on WebSphere Portal themes and modularization, see this link:

https://www-10.lotus.com/ldd/portalwiki.nsf/xpViewCategories.xsp?lookupName=Developing%20Themes%20for%20WebSphere%20Portal%208.5

15

Determining what the theme modules reference is easy using the WebSphere Portal Theme Analyzer in the WebSphere Portal Administration console. Below is an example of one of the modules in the simple theme.

In the example below the st_compressed_navbar module points to a CSS and a Javascript file which will be loaded when the simple theme is rendered.

16

Theme CSS and Javascript resources which are not modularized can also be located in the static theme directories. In this example, the banner.css.uncompressed.css file will be moved to WCH. This file is located in the ASimpleTheme->css->default directory.

17

The Oslo Template Structure in WCH

The Oslo template is an Angular 4 application. The start of the markup (i.e. the <!doctype html> element) for the site is located in the wch-site-application-master/src/index.html file. When the application is generated, the wch-site-application-master/src/app/app.component.html file pulls in the Oslo template header and footer which are divided into Angular components.

18

Here is the file structure in the Oslo template application for the header and footer components:

19

Header

The wchHeader component has three key files:

wch-header.html HTML5 markup for the header

wch-header.scss CSS for the header

wchHeader.component.ts Typescript file that defines how and what files will be loaded to support the component and includes Javascript.

The wch-header.html file loads the logo and the navigation for the header. It is synonymous to the <header> element part of the theme.html file. The wch-header.html file has to be changed to include markup from the theme.html file. Since the navigation part of the markup is unique to WCH, that part of the markup remains the same.

20

The wchHeader.html file looks like this after the markup from the theme.html file is moved to this file.

The markup refers to CSS classes (“stBanner”, for example) that are included in the banner.css.uncompressed.css file in the simple theme. For that reason, this file will need to be included in the wchHeader component. The details on how to include the banner.css.uncompressed.css file in the component will be covered after the other CSS changes are explained.

21

Angular 4 includes a responsive front-end framework called Foundation 6. This framework provides overall styling and Javascript for the site. For this example, some of the foundation CSS had to be overwritten. These overrides were included in a new file called wps-header.scss.

22

CSS already included in the wch-header.scss file needs to be changed for colors, etc. in the header.

In order to include the new files, the ”@Component” section of the wchHeader.components.ts file needs to be changed to include the new files along with the wch-header.scss file.

23

Footer

The wchFooter component also has three key files:

wch-footer.html HTML5 markup for the footer

wch-footer.scss CSS for the footer

wchFooter.component.ts Typescript file that defines how and what files will be loaded to support the component and includes Javascript.

The wch-footer.html file contains markup synonymous to the <footer> element part of the theme.html file. The wch-footer.html file has to be changed to include markup from the theme.html file.

24

The wchFooter.html file in this example looks like this and reflects links related to WebSphere Portal that are included in the simple theme:

The markup refers to CSS directives (“stFooter”, for example) that is included in the footer.css.uncompressed.css file in the simple theme. For that reason, this file will need to be included in the wchFooter component.

25

In order to include the new file, the “@Component” section of the wchFooter.components.ts file needs to be changed to include the new files.

26

Javascript

All custom themes include Javascript. Because the Oslo template is an Angular 4 application, only Typescript files are supported (files with a filetype of .ts). Any files moved from the WebSphere Portal theme to WCH must be converted to Typescript. However, the same function may be implemented differently in the Angular application. The inclusion of the “Bee” image in the theme banner is an example of how both products accomplish the same thing in a slightly different way.

“Bee” Example – WebSphere Portal

The ASimpleTheme contains a “bee” icon in the banner.

27

In the WebSphere Portal theme, the “bee” icon is obtained by running Javascript (see below) that loads an SVG file stored in the ASimpleTheme directories. The SVG sprite contains the “bee” image along with several other images. Typescript files must be updated in WCH to include the image in the Angular application, but the Javascript implementing the XMLHttpRequest does not have to run.

After the Javascript runs in WebSphere Portal, the DOM update looks like this:

28

Once the DOM is updated, the image can be referenced using this markup in the theme.html file.

29

“Bee” Example – WCH

Getting the image to display in the WCH template is accomplished in a slightly different way. The first step is to put the SVG file in the appropriate directory in the application.

30

The wchHeader.component.ts file is updated to “require” the SVG file. An “icon” object is also created that references the “bee” image in the sprite.SVG.

31

When the “require” runs, the DOM is updated to include the SVG.

The wch-header.html file is then updated with the following markup that includes the image.

32

New Site When all of the changes described above are included in the Oslo template, the new site looks like this: Header

Footer

33

Pushing the new site to WCH

Run

npm run build-deploy

from a command shell to push the application to the WCH tenant.

Look for the password prompt during the deploy.

Once the npm command runs, WCH will look like this:

34

Summary

The steps presented in this document demonstrate that any custom theme can be moved from WebSphere Portal to WCH. The degree of difficulty depends on the complexity of the theme. However, WCH and the Oslo template provide a lot of flexibility in how the theme components and their underlying functions can be surfaced in the new site.