author photo
by Scott Good
Technical Sales Specialist, IBM Global Markets

domino toymakers home page

The IBM Connections Engagement Center (ICEC) gives organizations a way to easily present content to their users in a flexible and attractive platform. This content can come from IBM Connections communities or from almost any other source—such as other company applications, the Internet, and so on.

ICEC ships with a handful of basic themes, but most customers are likely to want to enhance those themes for a more attractive user interface (UI), or just to match up better to corporate visual standards.

Fortunately, ICEC makes this quite easy to do, given a basic set of web development skills.

This article is intended for developers experienced with Cascading Style Sheets (CSS) and who have at least a basic understanding of JavaScript. I won’t spend much time explaining the nuances of either technology but will, instead, discuss ideas you can use to leverage those technologies to enhance what ICEC gives you out of the box.

So, let’s start there: With what you get out of the box.

ICEC themes out of the box

The Domino Toymakers page shown at the beginning of this article is a highly-customized ICEC theme. To give you a sense for the kinds of visual changes that were made to get to the final Domino Toymakers theme, in the image below you can see the same page presented using the default out-of-the-box ICEC theme:

default ICEC theme

And, although there are several other themes available with ICEC, they are all minor variations on the default theme:

other basic themes showing little variation

While these may be functional, they’re not very eye-catching. And yet, with a bit of work (and a fair sprinkling of CSS), they can be made quite appealing, as seen in this demo example:

square cafe demo site

 

ICEC 101

If you’re reading this, I assume you have at least a basic knowledge of ICEC. If not, here are a few things to get you going with theming.

First, you need to be an ICEC Administrator. You’ll know you are if you see the Customize button near the top of your ICEC pages. This used to be on the right side. Recently it was moved to the left. Wherever it is, clicking Customize opens an administrative UI, as seen here:

Connections admin UI

Although there are five tabs and a lot you can do from the ICEC Admin UI, from a theming perspective, most of what you’ll need to do will happen on the Engagement Center Settings tab, under Customization Files. This is where you will upload not only your theme’s CSS file but also any images you want to use (such as a company logo). If you need to add JavaScript to the page (as I did with the Domino Toymakers theme), you’ll add that here, too. I’ll discuss that later.

Note that you will also be spending a little time on the Page Settings tab. This is where you select the theme and navigation to be used on each page.

Different environments require different themes

It would be both logical and convenient if a theme developed in one ICEC environment—for instance, on the cloud—would work exactly the same in another ICEC environment (e.g., on-prem, or in a tech seller’s personal ICEC environment). Unfortunately, while much of what you do to create a theme will transfer at some level, the core Connections CSS in each of these environments is different, requiring somewhat different CSS for each ICEC platform.

It’s also worth mentioning that if your Connections environment uses one of the Visual Updates, that, too, will change your CSS. As of late October 2018, each new Visual Update version has required changes to existing ICEC themes to restore the original look and feel. So, if you’re using the Visual Updates—and why wouldn’t you be?—fair warning.

The basic components of the ICEC UI

Over the past 12 months, I’ve created literally dozens of ICEC themes for client demonstrations and have come to think about the elements on the page in three distinct groupings:

  • The Connections header bar
  • The ICEC navigation menu and breadcrumbs
  • The individual widget containers (as a group)

When building a new theme, I tend to work on each of these groups individually, in the order shown above. I won’t discuss each of these in detail as the nuances of identifying elements to be changed and determining selectors sufficient to make those changes should be pretty well understood by experienced front-end developers.

Having said that, a few thoughts:

First, in my experience, once you have identified the selector which applies to whatever it is you wish to change, it is usually sufficient to add “body” to the beginning of that selector to make your rule override the original. For instance, to change this CSS…

.xccstyle .xccWidget .wheader .wtitle {
color: black;
}

…I generally preface the selector with body:

body.xccstyle .xccWidget .wheader .wtitle {
color: red;
}

Second, if your organization is using the recent Connections Visual Updates, that CSS makes extensive use of the !important modifier. If your change isn’t taking effect, that’s probably why, and this is a case of needing to fight fire with fire:

body.xccstyle .xccWidget .wheader .wtitle {
color: red!important;
}

Inserting a company logo

Every new theme I build starts with the header bar, and every header bar starts with a company logo. Out of the box, Connections has no logo in the upper left corner. Instead, it has text, like this:

IBM Connections home page, showing no logo

So, the first thing I do is find a logo that will fit into the space. Typically, I look for logos that are horizontally-oriented and readable at 30-40px tall, which is roughly the space available. Here’s an example:

