PeopleTools 8.54+ - Branding - Part 5B - Fluid Branding (Continued)

Before I start this post, I must apologize for the delay. This post has been on my "to do" list for a very long time but unfortunately other priorities had pushed it back. I finally managed to find time to go over some of the additional ("more advanced") topics that I wanted to cover on Fluid Branding continuing on my previous post Part 5A (using HCM 9.2 PUM Image 12 - PeopleTools 8.54.08).

It is common knowledge by now that there are several new configurable branding capabilities coming our way in PeopleTools 8.55 - particularly for Fluid. I learnt from various presentations at Oracle OpenWorld 2015 that moving forward - starting from PeopleTools 8.55 - there will be only one Branding (or in other words navigation experience) and it would be Fluid based. With that said, I still feel that this post would be useful/relevant for several folks who are currently on PeopleTools 8.54 or planning to upgrade to PeopleTools 8.54. Given that PeopleTools 8.55 has an expected GA perhaps by end of this year or early next year, it would still be a while before everyone gets in on the uptake!

Before I dive deeper, I want to share couple of topics (utilities) which will help us with some of the more advanced branding requirements.

Global JavaScript Injection Bootstrap for Fluid UI:

In my previous branding posts, we saw how we could inject custom style sheet overrides for Fluid UI using the online configuration options available in PeopleTools 8.54 (Assemble Themes - Global Override Style Sheet - follow the link for more details). This online configuration provides a mechanism to easily override delivered styles without any customizations.

But one of the major let downs with Fluid in 8.54 (at least from my perspective) is the fact that there is no way to inject javascript globally using a configuration (similar to style sheets). If we recall from my previous posts, we used the Branding System Options to inject Google Analytics javascript globally across the application for classic components (follow the link for more details). Once again, this online configuration ensures that the listed javascripts are injected in all components without any need for customizations. This helps us to avoid some of the hacks we used in the past for such injection e.g.: customizing the delivered javascript objects (PT_COMMON, PT_PAGESCRIPT, etc.). But unfortunately, the javascripts listed under 'Branding System Options' are not getting injected into the Fluid UI components.

Another disappointment for me (with regards to Fluid in PeopleTools 8.54) was that the jQuery and jQuery UI javascripts that were delivered for classic (injected globally as part of the Branding Header Definition - refer screenshot below) are NOT part of any of the Fluid UI pages/components. This is exasperated by the fact that we cannot really inject our custom javascript objects globally into Fluid!

The ability to inject javascript objects is very important for performing some of the more advanced branding tasks (which should be reasonably clear from the my preceding introduction and examples). With that in mind, I wanted to create my own framework (or bootstrap if you will) to inject custom javascript objects into Fluid UI pages. I am sure there are several ways to "skin the cat" but here are the principles or drivers for my approach:

- Should be least intrusive from a customization point of view. That is to customize the least amount of objects.
- Should be highly configurable. That is to build a bootstrap configuration that allows us the flexibility to dynamically add/remove javascripts objects online (on the fly) without repeatedly customizing.

Note: I ended up adding one line of custom code to a delivered PeopleCode object. Other than that, this framework is entirely configurable online (using the Branding Objects page).

Step 1: Create a custom javascript object

Navigation: Main Menu > PeopleTools > Portal > Branding > Branding Objects (JavaScript Tab)

Note: This javascript object needs to be added online so that it provides a configuration to inject additional javascript objects.

Let us create CSK_FL_BOOTSTRAP_JS as shown in the screenshot below. I will explain the placeholder javascript later as we start injecting other javascripts (using this javascript as a configuration).

Placeholder JavaScript Code - Updated on 20160403:

Updated on 20160403: I found a better way to dynamically retrieve the site name using the delivered getSiteName function (part of PT_COMMON javascript object) which seems to be a lot more efficient than my previous approach.

// This section was commented on 20160403
// Conditional logic for site name which might vary based on current DB instance;
// var dbname = String('%dbname').toUpperCase();
// if (dbname == "HCM92012")
// {
//   var site = "ps";  
// }// Repeat preceding logic for other instances (DEV, TEST, QA & PROD);
// This section was commented on 20160403

// This line was added on 20160403
// Use delivered getSiteName function for dynamically retrieving the site name for different environments.
var site = getSiteName();
 
// -- NOT REQUIRED (20160403) -- Repeat preceding logic for other instances (DEV, TEST, QA & PROD);
// E.g.:
// if (dbname == "HCMDEV")
// {
//    var site = "psdev";  
// }

// Inject javascript(s);

Step 2: Add custom code to PT_HEADERPAGE.Activate (Page Activate PeopleCode)

PT_HEADERPAGE is a header page that is part of all Fluid UI components and is mainly used for navigation purposes. We will be adding a line of code to inject our bootstrap javascript using peoplecode.

Custom PeopleCode:

/* CSK Custom Javascript Bootstrap for Fluid - Start */
AddJavaScript(HTML.CSK_FL_BOOTSTRAP_JS);
/* CSK Custom Javascript Bootstrap for Fluid - End */

Step 3: Inject Javascript

Now that we have our custom javascript object (CSK_FL_BOOTSTRAP_JS) injected into all Fluid UI components, we can use that as a configuration to further inject other javascript objects.

