Saturday, November 29, 2014

PeopleTools 8.54 - Branding - Part 2

This is a continuation of my previous post on my experiments with PeopleTools 8.54 Branding.

The general theme I would like to continue is to explore how we can leverage the new features and configuration provided in PeopleTools 8.54. The idea is to see how far we can go without having to use App Designer (using just the online configuration).

Now that we learnt how we can easily change the logo of the application in Part 1, let us see how we can further brand the application.

Changing the background color of the Branding Header:



We can see from the screenshot that the background color for the branding header div (pthdr2container) is actually an image PT_HEADERBG_CSS.JPG which is repeated to cover the background entire div (repeat-x).

Note: If you are wondering how we can see html and css generated on the browser as in the screenshot above, I am using Firebug which is a Web Developer add-on for FireFox. Most browsers have Web Developer support similar to Firebug. It is highly recommended to use such tools to understand the html, javascript and css that are being used on a page.

PT_HEADERBG_CSS image for reference:






Let us see how we can override this delivered background image:

- Upload custom background image:

PeopleTools > Portal > Branding > Branding Objects (Images Tab)

Note: In this case, I am using a background image that is of similar height and width as the delivered PT_HEADERBG_CSS image because my custom branding header div (pthdr2container) is of the same height as the delivered div. If the custom branding header div is of a different height then please be sure to create your custom background image of similar height to cover the entire div.


- Create custom style to override the background on the branding header div (pthr2container):

PeopleTools > Portal > Branding > Branding Objects (Style Sheet Tab)