Banner with logo that fits in available space

Of course, not all logos fit so nicely into a horizontal space. Sometimes you have to use a little creativity to make a logo both big enough to read and small enough to fit:

logo edited to fit in banner

Regardless, the challenge is the same: Hide the text that’s there and replace it with a logo graphic. I tend to use Chrome as my development browser, but pretty much all browsers these days provide Developer Tools that will let you select a part of the page and see the related HTML and CSS. For the logo area, in an on-prem environment, the HTML looks more or less like this:

<div class=”lotusRightCorner”>
<div class=”lotusInner”>
<div class=”lotusLogo” id=”lotusLogo”>
<span class=”lotusAltText”>IBM Connections
</div>
</div>
</div>

Ignoring for a moment that the <div> with the class of lotusRightCorner actually appears in the upper left corner of the page, this is where you want to be.

To substitute a graphic for the text, first hide the <span> containing the text:

body.lotusui30 div.lotusBanner .lotusLogo .lotusAltText {
display: none;
}

Then add a background graphic to the lotusLogo div, like this:

body.lotusui30.xccstyle div.lotusBanner .lotusLogo {
margin: 2px 0 10px;
color: transparent;
font-size: 1.16em;
line-height: 1;
font-weight: 700;
background-image: url(/xcc/rest/public/custom/YourLogo.png);
background-size: contain;
width: 198px;
background-repeat: no-repeat;
top: 3px;
height: 28px!important;
}

Note that it’s necessary to give the containing <div> both height and width to get the background to show up. You’ll have to fiddle with the various sizes here to get things to show up as you want them.

Also note the URL used to retrieve the logo. All of the files added to the Engagement Center Settings > Customization Files area of the ICEC Admin UI can be retrieved with the URL:

/xcc/rest/public/custom/Whatever_Your_File_Name_Is.jpg

This is true not only within your theme’s CSS file, but also if you want to store, say, a graphic or other file to be used elsewhere on your ICEC page (such as, in an HTML widget).

Modifying other page components

Working with CSS is an exercise in patience. While it would be great to be able to make lots of changes quickly, that’s just not how it works. At least not for me. You’ll need to systematically work your way through each of the page’s elements making changes as you go.

So where do all of these changes—that is, your new CSS specifications—go? In a new CSS file for your theme. Be sure to name it something that makes sense for what you’re building because the CSS file’s name is what you will have to choose to set that theme on your pages.

Your CSS file goes into the Engagement Center Settings > Customization Files area of the ICEC Admin UI. Then, on the Page Settings tab, click Layout to actually choose your new theme. Unless you change the name of the theme, you only need to do this once.

Personally, I find it easier to edit and store my CSS files outside of ICEC and then to just upload a new version with each change. It is possible to edit these files within ICEC, but the editor is pretty basic.

More advanced techniques

At the beginning of this article, I mentioned the Domino Toymakers theme, which looks like this:

domino toymakers home page

This theme requires a special <div> to be added to the page to hold the header graphic–that is, the large yellow and orange graphic behind the Domino Toymakers title and the ICEC navigation links. I added this <div> to the page using the custom.js file, which can be found in the Customization Files list.

custom.js is a special file that contains code which allows you to add custom widgets to your page, among other things. Although you don’t want to change any of the code already in there, you can add your own code to enhance your page(s). In my case, I added the following code to create a <div> at the top of the page that I could use to insert my header graphic:

var iterationCounter = 0;
function addClassForSafari() {
if (navigator.userAgent.indexOf(‘Safari’) != -1 && navigator.userAgent.indexOf(‘Chrome’) == -1) {
// Add ‘safari’ to the object’s class list
const body = document.body;
if (body) {
document.getElementsByTagName(‘body’)[0].classList.add(“safari”);
} else {
iterationCounter++;
if (iterationCounter < 50){
setTimeout(()=>addClassForSafari(),100)
}
}
}
}

Keep in mind that any changes you make to the custom.js file will apply to all ICEC pages unless your code somehow limits itself.

The final result

The end result is an ICEC environment customized to your specific needs; in particular, to a look-and-feel that is appropriate for your, or your client’s, requirements. By using ICEC’s built-in container for CSS files (in the Customization Files area) and the ability to add your own JavaScript to the page using the custom.js file, it’s possible to make significant changes to both the functionality and appearance of your ICEC sites.

Join The Discussion

Your email address will not be published. Required fields are marked *