Visual Update 1 for IBM Connections

Visual Update Example App - Preview Available!

About this Example

The release of Connections Customizer provides some great opportunities to customize Connections. For example, you can modify the existing appearance of Connections by overriding styles used on the site.

In this Visual Update example we use Customizer to apply the new design specification to Connections, simply by overriding CSS. This example uses Sass to create CSS files and a script that instructs Customizer to return these CSS overrides with responses.

Prerequisites

Customizer is available on IBM Connections Cloud for tenants of the North America and Europe data centers. Before using Customizer your organization must first register for the service by sending an email with some simple information. Refer to section 3 of the IBM Connections Customizer documentation for more details.

What's included in the Preview

This release is a preview and has limitations, which include:

As long as Customizer is enabled, this example can be used with IBM Connections Cloud or IBM Connections on premises. However, there are some known visual styling issues when used with IBM Connections on premises.

Updates

We periodically release updates to fix defects and add styling to more applications and pages.

Review what's new and update history

Recommended Steps to Get Started

  1. Become familiar with the Files and Folders in this example.
  2. View the visual updates using Tampermonkey.
  3. Make a small modification, such as changing the brand colors and test using Tampermonkey.
  4. Create a Chrome extension to share your modifications with others.
  5. Add your modifications to Connections for more people to see.

Files and Folders

1. Fork and clone ibmcnxdev/cnx-custom-theme files on your local system

We recommend creating a fork and then clone that fork to your local file system. You can clone files using GitHub Desktop or a terminal window.

Once you have the files locally you are set to go. Make note of the local path for the next step.

2. Browse the files and folders to become familiar.

3. Understand why some scss files start with a "_" (underscore)?

You may have noticed, there are a lot of scss files but there are only a few CSS files generated. The point of this is to send less requests to the server and make the load time as fast as possible. The way this is achieved is by placing a "_" (underscore) before every .scss file that we don't want to create a CSS file for. We refer to these "_.scss" files as "partials". The main scss files, such as files, global, meetings, profiles, search, and settings don't have a "_" in front of their file name. The main scss files import "partials" and compile them into large CSS files.

4. Keep your local clone up to date

Periodically pull updates from ibmcnxdev/cnx-custom-theme to keep your local clone up to date. We will post updates to fix issues and to add styles to more pages and applications. Pull updates into your local clone from ibmcnxdev/cnx-custom-theme master branch.

View Visual Updates with a Browser Extension

Use a browser extension that allows you to override elements and CSS of a page with local files, such as Tampermonkey for Chrome. The extension allows you to see the changes you make in your local files.

Follow these steps to use Tampermonkey for Chrome to override the styles on the site with the styles defined in the files on your local machine.

  1. Install the Tampermonkey extension in Chrome.
  2. On the Extensions page, locate Tampermonkey and select the box to "Allow access to file URLs".
  3. Access Tampermonkey and go to the Dashboard to create a new script.
  4. In the editor, replace all the code with the code found in the /tmScript.js file.
  5. Replace "YOURFILEPATHGOESHERE" with the full path to the cloned /cnx-custom-theme directory.
    • Note: file:/// has 3 slashes.
    • Mac example:
      ...
      // @require      file:///User/username/folder/cnx-custom-theme/periscope.js
      // @resource     files file:///User/username/folder/cnx-custom-theme/css/files.css
      // @resource     profiles file:///YOURFILEPATHGOESHERE/cnx-custom-theme/css/profiles.css
      ...
    • Windows example:
      ...
      // @require      file:///C:/folder/cnx-custom-theme/periscope.js
      // @resource     files file:///C:/folder/cnx-custom-theme/css/files.css
      // @resource     profiles file:///YOURFILEPATHGOESHERE/cnx-custom-theme/css/profiles.css
      ...
  6. After you replace the file paths, save the script.
  7. Go to Connections Cloud and Files to see the changes included in this example.

Try Making Modifications

To make CSS easier to manage, all of the styling is written is Scss which needs to be compiled into CSS using a Sass Compiler.

How to Compile the Scss Files

You can use Koala, which is an open source compiler, to compile Scss into CSS. Learn more and install a Sass compiler.

After you install a Sass compiler you can set it to watch the /cnx-custom-theme directory for changes to files in /scss and it will automatically compile and output files to /css. The easiest way to do this is to run a watch command in a terminal window.

  1. Open terminal and navigate to the /cnx-custom-theme folder.
  2. Run this command:
      sass --watch scss:css
  3. Now when you make changes to scss files and save, they are compiled and the appropriate CSS files are updated in the /css folder.

Change the brand colors

Try to change the colors

  1. Locate /scss/prereqs/_colors.scss
  2. Change the primary brand colors, $brand-01, $brand-02, and $brand-03, with different hex values.
  3. Save the changes and if the compiler is watching it will generate all the css files because _colors.scss is used in all of them.
  4. Reload the web page to see the changes.

Add another application to style via a specific URL

Let's say we are trying to add styling to the homepage that is currently not being styled. An overview of the steps are as follows:

  1. Create a main homepage.scss file that imports the partials we need.
  2. Create an scss partial file for app specific styling.
  3. Add the homepage url to periscope.js.

