How to Customize Your SmartHub User Interface

Tip: In addition to the following instructions, for an example of customizing SmartHub, see How to Add a Tabular View to Your Results Page.

Note: When updating from SmartHub v5.x to SmartHub v6.x the custom settings files should be checked because some features, names and labels have been slightly modified.

• About the Files that Control the SmartHub User Interface

• How to Modify Your SmartHub User Interface

• Default SmartHub HTML and Settings Files

• Custom SmartHub Settings Files

• SmartHub Components

• Loading Default Components: SmartHubResourceLoader

• Example: Exclude the SavedQueries Module

About the Files that Control the SmartHub User Interface

SmartHub Web Pages: Defaults

The files described in the table below contain the code responsible for your SmartHub Index (or landing page), and Results pages.

• If you wish to modify the appearance of SmartHub, DO NOT change these files.
• Both Index.html and Results.html are overwritten when you upgrade SmartHub.

SmartHub Web Pages: Custom

How to Modify Your SmartHub User Interface

To modify the appearance of the Index and Results SmartHub HTML pages, use the following steps.

1. ALL customizations are made to files contained in the "CustomerCustomization" folder.
2. BA Insight recommends you leave the default folder as a backup.
3. Before using the files in the "CustomerCustomization" folder, make a copy of it and rename the copy, as shown in the screenshot below.
   
   
   
4. Make your customizations as described in the SmartHub Web Pages: Custom table above.

How to Create a Custom Index Page

Many clients choose to use a custom Index page to implement customizations to their Index page (Index.html).

This also prevents the file from being overwritten at upgrade time.

1. Copy the entire directory "<SmartHub installation root directory>\CustomerCustomization\"
   1. Creating a copy of IndexCopy.html and renaming the copy prevents any customizations from being permanently lost when the directory is overwritten at upgrade time.
      
2. Rename your copy of the "CustomerCustomization" directory.
   
3. (Optional) Rename the IndexCopy.html file.
   
4. Make any modifications you desire to IndexCopy.html.
   
5. Since SmartHub loads Index.htmlby default, you must direct SmartHub to load the new file in IIS using the steps in the topic below.

How to Set SmartHub to Use a Custom Index or Landing Page

Follow the steps below to direct SmartHub to load your custom Index.html file ("MyIndex.html" in the example below):

1. Locate your custom Index page file (by default, IndexCopy.html).
   
2. Open Internet Information Services (IIS), and select your SmartHub site.
   
3. Click "Default Document".
   
   
   
4. Click the "Add" link under the Actions menu on the right side and enter the name of your custom Index file ("IndexCopy.html" or "MyIndex.html", for example) to add your index page as the default root page.
   
   
   
5. Your custom Index file appears as the new default root page:
   
   

Default SmartHub HTML and Settings Files

The SmartHub Web pages above are HTML files, but many of the page elements and behaviors are controlled by code in settings files which stored in the \modules\SmartHubResourceLoader directory.

See the table below:

Custom SmartHub Settings Files

The table below summarizes the names and locations of the custom settings files you create to replace the default SmartHub files:

SmartHub Components

• Each SmartHub component is found in its own directory, under \modules, as shown in the graphic below.
• Each SmartHub component stores its settings in the same file: <SmartHub root>\modules\SmartHubResourceLoader\DefaultModuleSettings.js.
• Component settings are used to change the behavior and/or appearance of the component.
• To alter a component's settings, the settings are copied into the appropriate section of your custom settings file, and modified from there.

Loading Default Components: SmartHubResourceLoader

• The SmartHubResourceLoader loads default components or modules (see the table above) through the DefaultModuleSettings.js settings file:
• The landing page and query results pages load their settings separately:
  
  • On the page "Results.html" SmartHubResourceLoader uses the settings file "ResultsPageSettings.js" to load the settings on the (query) Results page.
  • On the page "Index.html" SmartHubResourceLoader uses the settings file "IndexPageSettings.js" to load the settings on the Index (start or home) page.
    
    

