Customizer: Samples Made Simple

Many of us who have written Notes apps over the years remember the Nifty Fifty with a certain fondness. This was a set of 50 template applications that did various useful things out of the Notes R5 box – Stefan Wissel summarizes it very well here in a Nifty Fifty blog post from a number of years back. Quite apart from the obvious and immediate functional value that these templates delivered, the educational benefit was quite possibly even greater! Here was a bunch of apps that developers could explore from the inside out, learn from, extend and ultimately make their own. Perfect!

Today many IBM ICS customers are familiar to some extent with Customizer – umm, some tool for adapting the IBM Connections user experience by providing custom client-side CSS and JavaScript, right? Very often, despite real needs, the vague concept around a technology never progresses to anything more concrete for customers because of difficulties getting it up and running.  Maybe some initiative like the Nifty Fifty could help enable the Connections community learn how to customize their environment – i.e. a set of sample CSS/JS customizations that can be easily deployed on-cloud or on-premises that perform simple tasks and come with re-usable source code. And that in a nut shell is what the Nifty Scripties application provides!

Nifty Scripties

Let’s start with IBM Connections Cloud. It has an App Catalog that has undergone a number of major upgrades over the past twelve months, transforming it from a somewhat moribund site housing half a dozen apps to something entirely more modern with over thirty applications. The most recent addition to this collection is the Nifty Scripties app, as identified in the following screen display.

Figure 1. IBM Connections App Catalog Main Page

IBM Connections Catalog Main Page
An administrator of a tenant organization in IBM Connections Cloud can find this App Catalog page via the Admin > Manage Organization > Apps > App Catalog menu path or by following this URL:

https://apps.{data_center_id}.collabserv.com/manage/catalog/apps/allapps/input

All application offerings follow the same pattern, namely, click on Learn More to get details of the offering and click Get to install the application into your organization. Nifty Scripties had already been installed in my cloud organization when this screenshot was taken so it presents a Configure button instead which enables you to change some aspects of how the application is deployed.

Note: Nifty Scripties is a free offering that will be installed at no cost to your organization.

Regardless of whether you are installing from scratch or reconfiguring your installation, you will next be asked if the Nifty Scripties app should be installed for your Entire Organization or for selected Individuals. Given that this is a collection of samples then you should select Individuals so that the modified user experience is not exposed to all users in your organization. This is particularly true if you are experimenting inside a production tenant org. By selecting the Individuals option you can target the samples to specific users once installation is complete (e.g. just yourself) and not disrupt the usual experience of regular users.

The next screen lists the 10 separate samples contained within the Nifty Scripties app (okay, 10 rather than 50, but with your help this list will grow :-)). You can choose any combination of the 10 samples to install. It makes sense to install all the samples as you can always enable or disable individual samples later on.

Figure 2. Nifty Scripties Samples List

 Nifty Scripties Samples List
Clicking Next and Finish completes the installation and you can see the app displayed in the My Apps tab. Since Nifty Scripties is a Customizer app it means that you will see the results of installation in the App Registry since all Customizer apps live there. You can navigate to the App Registry from the App Catalog by clicking Organization Extensions in the Administration navigator and then following the new Apps Manager link.

The final step is to validate that the app is enabled for the correct set of consumers. By default the App Catalog will reduce the audience for the Nifty Scripties app to the admin user who installed the app – or if this email address could not be resolved during the installation process then a dummy email address is used (“userid1@example.com”).  You can check the exact setting via the App Registry Code Editor. Listing 1 shows the JSON fragment for the Nifty Scripties app container with the relevant match rule highlighted in red.  Be aware that you can add more user entries to the “user-email” list or employ user-group references.  For more information on this you can jump to the Fine Grained Filtering based on User Identity section of the online documentation or the Support for Groups blog article.

Listing 1. Nifty Scripties App – Default User Match

{
   "app_id":"com.nifty.scripties",
   "name":"Nifty Scripties App",
   "title":"Nifty Scripties App",
   "description":"Provides the Top Ten Customizer Apps",
   "services":[
      "Customizer"
   ],
   "match":{
      "user-email":[
         "martindonnelly@yopmail.com"
      ]
   },
   "state":"enabled",
   "extensions":[ ... ]
}

Once you are satisfied that the match rule meets your needs then you are ready to play around with 10 new Customizer samples – all good to go! This short video (Nifty Scripties Getting Started) walks through everything you have read so far.

Samples in Action

Inside the Nifty Scripties JSON you will see a JSON object defined for every extension – i.e. one for every item listed in Figure 2. They all follow the same pattern. Listing 2 shows an example of one such extension:

Listing 2. Nifty Scripties Extension Example – Search Results in New Window

{
   "ext_id":"com.nifty.scripties.searchResults",
   "name":"Open Search Results in New Window",
   "description":"Open search results in new window",
   "type":"com.ibm.customizer.ui",
   "payload":{
   "include-files":[
      "cnx-search.js"
   ],
   "include-repo":{
      "name":"cnx-searchresults"
      }
   },
   "path":"search"
}

 