We can see how a new style was added and how it uses the id selector (#) and class selector (.) to specifically target the element (div) with id = "pthdr2container" and class = "pthdr2container". This style is referencing the custom background image CSK_HEADERBG_CSS.

- Include custom style sheet definition on the Branding System Options Page:

PeopleTools > Portal > Branding System Options


This would ensure that our new style sheet is also loaded while rendering the page.

- Test changes:

Recommendations if you are experiencing caching issues:
  1. Clear local browser cache.
  2. Shutdown, purge cache and reboot the web server(s).



Changing the background color of the Navigation Drop-Down Menu:



We can see in the screenshot that the background color for the Navigation Drop-Down Menu is coming from the image PT_BREADCRUMB_CSS3. The nav element (pthnavcontainer) is enclosed within the dropdown menu div element (ptdropdownmenu).

PT_BREADCRUMB_CSS3 image for reference:





Let us see how we can override this delivered background image:

- Upload custom background image:

PeopleTools > Portal > Branding > Branding Objects (Images Tab)

Note:Again, in my case I am using a custom background image that is of the same height as PT_BREADCRUMB_CSS3.


- Create custom style to override the background on the Navigation Drop-Down Menu (nav element):

PeopleTools > Portal > Branding > Branding Objects (Style Sheet Tab)


We can see in the screenshot that we are using the existing style sheet (CSK_BR_GEN) to add the new style. The new style is using the id selector (#) and the descendant selector (e.g.: X Y, where Y is a descendant of X) to target the element (nav) with id = "pthnavcontainer" and is a descendant of element with id = "ptdropdownmenu". This style is referencing the custom background image CSK_BREADCRUMB_CSS3.

Note: As we already have the style sheet CSK_BR_GEN added to the 'Branding System Options', we can directly proceed to test these changes.

- Test changes:

Recommendations if you are experiencing caching issues:
  1. Clear local browser cache.
  2. Shutdown, purge cache and reboot the web server(s).





Sticking with our theme, we have now implemented a custom logo, custom branding header background image and custom navigation drop-down menu background image by just using the PeopleTools Branding features and configuration available online.

Changing the font color of Branding Header System Links (Home, Worklist, ..., Sign out):



We can see in the screenshot that the System Links on the Branding Header is using the style class of PSHYPERLINK (color: #004b91). As most of you know, this style class is widely used across the application.

Let us see how we can use css to specifically target the required elements and override the font color:

- Create custom style to override the font color of the Branding Header System Links:


We can see in the screenshot that we are using the existing style sheet (CSK_BR_GEN) to add the new style. The new style is using the id selector (#), class selector (.) and the descendant selector (e.g.: X Y, where Y is a descendant of X). This style would target all elements with class = "PSHYPERLINK" and are descendants of element with id = "pthdr2syslinks".

- Test changes:

Recommendations if you are experiencing caching issues:
  1. Clear local browser cache.
  2. Shutdown, purge cache and reboot the web server(s).



Changing the font color of the Navigation Drop-Down Menu:



We can see from the screenshot that the font color (#284562) of the Navigation Drop-Down Menu is using the style .pthnav a (all anchor elements which are descendants of element with class = "pthnav").

Let us see how we can override this delivered font color:

- Create custom style to override the font color of the Navigation Drop-Down Menu:


We can see in the screenshot that we are using the existing style sheet (CSK_BR_GEN) to add the new style. The new style is intended to specifically target all anchor elements (a) that have a descendant hierarchy of #ptdropdownmenu #pthnavcontainer .pthnav. The descendant hierarchy would target all anchor tags that are descendants of elements with class = "pthnav" which are in turn descendants of elements with id = "pthnavcontainer" which are in turn descendants of elements with id = "ptdropdownmenu".

- Test changes:

Recommendations if you are experiencing caching issues:
  1. Clear local browser cache.
  2. Shutdown, purge cache and reboot the web server(s).



Let us now look at how we can further branding our application with some more common branding requirements.

Note: I am not a big fan of the bright red font color on the Branding Header (it was just used as an example) and besides the orange/yellow and delivered blue go well with the CSK team colors. So I will be reverting the font color changes which I just made for future examples to make it a bit easier on the eyes.

Adding a Hyperlink to the Branding Logo:



Let us assume we want our logo to image to link to another website.

- Create URL Definition to store the hyperlink address:

PeopleTools > Utilities > Administration > URLs


- Modify existing style for the Branding Logo:


CSK_HDR_LOGO was created in example provided in Part 1. We can see from the screenshot that the style has been modified to comment out the content attribute.

- Modify logo element in the custom Header Layout Definition:

PeopleTools > Portal > Branding > Define Headers and Footers

-> Additional Options for leaf cskhdrlogo


We have replaced the existing Static HTML (which was a non-breaking space  ) with an anchor element referencing the URL Definition (href), Image Object (img element) and URL Definition Description (title).

- Test changes:

Recommendations if you are experiencing caching issues:
  1. Clear local browser cache.
  2. Shutdown, purge cache and reboot the web server(s).


Moving Branding Elements using CSS:


Most organizations would like to print the name of the database (e.g.: DEV, TST, UAT, etc) on the branding header for test environments. Let us move the ptgreetingmessage div to make way for the Database name to be printed on the branding header. We will use css to move the ptgreetingmessage div to the bottom right hand corner of the header.


Create custom style to override the alignment and location of the ptgreetingmessage div:


Modify the ptgreetingmessage (div) leaf on Header Layout for logical ordering:


Test changes:


 

Adding Database Name on the Branding Header:


Now that we moved the ptgreetingmessage div and made way for displaying the database name, let us use custom javascript to achieve this requirement. We could directly use the %dbname meta-html in a div to display the database name but we will be using a javascript to write some logic to only display database name in non-PROD environments.

- Create custom style for the database name:


This style is cloned from the delivered greeting style class to replicate the font and location.

- Add new leaf to represent the database name element on the Branding Header Layout:




We added a new child element under the pthdr2container. This element is a static javascript object (cskdbname) which is ordered after the cskhdrlogo element.

Note; In the javascript, replace PROD_DBNAME with the actual name of the Production Database. The javascript is intended to not display the name of the database for Production.

- Test changes:

Recommendations if you are experiencing caching issues:
  1. Clear local browser cache.
  2. Shutdown, purge cache and reboot the web server(s).



I found that adding static javascript to the Header Layout breaks the "Preview" functionality on the page. Here are the results of clicking/expanding the "Preview" functionality on the "Define Headers and Footers" page when it contains a static javascript object.



The reason this occurred is because the document.write in the javascript is overwriting the page. Let us replace the static javascript with a javascript object to avoid the issue with the preview.



Result:


Note: document.write is not generally recommended. In this case, we got away with it because it is being used at the header level and does not interrupt the page that is loaded during runtime.

Although document.write works in our case, to comply with best practice let us replace the document.write with Document Object Model (DOM).

Modified JavaScript (CSK_DBNAME):

if ("%dbname" !== "PROD_DBNAME")
{
   // document.write("<div id='cskdbname' class='cskdbname'><p>%dbname</p></div>");

   // create div for dbname
   var dbname = document.createElement("div");

   // set attributes and innerHTML
   dbname.setAttribute("id","cskdbname");
   dbname.setAttribute("class","cskdbname");
   dbname.innerHTML = "<p>%dbname</p>";

   // insert dbname div after the cskhdrlogo div
   var logo = document.getElementById("cskhdrlogo");
   document.getElementById("pthdr2container").insertBefore(dbname, logo.nextSibling);

}

We have commented out the document.write and replaced with DOM to create the DIV element, set attributes, set innerHTML and finally added the div to the pthdr2container element. We are using the logo.nextSibling as a logical selector for the next child of pthdr2container after cskhdrlogo because we do not know if ptsearchbox would be displayed at runtime (e.g.: in cases where SES is turned off).


So far we have seen some of the more common branding requirements and we were able to achieve all of them by just using the online configuration pages. I hope this is definitely something everyone would be excited about!

In the next part (as time permits), I would like to look into some of the more advanced branding requirements like using a custom image on the PeopleTools Timeout message (which contains the Oracle Logo), displaying a more dynamic, user specific greeting message, adding Google Analytics javascript and migrating the branding modifications.

As always, I would appreciate any feedback/improvements that could be made to the content of this post.

Custom CSS for Reference:

Object Name: CSK_HDR_LOGO


Object Name: CSK_BR_GEN

Sunday, November 23, 2014

PeopleTools 8.54 - Branding - Part 1

PeopleTools 8.54 is here! Well it has been out for the past few months. I finally managed to get a VM Instance up and running.

I have been working on Branding PeopleSoft Applications starting from 8.48 and was naturally interested in finding out the new configuration, functionality and features that 8.54 has to offer. As you all know, Branding in PeopleTools has slowly evolved with new styles like SWAN and TANGERINE. I was interested in exploring how it has changed with 8.54 and what it might take to do some custom Branding that most organizations would like to perform at a very basic level.

This post (followed by a few more parts as time permits) is intended to detail my findings while branding a PeopleSoft Application on PeopleTools 8.54.

First thing I noticed with PeopleTools 8.54 is that the PeopleTools Options Page does not allow us to update the Branding App Package and Default Style Sheet any longer.



Notice how the Default Style Sheet, Branding Application Package and Application Class are all disabled? So where do we change this now in 8.54?

PeopleTools > Portal > Branding > Branding System Options



The original branding options (that we are used to from pre 8.54 tools) can be found on this page. And technically we could just customize these options (Default Style Sheet, Package Name and Application Package) similar to prior PeopleTools versions and be done with it from a branding point of view. But let us explore the other configuration items that are available online as part of PeopleTools 8.54.

The Default Branding Theme appears to be at the highest level amongst all configurable options on the Branding System Options page. So let us start by creating a custom Branding Theme similar to DEFAULT_THEME_TANGERINE.

PeopleTools > Portal > Branding > Assemble Themes
- Search for DEFAULT_THEME_TANGERINE.
- Save As a custom theme.
- In my example, I am calling my custom theme CSK_THEME_TANGERINE. CSK is my favorite cricket team in the IPL!!



If we go back to the Branding System Options then we would now see the new custom theme in the drop down for Default Branding Theme.



Let us go ahead and select this new theme as the Default Branding Theme  and save the Branding System Options (so we can customize it accordingly).

Let us now start customizing our Branding Theme (custom copy) step by step.

First item on everyone's list would be to get rid of the Oracle logo and use a custom logo. In previous PeopleTools versions, we would have uploaded our custom logo image using Application Designer and then modified the style sheet (e.g.: pthdr2logoswan) that references the logo image accordingly.

With PeopleTools 8.54, we can upload our custom logo (image) and style sheet objects using the following page:
PeopleTools > Portal > Branding > Branding Objects

I uploaded my custom logo and custom stylesheet that I would like to use for overriding the delivered style.

Image Screenshot:



For simplicity sake, I resized my custom logo to the same height (55) as the delivered Oracle logo.

Style Sheet Screenshot:



Notice that I have referenced the custom logo in my style class as follows:
content: url(%Image(CSK_LOGO));

Note: Objects uploaded via the Branding Objects page would be created as PeopleTools managed objects in the database meaning that we can view and migrate them using App Designer.



Now that we have the necessary objects for customizing the logo, let us see how we can apply them to our custom branding theme.

We will perform this task by using the Assemble Themes page.

PeopleTools > Portal > Branding > Assemble Themes
- Search for our custom theme (CSK_THEME_TANGERINE)



We can see that on this page we can assemble a theme by associating several configurable items most notably the Homepage Header and Footer. As the custom theme is still a copy of the delivered theme, it is referencing the delivered Homepage Header and Footer properties.

Let us create a custom Homepage Header and then associate it with the custom Theme.

PeopleTools > Portal > Branding > Define Headers and Footers



On this page we can see that each of the DIV elements on the header are represented in a tree structure. Here a branch/folder represents a logical container and the leaves represent the DIV elements.

Tree Structure:



Corresponding DIV elements:



Other notable features on the Define Headers and Footers page are the Preview and Style Definitions Options. The Preview option can be used to visually identify the location of each of the folders/containers and leaves in the tree. The Style Definition is available to enter any additional free form style class definitions.






Let us use this delivered Header definition (DEFAULT_HEADER_TANGERINE) to 'Save As' a custom Header (CSK_HEADER_TANGERINE).

On the custom Header definition (CSK_HEADER_TANGERINE) let us delete the pthdr2logoswan element under pthdr2container (we will be replacing this with our custom DIV element).



Now let us add a new child element under pthdr2container as follows:









Note:
- Make sure the order of the new element is '01 - First'.
- The properties and attributes of this DIV element (cskhdrlogo) were cloned from pthdr2logoswan.

Our custom header is now ready with the updated logo:



Let us now go back to 'Assemble Themes' and update our custom Theme (CSK_THEME_TANGERINE) to reference our custom Homepage Header definition (CSK_HEADER_TANGERINE):



Last but not the least, we will update the 'Branding System Options' to add our custom style sheet object:



Now we are ready to test our changes.

Note: Please shutdown, purge cache and reboot your web server before continuing to test.

Test Screenshots:





Just like that we were able to apply a custom logo to the Application on PeopleTools 8.54:
- Without any customizations.
- Without using Application Designer (completely configurable).

In the next part, I would like to experiment with customizing the background color and the font color of the Drop Down Menu (ptdropdownmenu) and the Header Container (pthdr2container). Stay tuned!





Note:
- This post is based on my recent experiments with PeopleTools 8.54 and there could be more efficient ways of doing the same. I welcome all feedback and suggestions and would be more than happy to update this post if any improvements could be made. Again, the intent of this post is to create a quick reference/starter guide for anyone who wants to brand PeopleTool 8.54+ applications.
- This exercise was done based on HCM 9.2 PUM Image 8 (PeopleTools 8.54.01).
- If you find the images are small for viewing then just click on them to view in full size.

Updated related branding articles list on April 21th, 2017:

Index of blog posts on PeopleTools Branding:

Customizing DEFAULT_THEME_TANGERINE Theme (continuation of this post):
PeopleTools 8.54 Branding - Part 2
PeopleTools 8.54 Branding - Part 3

Customizing DEFAULT_THEME_TANGERINE_ALT Theme: 
PeopleTools 8.54+ Branding - Part 4A
PeopleTools 8.54+ Branding - Part 4B
PeopleTools 8.54+ Branding - Part 4C
PeopleTools 8.54+ Branding - Part 4D
PeopleTools 8.54+ Branding - Part 4E

PeopleTools Fluid Branding:
PeopleTools 8.54+ Branding - Part 5A
PeopleTools 8.54+ Branding - Part 5B
PeopleTools 8.54+ Branding - Part 5C
PeopleTools 8.54+ Branding - Part 5D

PeopleTools 8.55.x Branding:
Part I - What has changed?
Part II
Part III - Custom Macros and More

PeopleTools 8.55.x - Using Oracle JET:
Part 1
Part 2
Part 3
Part 4

JavaScript Injection Framework:
Global JS Injection Framework

Miscellaneous Topics:
Component Branding
PeopleTools 8.54 Branding Objects - Migration Issue and Workaround
Branding Header Definition - Steps to add external link to System Header Links (Open in New Window)
PeopleTools 8.54+ FavIcon for Classic
PeopleTools 8.54+ Role Based Theme Assignment/Override
Using ACE Editor for Online Branding Objects (HTML, JavaScript and Style Sheets)
PeopleTools 8.55 - Fluid UI - Drop-Down Menu/Breadcrumb Navigation vs NavBar/Navigator Conundrum
Fluid UI - New Window Feature - Workaround
Using Different Branding Themes for Different Portals