• The code that loads the settings file is found at the top of any SmartHub page.
  • For example, the Results page (Results.html) is shown in the graphic below
    • The Results Page Settings file path is defined around line 24.
    • This default settings file can be overridden by entering the path to a custom settings file.
      • The path shown on Line 20 in the Results HTML file shown below can be changed to a custom settings file you define. See the table "SmartHub Web Pages: Custom" above.
    • Multiple custom settings files can be used. They are merged and loaded at run time.
      
      
      

Copy the Settings You Want From Other Files Into Your Custom Settings File (Optional)

1. Copy the settings you want to modify from other settings files, such as TypeAhead.
2. All module settings are found in the file <SmartHub root>\modules\SmartHubResourceLoader\DefaultModuleSettings.js.
   1. The TypeAhead settings are contained on line 81 in the DefaultModuleSettings.jsexample below:
      
       
      
3. Paste the settings into your Custom Settings file (for example, ResultsCopyCustomSettings.js) in the appropriate section.
   
   1. The Custom Settings file has separate sections for each module.
   2. TypeAhead settings are located around line 31. See the following screenshot:
      
      
      
4. Modify the setting you pasted into the file, as you see fit.
   
5. Save your custom settings file.

Page Styles - CSS

1. If you are loading any CSS files as part of your modifications, create them and store them in the folder for custom CSS:
   • <SmartHub install root>\<Your>CustomerCustomization\styles, which also contains the CSS files for the Index and Results pages.
     
2. Be sure to save your custom CSS file.

Direct SmartHub to Use Your Custom Results HTML File

Note: Your custom settings file overrides all other settings.

1. SmartHub, by default, loads the file Results.html.
   
2. Once you have made a custom Results HTML file, you must direct SmartHub - specifically your Index HTML file - to load the file instead of the native Results.html file.
   
3. To do this, you need to copy (and modify) a setting from your default Index Page settings file into your custom Index settings file.
   
1. Open the Index page settings file IndexCopyPageSettings.js from the location <SmartHubRoot>\modules\SmartHubResourceLoader\.

2. Copy the following code, found around line 218, into your custom Index settings file:

   Code to modify for redirect

   Copy

      "/modules/O365/SPOAuth.js": {
               "params": {
                   "id": "SPOAuth",
                   "data-rest-uri": SH.RootLevelURL + "services/FederatorService.svc",
                   "data-redirect-uri": SH.RootLevelURL + "Results.html"            }
           },

1. Modify the value "data-redirect-uri" to point to your custom Results HTML file. For example, "data-redirect-uri": SH.RootLevelURL + "CustomResults.html".

2. When SmartHub loads, your Index Page loads its custom setting file which now includes the redirect to your new Custom Results HTML page.

3. In turn, whatever values your Custom Results HTML file contains are also used.

4. Your Custom Results HTML file pulls its settings from its settings file, ResultsPageSetting.js, or else from a custom results settings file, if you have created one.
   

Adding a Custom Version to a Specific File

In order for browsers to cache the SmartHub files for a better performance, we append the SmartHub version to all the files.

In case that, you want to use a custom file, and you don't want that file to be cached by browsers or you want to have a specific version, css/js files supports 'version' parameter.

Example:  

SH.Loader.FilesToLoad = {

    //adding files
        '/modules/my-css.css': {
        'version':'1.0.1'    
    },
        '/modules/my-js.js': {
        'version':'1.0.1'
    },
};

Example: Exclude the SavedQueries Module

Some users prefer not to load certain modules for various reasons, such as eliminating unwanted visual objects in the user interface.

• To exclude a module from loading, locate the module - found within <SmartHubInstallation>/modules/<ModuleName>.

In the following example the SavedQueries module is excluded.

1. The SavedQueries.js file is shown in the /modules/SavedQueries.js. 
   
   
   
2. The following graphic shows our Custom Results Settings file (ResultsCopyCustomSettings.js).
   
3. The path to the Saved Queries module is inserted within brackets [ ] under the "SH.LoaderPathsToExclude =" section (line 9 in the graphic below).

• This prevents the SavedQueries module from loading.