Engineer.List Support

Introduction 

EngineerList allows the presentation of iSheet data into an attractive panel layout in HighQ Home or Wiki pages. 

Please note that engineerList is designed to accompany Engineer.Table to create dynamic comparison tables, but can also be used without this to link to iSheets and tasks.

Prerequisites 

• HighQ Collaborate 

• A System Admin Account is required to install the software. (See Installation) 

• Scripting Enabled on your HighQ instance or allowed for each user who will be editing a page containing a list - more details are available in the HighQ Knowledge base regarding this: Enable users to bypass XSS protection and add custom Javascript to a - Thomson Reuters HighQ Knowledge  

Please note: Engineer.Legal plugins do not currently support System Dashboards or "Custom Pages" due to limitations in these modules

Installation

If this is your first Engineer Legal plugin you'll need to create your engineerLegal-plugins file. Instructions for this will be in your welcome email.

Download engineerList.js, engineerCore.js

Upload both files to your HighQ instance in the System Admin File Library - This can be reached by clicking the profile picture/icon in the top right of your HighQ Instance > System Admin > File Library. Click “Add new file” and select each of the files to upload.

Copy each of the URLs for the uploaded files, we'll need to reference these in your engineerLegal-plugins file. DO NOT use the Get Link/Public link column, this will make your file publicly accessible. 

Updating your version

When new versions become available download the updated js files provided. Then, in your HighQ instance, navigate to the System Admin File Library and locate your existing engineerList.js file. Clicking on the file ID to the left of this filename will open the "Update file" page, allowing you to replace the older file with the updated one you just downloaded. BEWARE: this overwrite happens immediately upon clicking Save and is irreversible. Ensure you are overwriting the correct file by double checking the file name field before clicking Choose File. It is advisable to always have backups of all files stored in the System Admin File Library.

After updating the file it can sometimes take a a little while to update for all users if their browsers are caching older code, if any user reports issues advising them to clear their cache using CTRL + SHIFT + R to do a hard refresh of the page.

Adding Engineer.List to a HighQ site 

You’ll need iSheets and either the Home or Wiki modules available in your site. 

Create an iSheet with the below columns: 

• A ‘Single Line Text” column for your panel names

• At least one “Choice” column to represent each of the "status" layers for your panels - e.g. whether or not a Regulation applies in this region, or the compliance status of each corporate entity

• Optional: Image column for flags or other images

Create a view

Create a new view your iSheet called Quick View. 

Ensure your panel name column is the first column in the view, followed by your image column (if used), single line text group column (if used), then your choice columns.

Save your view.

Add to your Home/Wiki page 

Go to the Home or Wiki page where you would like your list to appear. Edit the panel and select Source view. 

Use the HighQ editor to add a link to your iSheet view (more help here: Add a link to a page with the rich text editor - Thomson Reuters HighQ Knowledge)

Once you've created your link, open the panel in Source view and paste in the below minimum code needed to run engineerList – the “flag_” links will need to be replaced with your links from the installation section. Ensure there is no space before the closing "</script>" tag when you edit these as this can cause the chart to load multiple times.

As of the new version 4 there is a new, simplified method to load each plugin, allowing quick switching between different plugin types, you only need to include:

<div id="listContainer1"><script>

    engineerLegal({

      container: 'listContainer1',
      plugin: 'list',

    });

  </script>
<!-- EngineerLegal-plugins--><script src="./flag/flag_50i54j53i54h51k53k54.action"></script>
<!--EngineerCore--><script src="./flag/flag_50l53n55j49j57k51i50.action"></script>
</div>

the old method of loading a plugin is still supported, please contact us to upgrade rather that using the below deprecated method:

<!-- DEPRECATED CODE -->
<div id="listContainer1"><script>

    engineerList({

      container: 'listContainer1',

    });

  </script><!-- EngineerCore --><script src="./flag/flag_50i54j53i54h51k53k54.action"></script><!--EngineerList--><script src="./flag/flag_50l53n55j49j57k51i50.action"></script></div>