Custom JavaScript (CSK_FL_BOOTSTRAP_JS):

// This section was commented on 20160403
// Conditional logic for site name which might vary based on current DB instance;
// var dbname = String('%dbname').toUpperCase();
// if (dbname == "HCM92012")
// {
//   var site = "ps";  
// }// -- NOT REQUIRED (20160403) -- Repeat preceding logic for other instances (DEV, TEST, QA & PROD);
// This section was commented on 20160403

// This line was added on 20160403
// Use delivered getSiteName function for dynamically retrieving the site name for different environments.
var site = getSiteName();

// Inject javascript(s);

// jQuery - PT_JQUERY_1_6_2_JS;
document.write(unescape("%3Cscript src='/psc/" + site + "/EMPLOYEE/EMPL/s/WEBLIB_PTBR.ISCRIPT1.FieldFormula.IScript_GET_JS?ID=PT_JQUERY_1_6_2_JS' type='text/javascript'%3E%3C/script%3E"));

// CSK Fluid Image Replacement JS;
document.write(unescape("%3Cscript src='/psc/" + site + "/EMPLOYEE/EMPL/s/WEBLIB_PTBR.ISCRIPT1.FieldFormula.IScript_GET_JS?ID=CSK_FL_IR_JS' type='text/javascript'%3E%3C/script%3E"));
 

• The reason I am using the delivered IScript (IScript_Get_JS) in conjunction with document.write is because I am not able to use %JavaScript meta-HTML functions in javascript objects (in the same fashion as we do in HTML objects). Perhaps a future enhancement if anyone from Oracle is listening? :)
• The delivered IScript provides a way to resolve the javascript (at runtime) to the URL suitable for referencing the .js file on the web server (cache directory).
• I am using the custom variable site as a mechanism to make this javascript production ready and database refresh proof. This would allow the javascript to dynamically determine the sitename using variable substitution instead of hardcoding.

In the above example, you can see that I used the javascript object, CSK_FL_BOOTSTRAP_JS, as an online configuration to inject additional javascript objects with the following line of code.

document.write(unescape("%3Cscript src='/psc/" + site + "/EMPLOYEE/EMPL/s/WEBLIB_PTBR.ISCRIPT1.FieldFormula.IScript_GET_JS?ID=PT_JQUERY_1_6_2_JS' type='text/javascript'%3E%3C/script%3E"));

IScript for Image Object Source URL Resolution:

If we look into the WEBLIB_PTBR.ISCRIPT1.FieldFormula, we will find several useful IScripts similar to IScript_GET_JS that we used in the preceding section.

Since using meta-HTML such as %Image and %JavaScript does not seem to work in JavaScript objects, I tried to see if there was an IScript which might possibly return the URL suitable for referencing an image object on the web server (loaded on the cache directory). I did not find any delivered IScripts that did something like that so I wrote my own version.

WEBLIB_FL_CSK.ISCRIPT1.FieldFormula - IScript_Set_Image_URL_Variable

PeopleCode for Reference:

Function IScript_Set_Image_URL_Variable
 
   Local string &var = %Request.GetParameter("var");
   Local string &img = %Request.GetParameter("img");
  
   Local string &html = GetHTMLText(HTML.CSK_IMAGE_URL_JS, &var, &img);
  
   %Response.Write(&html);
  
End-Function;

HTML Object - CSK_IMAGE_URL_JS

Let us see this in action. Let us create our custom javascript object.

Navigation: Main Menu > PeopleTools > Portal > Branding > Branding Objects (JavaScript Tab)

JavaScript for Reference:

// Get Image URL for CSK_LOGO;
document.write(unescape("%3Cscript src='/psc/" + site + "/EMPLOYEE/EMPL/s/WEBLIB_FL_CSK.ISCRIPT1.FieldFormula.IScript_Set_Image_URL_Variable?var=cskLogo&img=CSK_LOGO_SVG' type='text/javascript'%3E%3C/script%3E"));

// Print variable using jQuery once the document is ready;
var $jq = jQuery.noConflict();

$jq(document).ready(function(){
  alert(cskLogo);
});

What does this JavaScript do?
- Calls IScript (IScript_Set_Image_URL_Variable) and passes two variables (var - variable name to store image URL; img - image object name).
- Prints variable using jQuery once the document is ready for testing purposes.

Note: I previously injected the delivered jQuery javascript PT_JQUERY_1_6_2_JS object which is how I am able to use jQuery in the above javascript.

Let us now inject this javascript into Fluid UI using the Fluid Bootstrap javascript created in the previous section.

Now if we try to access any Fluid content then we should get the alert message that displays the variable cskLogo with the relative image URL substitution.

We can also access the IScript directly on the browser to see what it does behind the scenes.

In the next post, I intend to cover some advanced Fluid branding concepts such as image replacement techniques without customizations (using the utilities detailed in this post) and more. Stay tuned!

Note: You could enhance the utilities detailed in this post by writing your own custom meta-HTML which is a topic described in great detail by Jim Marion in his book,  PeopleSoft PeopleTools: Tips and Techniques - Chapter 9 - Page 350.