All extensions are characterized by three general properties: name, type and path.  The name is self-explanatory, the type represents the Customizer extension point (com.ibm.customizer.ui means this is a UI customization and this value is the same for all samples in this app) and the path identifies the IBM Connections app that the customization applies to – ‘Search’ in this instance.

The payload section contains properties that can refine the behaviour of the extension. Again in this particular instance it is very simple – include the cnx-search.js file in the HTTP response when serving up Search pages in IBM Connections.  Some Nifty Scripties extensions may have extra properties depending on the complexity of the use case.

To see this sample in action, do the following:

  1. Ensure that the extension is in an enabled state and targeted for you
  2. Navigate to a page in Connections where you can perform a search, e.g. Homepage
  3. Enter a term in the Search text box and press {CR} or click the Search icon
  4. When searching completes, click an entry in the results page

Observe that the content for the result is opened in a new separate tab window in your browser. Ordinarily this content would be loaded into the current page, overwriting the results. Figure 3 shows a screenshot of this scenario along with some assistive callouts.

Figure 3. Nifty Scripties Sample – Open Search Result in New Window

 Open Search Result in New Window
Once you have successfully walked through this customization, you can apply the same pattern to the other extensions in the Nifty Scripties app. Table 1 below provides a functional summary of what each extension does and there is another short video available online that walks through some of the other Nifty Scripties samples (Nifty Scripties in Action).

Table 1. Sample Summary

  1. Smooth UI Loader reduces screen jitter that can sometimes happen according as many components compete to update a Connections HTML page at runtime. If you are using this extension in conjunction with other Customizer extensions it is important that is loaded first – hence the reason its name is set as “!!Smooth UI Loader”. When an application contains more than one extension, they are loaded alphabetically by name, and the leading “!!” characters force the extension to the front of the queue in this application.
  2. Activity Stream Infinite Scroll replaces the Pager UI with a dynamic refresh mechanism which fetches more entries according as the user navigates towards the end of the displayed list.
  3. Bulk Delete Members from a Community will enable community owners to remove members via a multi-select people picker dialog box as opposed to repeating individual delete operations one by one. A Bulk Delete Members button will be rendered in the Community Members page but only to Community owners.
  4. Change CKEditor Font Size will programmatically set the default editor font size to whatever supported font you specify inside the source code JavaScript and CSS include files. In this sample, the font size is specified as 18 pixels in the JavaScript code.
  5. Community Flipcard Layout allows you to toggle between the traditional list view of your Communities and a Card Layout. Each card displays the community icon on the front side and flips over to display summary community information on the reverse side whenever you hover the mouse over it.
  6. Enhanced Activity Stream Notifier will post an update to your homepage when a new message appears in your activity stream. Thus for example if another user @mentions you in a post then a notification is proactively rendered without you having to refresh the homepage. Figure 4 shows a screenshot of how this looks.
  7. Mark Favourite Community renders a heart icon in the title row of each Community entry (see Figure 5). Clicking the icon adds that particular community to a list of favourite communities that can be displayed and selected by clicking Favourite Communities in the Communities navigation bar.
  8. Open Bookmarks in New Window opens the content page associated with any given bookmarked link in new browser window tab, thus leaving the original bookmark view in place.
  9. Open Search Results in New Window is the same concept as #8 but for Search results. This extension is explained in detail in the Samples in Action section and is also featured in the Nifty Scripties in Action video.
  10. Set Orient Me as Homepage will replace the traditional Connections Homepage with the new OrientMe homepage as the default user experience. To do this otherwise requires a ticketed request be processed by IBM Connection Cloud dev ops for your organization. Under the covers this script creates a special setting in the browser’s local storage, as shown later in Figure 6.

Summary

The objective of Nifty Scripties is to create a simple means of provisioning Customizer samples to organizations in IBM Connections Cloud. On-premises customers can avail of the same samples by copying the resources from the GitHub repositories identified in the Nifty Scripties application JSON and laying that content down under the local Customizer customization folder.

Hopefully this blog article along with the accompanying videos and the screenshots that follow in Appendix 1 will help get you up and running with simple IBM Connections UI customizations.

Links to Other Useful Resources

Customizer Online Documentation

IBM Connections Developers GitHub Organization

OpenCode4 Connections GitHub Organization

Customizer Enablement Videos on OpenNTF YouTube Channel

App Reg JSON for Nifty Scripties

This Blog Article as a PDF

 

Appendix 1

Figure 4. Enhanced Activity Stream Notifier

Enhanced Activity Stream Notifier

Figure 5. Favourite Communities

Favourite Communities

Figure 6. Set Orient Me as Homepage – Local Storage Info

Set Orient Me as Homepage - Debugger