1. Create a main homepage.scss file that imports the partials

Create a homepage.scss file in the /scss folder. You can also duplicate one of the other main scss files to start from. The contents of the file should look something like this:

  // Prerequite Imports
  @import "prereqs/prereqs";

  // Component Imports
  @import "components/components";

  // App Specific Imports
  @import "apps/homepage/homepage";

The first import loads all predefined scss variables such as colors and mixins. The second import loads all the common components used across applications. If you want to apply only some of them, you can import scss partial files from the /components folder. The last import is for application specific styling, which is covered in the next step.

2. Create an scss partial file for app specific styling

Each application typically has some application specific styling. Create an app specific partial file, _homepage.scss, in a /apps/homepage folder. Include app specific styling that applies to pages with /homepage/ in the URL. If it is a component that might later be used on other pages too, it should go under components. Or if it's a styling that exists on every subURL of your Connections application, it would be logical to create the file under the /global folder.

3. Add the homepage URL to periscope.js

The main goal of periscope.js is to detect what method the user is using to load the CSS to Connections and load the relevant CSS files when the user is on certain URLs that were specified within the mappings object. Each key within the mappings object is a CSS file for every url within the array corresponding to the key will load.

Locate the mappings in periscope.js and add the CSS : URL mapping or uncomment one that is already there. In this case "homepage" is already in the file and can be uncommented.

var mappings = {
  //global is special case where the empty array applies to all the pages.
  "global":[],
  "files":["/files/"],
  "meetings":["/meetings/"],
  "profiles":["/profiles/",
              "/mycontacts/",
              "/contacts/"],
  "search":["/search/"],
  "blogs":["/blogs/"],
//  "activities":["/activities/"],
//  "communities":["/communities/"],
//  "home":["/homepage/"],
  "forums":["/forums/"],
  "wikis":["/wikis/"],
  "settings":["/manage/account/user/",
              "/news/",
              "/manage/subscribers/showInviteGuestDialog/"]
};

So if we want to add the url of homepage to load the homepage.css file, our mappings should look like the following.

var mappings = {
  //global is special case where the empty array applies to all the pages.
  "global":[],
  "files":["/files/"],
  "meetings":["/meetings/"],
  "profiles":["/profiles/",
              "/mycontacts/",
              "/contacts/"],
  "search":["/search/"],
  "blogs":["/blogs/"],
//  "activities":["/activities/"],
//  "communities":["/communities/"],
  "home":["/homepage/"],
  "forums":["/forums/"],
  "wikis":["/wikis/"],
  "settings":["/manage/account/user/",
              "/news/",
              "/manage/subscribers/showInviteGuestDialog/"]
};

Change icons on a page

The way Connections was built, most icons are loaded via a sprite sheet as background and to show the certain icon, the developers used background-position and set x,y values to some specific value.

If we want to replace an icon, we can add in an svg file. However since we can't modify the DOM to insert the svg, we can override the background and include the svg as encoded in base64. Since this example has many icons changed, we made this process as simple as possible.

  1. Edit the .svg in a text editor.
    • Remove any unnecessary comments or attributes.
    • Remove all the line returns so that the .svg markup is all on one line and save the file.
    • Include fill="#000000" on parts of the SVG where you want to be able to change the color. The logic used in this example looks for fill="#000000" and replaces it with the color you specify.
      Note: This only supports changing one color at this time.
  2. Add the .svg as a variable to use in Connections. Find the scss/prereqs/_icons.scss file and add your icon as a variable:
    $svg-myIcon:'<svg width="24px height="24px" blah blah blah;><path fill="#000000" d="blah blah"></path></svg>';
    
  3. Apply the icon variable to be used as a background-image for any element you need by doing the following:
    .myElement{
       background-image:svg-url-with-replaced-fill($svg-myIcon, '#000000', $colorVariable) !important;
    }
    

How to create / update Chrome extension

Create a Chrome extension to share your changes with others.

  1. Create a new folder for the extension, such as /theme-extension, and put a copy of the /cnx-custom-theme folder inside of it.
  2. In the extension, edit the /manifest.json file if:
    • You want to modify the version number of the extension
    • You changed the name of the periscope.js file
  3. In the extension folder, remove the following folders that aren't needed and to save space:
    • /.git
    • /.sass-cache
    • /docs
    • /scss
    • /svg
  4. Zip up only the /theme-extension folder.
  5. Share theme-extension.zip with others along with the following instructions to install it.

Instructions to install the Chrome extension

  1. Download this zip file and unzip it where you want.
  2. Go to chrome://extensions
  3. Check "Developer mode"
  4. Click "Load unpacked extension..."
  5. Locate and select the /theme-extension folder you unzipped. If you see /theme-extension/theme-extension select the nested folder.

Instructions to update the Chrome extension with an updated version

  1. Download and replace the zip and folder from before.
  2. Go to chrome://extensions
  3. Click "Reload" on your existing Chrome extension to get the updates.

Add to Connections as an Organization Extension

An organization administrator can add a Customizer application containing visual updates. The Customizer application is added as an Organization Extension in the admin interface. The Customizer application is defined in a JSON file which identifies the components that need to be targeted and the actions that need to be performed.