Click Ok and then Save and your list should appear. 

You can hide the link to your iSheet view if you don't want it to be visible by opening the Source view again, and locating this bit of HTML: 

class="CKContextLink" and adding a space inside the last double quote and adding the word "hidden" so: class="CKContextLink hidden"

Displaying a Count or Sum

EngineerList can be used to show the number of times a State/Region/Entity occurs in your iSheet. It can then link through to a filtered view of the iSheet showing only the matching rows when a panel is clicked. You’ll need iSheets and either the Home or Wiki modules available in your site. 

• Create an iSheet with at least a ‘Choice” column that will be show on your panels, the number of occurrences of this choice will be show on each panel.

• You can add any other columns you need after the choice column above; perhaps to show information about each case, property, or claimant in the portfolio. 

Create your views 

When totaling the data in our iSheet we need to load ALL the rows then do the sum, so we want to make our "Quick View" as small as possible, this means just the name column should be used in this view. Your iSheet View can then contain all associated data.

• Create a new view of your iSheet called Quick View. 

• Include only your Choice column containing values you want to count.

• Save your view.

• If you want to show more/different data when your panels are clicked, create a new view called "iSheet View" and ensure your panel name column is the first column, add any other columns you want to display after this.

Add to your Home/Wiki page 

Use the above method to add engineerList to your page then we enable "choropleth" (many colors) mode by adding the below option on new line after plugin:'list', (for more details see the Modifying Options section below):

      isChoropleth: 'true',

Click Ok and then Save and your list should appear. 

Modifying Options 

The code for each list can be modified by setting options, these are the lines of code ending in a comma (,) between the curly braces ({}) after “engineerLegal”. Each line changes or provides information to a different component of the list. Details of all the options available are listed in the Advanced Configuration section of this guide. 

To add a new option, add a new line after the last comma and before the last curly brace and add your option line as below. 

Warning: HighQ does not keep a version history of your edits to code in Home pages so it's good practice you save your code into another window such as notepad before making changes in case you need to roll back.  

        nameColumn: '0', 

        isChoropleth: 'true', <<ADD NEW LINE HERE>> 

   }); 

For example, if you wanted to change the text on the button that switches between your choice columns we can use the buttonText option. 

We would add a new line to the code above, add our option, then a colon (:) then a single quote (‘) then your new button text then another single quote and comma. 

        isChoropleth: 'true',  

        buttonText: 'Select Layer', 

   }); 

FAQs 

Can I have multiple lists on the same page? 

Yes! Follow the instructions for adding a list to a HighQ site above then ensure the "container" required option on your new list is different to any other containers on the page. This could mean counting up to listContainer2 for your second list etc. You must also update the line of HTML <div id="listContainer2"> to match.

Advanced Configuration 

This section lists all the possible options that can be used to modify the standard behavior of the list. See “Modifying Options” section for instructions on using these. 

Required Options 

The below options MUST be included for the list to load.

container

e.g.

container:'listContainer1', 

Tells the code where you want the list to appear on your page. It requires a corresponding HTML element similar to <div id="listContainer1">&nbsp;</div>

 somewhere on the page. This div element can use any term between the quotes in the id= attribute as long as it corresponds exactly with the container option value. 

Configuration Options 

The below options can be used to modify the behavior or look and feel of the list. They do not need to be set and can be removed to return them to their defaults.

nameColumn 

e.g.

nameColumn: '0', 

Tells the code which column in your Quick View AND iSheet View contains the list of panel names. The first column is column 0 the second is 1, etc. Normally the first column, 0, will contain these names but if you are linking to a data set that must be formatted differently this value will need to updated for the list to generate.

flagColumn 

e.g.

flagColumn: 'false', 

Tells the code which column in your data contains the an Image column with the images used to display on the panels. The first column is column 0 the second is 1, etc. If you wish to hide the images on the panels this must be set to false. By default engineerList will display the leftmost Image column from your Quick View.

groupColumn 

e.g.

groupColumn: '2', 

