Visual Update 1 for HCL Connections

Customize Visual Update 1

About

The release of Connections Customizer provides some great opportunities to customize Connections. Visual Update 1 is a a working example of how you can modify the existing appearance of Connections by overriding styles used on the site.

Visual Update 1 was actually written with visual customization in mind. In this topic you will learn the basics about the struture and variables used which make quick customizations, such as changing colors, possible.

Prerequisites

Connections Customizer

In this Visual Update example we use Customizer to apply the new design specification to Connections, simply by overriding CSS. 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 HCL Connections Customizer documentation for more details.

Sass compiler

This example is written using Sass, which is compiled into CSS that will be injected into pages by Customizer. This example uses Sass to create CSS files and a script that instructs Customizer to return these CSS overrides with responses.

"Verse Theme (Default)" or "Hikari" theme

Connections must be set to use one of these default themes: "Verse Theme (Default)" or "Hikari".

Overview of Steps

  1. Become familiar with the files and structure.
  2. View the visual updates as you work.
  3. Make a small modification, such as changing the brand colors.
  4. Share your customizations with others.
  5. Create a Chrome extension to share your modifications with others.
  6. Add your modifications to Connections for more people to see.

Files and Folders

1. Fork and clone hclcnx/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 hclcnx/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 hclcnx/cnx-custom-theme master branch.

View the visual updates as you work

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 application.

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 an open source Sass 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.

Increase the height of the top navigation bar
  • The properties of the top navigation bar are defined as variables and are centrally located in this file: 
      /scss/prereqs/_navbar.scss

Try to change the height and font-size

  1. Locate /scss/prereqs/_navbar.scss
  2. Change $navbar-height to 80px.
  3. Change $navbar-font-size to 16px.
  4. Save the changes and if the compiler is watching it will generate the necessary css files. It might only generate global.css because the navigation bar is a global item.
  5. Reload the web page to see the changes.

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;
}

Share your customizations with others

Create a 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.

Create application in app registry

When you are ready to share these changes with a wider audience, follow the instructions to Create and Enable an application in the app registry.

Back to main | Back to top

Copyright 2017, 2019, HCL Technologies Limited