This section includes:

Add this Visual Update example as an extension in Organization Extensions

Refer to IBM Connections Customizer documentation for more information.

  1. As an adminstrator, locate Admin in the top navigation and select Manage Organization.
  2. Go to Organization Extensions.
  3. Click the new App Manager link at the top of the page.
  4. Click the New App button and you will see the following JSON template.
    {
      "name": "",
      "title": "",
      "description": "",
      "services": [],
      "extensions": []
    }
    
  5. Replace the JSON template with the following JSON content:
    {
      "name": "Visual Update 1 for IBM Connections",
      "title": "Visual Update 1 for IBM Connections",
      "description": "Customizer extension to re-theme IBM Connections.",
      "services": [
         "Customizer"
      ],
      "extensions": [
        {
          "name": "Visual Update 1 for IBM Connections",
          "type": "com.ibm.customizer.ui",
          "path": "global",
          "payload": {
            "include-files": [
              "periscope.js"
            ],
            "include-repo": {
              "name": "cnx-custom-theme"
            }
          }
        }
      ]
    }
    

    Notes: This sample JSON can also be found in cnx-custom-theme/org-ext.json.

  6. The include-repo property in this example points to the cnx-custom-theme repository in the ibmcnxdev GitHub organization so no changes are needed to review the example. See the next section for how to add your own customized files to Connections.
  7. Save the changes.

Add your visual customizations as an extension in Organization Extensions

Follow the same steps as above but make modifications to reference your own customized files.

Important: Refer to IBM Connections Customizer documentation as you complete this step.

  1. Store your customizations in a GitHub repository that can be accessed by Customizer.
    • By default Customizer, via the include-repo property, looks for customizations in a repository in the public IBM Connections GitHub organization (https://github.com/ibmcnxdev). Refer to the IBM Connections Customizer documentation for instructions to create or share a repository.
    • You can use a private GitHub repository. Refer to IBM Connections Customizer documenation for instructions.
  2. Update Scss variables to reference your GitHub repository. Open /global/_repoName.scss and update the value of repo-name. Compile the Scss changes.
    $repo-name: 'cnx-custom-theme';
  3. Update the application JSON to reference the correct GitHub repository.
    "include-repo": {
      "name":"cnx-custom-theme"
    }
    

Enable for no users or a sub-set of users

You can enable the extension for no users or a sub-set of users. This way you control who will see the new visual updates.

Enable for no users by adding a fake email address inside "user-email":

  "payload": {
    "match": {
      "user-email": [
        "userid1@example.com"
      ]
    },
    "include-files":[
      "periscope.js"
    ],
    "include-repo": {
      "name":"cnx-custom-theme"
    }
  },
  

Enable for a sub-set of users by adding email addresses inside "user-email":

"payload": {
  "match": {
    "user-email": [
      "userid1@example.com",
      "userid2@example.com"
    ]
  },
  "include-files":[
    "periscope.js"
  ],
  "include-repo": {
    "name":"cnx-custom-theme"
  }
},

Support

FAQ

Why don't I see Visual Update 1 changes?

Question: Why don't I see any visual updates after I enable Visual Update 1?

Answer: Check the following things:

Which customizations appear if both an org extension and Visual Update 1 are enabled?

Question: Which customizations appear or win if an Organization extension with company updates and the Visual Update 1 for IBM Connections application are enabled? Put another way, what is the sequence or order of changes when enabling Apps and extensions.

Answer: Which customizations appear or win is based on the order in which extensions get injected into the page by Connections Customizer. Customizer makes a request to the App Registry and it returns a list of extensions by name, in alphabetical order. The changes are applied in alphabetical order, overriding changes made earlier in the alphabet.

The App Registry includes the Visual Update 1 for IBM Connections application. A company adds an extension to the App Registry, to override styles, and it is called "Xtended Company Theme". The Visual Update 1 for IBM Connections application is loaded and applied first. Next the "Xtended Company Theme" gets loaded with its CSS and/or JS overriding any of the Visual Update 1 for IBM Connections changes.

What is supported

The Visual Update 1 for IBM Connections is supported only for implementations where the application is installed and configured directly from the IBM Connections App Catalog and in which all of the following criteria are met: (1) Only the Verse Theme (Default) is enabled (2) No additional customizations are configured. Implementations added manually through an organization extension, combined with additional customizations, and/or contained code which was modified from its original state will not receive support considerations.

Due to the preview nature of the application, PMRs will not be accepted and resolved by IBM. Questions and support requests, however, can be posted directly on the support forum located here. IBM will not assist with making modifications to the open source code provided for this application nor modifications created to add additional customizations in lieu of the Visual Update 1 for IBM Connections.

While the application is in preview, bi-directional language support will not be included. Visual updates will apply only to applications stated in official communications and will not extend to custom widgets added to Connections. IBM plans to regularly add new Connections applications to the visual update and will share communications accordingly.

Getting support

Ask questions and view answers tagged with 'cnx-custom-theme' on dW Answers.

Copyright 2017, 2018, IBM Corporation