Tells the code which column in your data contains the single line text or choice column that will be used to create groups of panels, this could be by continent, corporate entity, or case type. The first column is column 0 the second is 1, etc.

Setting this to 'status' will group the panel by the status pills of the currently selected iSheet column.

hideGroupColumn

e.g.

hideGroupColumn: 'false', 

By default, if your group column is a choice column type then it is removed from the dropdown menu (i.e. if we group by continent, then it's unlikely we'd want the user to see the continent option in the menu). However, in a real estate portfolio it might be helpful to group by property status and also show the lease status pill.

otherColumns 

e.g.

otherColumns: '4,5', 

Displays the column header and value of other columns from your data on the panel body. To display multiple column add their column position in your view here in a comma separated list. The first column is column 0 the second is 1, etc.

showOtherColumnHeaders

e.g.

showOtherColumnHeaders: 'false', 

Setting this to false will remove the iSheet column heading before the colon when using the otherColumns option above.

colorPanelBackground

e.g.

colorPanelBackground: 'true', 

Setting this to true will apply the colors from your choice column to the entire panel background, not just the status pill

imageWidth

e.g.

imageWidth: '40px', 

Sets a width for the images displayed in each panel if and image column is found in the iSheet and flagColumn is not set to 'false'

titleLocation

e.g.

titleLocation: 'above', 

Choose where the name of the panel should appear in relation to the panel image, accepted options:

titleLocation: 'above',

titleLocation: 'below',

titleLocation: 'right',

panelLinks

e.g.

panelLinks: 'isheet', 

Add an click action to each panel that can perform one of several actions depending on the configuration option:

panelLinks: 'viewItem',     - will open the HighQ view item modal window for the record selected

panelLinks: 'print',            - will open the HighQ print preview pane for the iSheet record selected

panelLinks: 'isheet',        - will navigate to the iSheet view filtered to just show the record selected

panelLinks: 'search',        - will navigate to the iSheet view and search it for the value of the name on the panel

panelLinks: 'default',         - will navigate to the iSheet of the record selected but the default view instead of the view chosen for the table

Please note, additional panelLinks options are listed further down the page if you have EngineerTable installed.

filterPanels

e.g.

filterPanels: 'true',
filterPanelsPlaceholder: 'Search Countries',
filterPanelsButtonText: 'Search',
filterPanelsClearText: 'Reset',

When set to true, adds a filter text box above your List allowing a search across the panel text

filterGroups

e.g.

filterGroups: 'true',
filterGroupsPlaceholder: 'Search Regions',
filterGroupsButtonText: 'Search',
filterPanelsClearText: 'Reset',

When set to true and when groupColumn is set, adds a filter text box above your List allowing a search across the group headers

singleColumn

e.g.

singleColumn: 'true', 

When set to true, forces the panels to display in a single column instead of dynamically resizing. Great for using engineerList as a single column widget.

collapsibleGroups

e.g.

collapsibleGroups: 'true', 

When set to true the user is able to click a carat next to the Group headers above each panel group to open and close them. The default open/close configuration is set with groupCollapseDefault.

groupCollapseDefault

e.g.

groupCollapseDefault: 'open', 

When collapsibleGroups is set to true this determines the starting position of the groups. By default "first" is set, meaning the first group tab is expanded and the rest are closed. 'open' means all groups are expanded but are able to be closed
'closed' means all groups are closed and only the header names are visible, but can be clicked to be opened.

taskSearch

e.g.

taskSearch: '0', 

When set to a number corresponding to a column in the iSheet, clicking on a panel will open the HighQ site Tasks module and pre-filter the results based on the value in the column for this panel. If the column contains a matter number, for example, then all tasks for that matter will be displayed.

linkTab

e.g.

linkTab: 'self', 

Determines if links from a clicked panel should open in the same tab ('self') or a new tab ('blank').

buttonText 

e.g.

buttonText : 'Select Column', 

Sets the button text on the dropdown button that switches between iSheet choice columns.

quickViewSearchEnabled 

e.g.

quickViewSearchEnabled : 'false', 

Setting this to true will enable a type ahead search box in the layer dropdown menu to locate a view in a long list.

searchDelay 

e.g.

searchDelay : '300', 

When quickViewSearchEnabled is set to 'true' then setting this value will determine how many milliseconds the system will wait before executing the type ahead search.

isChoropleth

e.g.

isChoropleth : 'true',

Configures the list to count the number of occurrences of a name. See the "Displaying Totals" section of this guide for more details.

sumColumn 

e.g.

sumColumn : '2', 

Tells the code which column in your data contains a numeric column that will be used to show the total of that value for each occurrence of the nameColumn value like HighQ's KPI cards.

itemsPerColumnLimit

e.g.

itemsPerColumnLimit: '1', 

panelLimit

e.g.

panelLimit: '5', 

heroPanels

e.g.

heroPanels: '1', 

Table Options

Using these options requires engineerTable to be installed in your HighQ instance - Contact us for more details.

Please note: As of version 4 there is no longer any need to add the flag URL for EngineerTable into the page

panelLinks

e.g.

panelLinks: 'table', 

Add a click action to each panel that can perform one of several actions depending on the configuration option:

panelLinks: 'table',     - will show the details for the clicked panel in EngineerTable

panelLinks: 'compare',      - will show the details for the clicked panel in EngineerTable along with any previous regions clicked, clicking a region again will remove it

panelLinks: 'filter',     - will show all panel details in EngineerTable then acts like 'compare' above thereafter

Ensure you only have one panelLinks option. Once one of the above options is set, by default, Engineer Table will load directly below Engineer List in its default configuration, if you wish to make changes this table then you'll need to to add some options from the Engineer Table documentation and embed them between the curly braces of "tableOptions: { }," like in the example below. Any options that apply to this table must be within the braces. It's a good idea to add these options after all your options that apply to Engineer List to avoid confusion.

panelLinks: 'table', 

      tableOptions: {

             recordLinks: 'viewItem',

             transposeTable: 'true',

      },

showScrollButton

e.g.

showScrollButton: 'false', 

When a panel is clicked and EngineerTable is loaded below list an off the screen then a button will float in the bottom right of the screen allowing the user to quick scroll down to their comparison table. Setting this to false will disable this feature.

scrollButtonText

e.g.

scrollButtonText: 'View Comparison Table', 

This feature requires engineerTable to be installed in your HighQ instance - Contact us for more details.

Changes the text on the button that is at the bottom of the page when the comparison table is active but currently below the view port of the user's browser.

showTableFilters

e.g.

showTableFilters: 'false', 

This feature requires engineerTable to be installed in your HighQ instance - Contact us for more details.

This feature enables a filters panel below EngineerList that allows the end user to select which columns of data they would like to see in the comparison table below. It defaults to a collapsed section that can be expanded by clicking the Filters button:

showTableFilters: 'collapse',     - default, hides the filters but allows the user to open a filters menu

showTableFilters: 'true',            - displays the filters whenever a panel is added to the comparison table

showTableFilters: 'false',        - hides the filter options

Please note, if a user unchecks ALL filters then the entire table will be shown, just as if all the boxes were ticked.

clickColor

e.g.

clickColor: 'red', 

When a panel is clicked and added to the table this option allows setting of the panel highlight color

groupFilters

e.g.

groupFilters: 'true', 

Using a HighQ SCORE column type in your iSheet view data will create groups of columns in the filters section and in EngineerTable when it is generated. All columns between 2 SCORE columns will be grouped together. When setting groupFilters to true, the filters section will only generate a checkbox for each section. When checking this box ALL the columns within the checked section will be added to the comparison table.

filterText

e.g.

filterText: 'Filter Table', 

This feature requires engineerTable to be installed in your HighQ instance - Contact us for more details.

When showTableFilters is set to 'collapse' this option changes the text on the button that is generated above the comparison table that allows filtering the iSheet column that a user is interested in.

filtersSearchEnabled

e.g.

quickViewSearchEnabled : 'true', 

Setting this to true will enable a type ahead search box in the filter dropdown menu.