Engineer.Map Support

Introduction 

EngineerMap allows the presentation of iSheet data into a map format on HighQ Home or Wiki pages. 

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 map - 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 engineerMap.js (engineerMap.min.js) and engineerCore.js (engineerCore.min.js) 

Download the mapData template file that corresponds to the region your map will display. 

Upload all 3 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 one of the files to upload. Do this two more times for the other files. 

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 of engineerMap become available download the updated engineerMap.js file provided to your local machine. Then, in your HighQ instance, navigate to the System Admin File Library and locate your existing engineerMap.js install. 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 a map to an existing 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 region names – you can call it anything you like but “Regions” or “States” is good practice. 

• At least one “Choice” or “Hyperlink” column to represent your map layers. 

Create your view 

• It’s good practice to create an iSheet view dedicated to the map. Call it Map View to make this clear. 

• Remove the HighQ metadata columns from your view (Created By, Created Date, Modified By, Modified Date). 

• Ensure your Regions column is the first column in the view. 

• Save your view. 

Add to your Home/Wiki page 

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 – the “flag_” links will need to be replaced with your links from the installation section.

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:

<!-- EngineerCore --><script src="./flag/flag_000000000000000000.action"></script> 

<!-- EngineerLegal-plugins --><script src="./flag/flag_000000000000000001.action"></script> 

<div id="mapContainer1">

<script> 

    engineerLegal({

          plugin: 'map',

     container: "mapContainer1", 

          mapData: "./flag/flag_000000000000000002.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 -->
<!-- EngineerMap --><script src="./flag/flag_000000000000000001.action"></script> 

 <!-- EngineerCore --><script src="./flag/flag_000000000000000000.action"></script> 

<div id="mapContainer1">

<script> 

      engineerMap({ 

     mapElement:"mapContainer1", 

        mapData:"./flag/flag_000000000000000002.action", 

        isChoropleth: "true", 

   }); 

</script> 

</div> 

Click Ok and then Save and your map 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"

Density Maps (Choropleth) 

Density maps will show the number of times a State/Region occurs in your iSheet and then link through to a filtered view of the iSheet showing only the results for a clicked region. You’ll need iSheets and either the Home or Wiki modules available in your site. 

• Create an iSheet with at least a ‘Single Line Text” column for your region names – you can call it anything you like but “Regions” or “States” is good practice. 

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

Create your view (please note, the map will not show if your iSheet is empty)

• It’s good practice to create an iSheet view dedicated to the map. Call it Map View to make this clear. 

• Remove the HighQ metadata columns from your view (Created By, Created Date, Modified By, Modified Date). 

• Ensure your Regions column is the first column in the view. 

• Save your view. 

Add to your Home/Wiki page 

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

      isChoropleth: 'true',

Click Ok and then Save and your list should appear. 

Modifying Map Options 

The code for each map can be modified by setting map options, these are the lines of code ending in a comma (,) between the curly braces ({}) after “engineerMap”. Each line changes or provides information to a different component of the map. 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 map 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 color of regions that have no data in your iSheet from the default black to red we can use the defaultMapColor option. 

We would add a new line to the code above, add our option, then a colon (:) then a single quote (‘) then color (you can use any HTML accepted color so ‘red’ or ‘#FF0000’) then another single quote and comma. 

        isChoropleth: 'true',  

        defaultMapColor: ‘red’, 

   }); 

FAQs 

How do I sort the legend? 

It's possible to set the sort order of items in the legend using the sortLegend advanced option.

How do add or remove certain States or Regions? 

Removing data for a region from the iSheet will set the region to its defaultMapColor but to remove a region completely from the map or to add a new region you'll need a new mapData file. Please Contact us for more details.

How do I change the color of a region? 

Changing the color for a shaded region in the map is accomplished by editing the iSheet connected to the map. Edit the choice column for the specific layer where you'd like to change the color then select the choice that matches the region you'd like to change. Pick a new color and click save. The map will reflect your new color after a page refresh. You can also use the advanced options to set the hoverMapColor, otherMapColor, and defaultMapColor 

How do I make the map bigger/smaller? 

The map will resize according to the screen size of the device viewing it but you can also use the HighQ page editor to reduce the size of the Content Editor Panel.

How do change the tooltips? 

The tooltipColumn advanced option contains details of how to set the options for tooltips on the map.

Can I show when the map was last updated? 

The advanced option mapLastModified contains instructions for adding this to the legend on your map.

Can I have multiple maps on the same page? 

Yes! Follow the instructions for adding a map to a HighQ site then ensure the mapElement required option on your new map is different to any other mapElements on the page. This could mean counting up to mapContainer2 for your second map. You must also update the line of code <div id="mapContainer2">&nbsp;</div> to match.

Advanced Configuration 

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

Required Options 

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

container

e.g.

container:'mapContainer1', 

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

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

mapData 

e.g.

mapData:'./flag/flag_50l54i48i54j54h54h56.action', 

Points to the file containing the JSON data that builds the map shapes. If you have multiple maps installed in your instance, you'll need to point to the correct mapData JSON file for the map you're hoping to display.

Configuration Options

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

nameColumn 

e.g.

nameColumn: '2', 

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

useSelector 

e.g.

useSelector : 'Risk Level,Enforcement', 

Allows you to specify which columns in the iSheet will create layers on the map if not ALL choice or hyperlink columns are required as map layers/buttons. Column names must be added EXACTLY as they are titled and separated by commas. Do not include a space after the comma or the title will not match. - NOTE: At present you must remove commas from column titles to use this useSelector option.

hideErrors

e.g.

hideErrors: 'true',

As of May 2024 EngineerMap will now show an errors button if rows are found in the iSheet that do not match a country/region/state. This will help ensure that regions are not missed. Setting this option to true will hide the errors button.

printRegions

e.g.

printRegions: 'true',

When set to the true this option will print a list of valid region names for the current mapData template file to the JavaScript console (accessed with F12 or CTRL + SHIFT + J)

borderColor 

e.g.

borderColor : 'black', 

Sets the border color around each region on the map. Accepts any HTML accepted color so ‘red’ or ‘#FF0000’.

fontSize

e.g.

fontSize: '12px', 

Sets the font size of labels on the map in pixels. Note that larger font sizes can impact mobile views more dramatically than desktop.

lineSize

e.g.

lineSize : '2', 

Sets the size of lines around each region on the map in pixels. Note that larger fint sizes can impact mobile views more dramitically than desktop.

hoverMapColor 

e.g.

hoverMapColor : 'none', 

Sets the color of a region when a mouse cursor is hovered over it. Accepts any HTML accepted color so ‘red’ or ‘#FF0000’. To disable the hover color change, set 'none'.

otherMapColor 

e.g.

otherMapColor : '#3d54d3', 

Sets the color of a region when a URL is set in a hyperlink type column. Sets the color for a choice column that has 'other' picked as its value. When isChoropleth is set to true this governs the base color of region shading. Accepts any HTML accepted color so ‘red’ or ‘#FF0000’.

defaultMapColor 

e.g.

defaultMapColor : 'gray', 

Sets the color for a region when no data is present in the iSheet. Accepts any HTML accepted color so ‘red’ or ‘#FF0000’.

mapNormalText 

e.g.

mapNormalText : 'brown', 

Sets the color for text labels in a region. Accepts any HTML accepted color so ‘red’ or ‘#FF0000’.

mapHoverText 

e.g.

mapHoverText : 'brown', 

Sets the color for text labels in a region when a mouse cursor is hovered over them. Accepts any HTML accepted color so ‘red’ or ‘#FF0000’.

mapInverseText 

e.g.

mapInverseText : 'blue', 

Sets the color for any lines used to connect region labels outside that sit outside of their region (i.e. because the region is too small for an internal label, on mobile view this will also set the text color of external region labels. Accepts any HTML accepted color so ‘red’ or ‘#FF0000’.

otherTitle 

e.g.

otherTitle : 'Conditional', 

Sets the label in the legend for how any items input into the choice column under the "other" grouping will be displayed. If, for example, a region could be high or low risk, but some regions have a conditional nature such as "Low pending new legislation" then the other option could be used to capture this.

defaultTitle 

e.g.

defaultTitle : 'Not surveyed', 

Sets the label in the legend for regions that have no data, perhaps because they are excluded or are pending.

linkTitle 

e.g.

linkTitle : 'Documents Available', 

Sets the label in the legend for regions that have a URL populated in a hyperlink column in the iSheet, i.e., if each region links to its legislation guidance in a wiki page, then populated regions will be grouped under this legend name.

mapLinks 

e.g.

mapLinks : 'search', 

Determines what happens when clicking on a region on the map.

• 'isheet' will link to the iSheet record containing the data for the region

• 'viewItem' will open the HighQ view item modal window for the record region

• 'print' will open the HighQ print view for the iSheet record containing data for the region

• 'none' will disable linking

• 'search' will run a search for the region name in the iSheet potentially returning multiple records for that region

• 'override' allows a specific link to be set for all regions using the maplinkOveride option

+ There are additional mapLinks options available if EngineerTable is used in the Table Options section below.

mapLinkOverride 

e.g.

mapLinkOverride : 'https://www.google.com', 

If the mapLinks option is set to 'override' then this option will cause all regions to link to a single specific URL (such as another HighQ page, external link, or other map).

hyperlinkColumn

e.g.

hyperlinkColumn: '5', 

Can be set to the column index (The first column is column 0 the second is 1, etc.) of a Hyperlink type column. This will apply any link found for each row to the region in the map causing a click on that region to take the user to that page. This allows will prevent that hyperlink column from being added the layer menu/buttons.

mapLinkTab 

e.g.

mapLinkTab : 'self', 

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

labelText

e.g.

labelText : 'none', 

Determines if regions should be labelled with their initials ('initial') or none ('none'). labelText is available from version 3.1.2 but lblText will not be removed. (June 2024).

hideUnusedLabels

e.g.

hideUnusedLabels: 'true', 

If a region isn't present in the iSheet data then hide its label to declutter the map.

tooltipColumn 

e.g.

tooltipColumn : '3', 

Determines if regions should have tooltips when a mouse cursor is hovered over them.

• '0' will set the tooltips to display the value from the first column on the left in the iSheet (in most cases this will be the region name)

• Any number will display tooltips from that column (caution, a number exceeding the number of columns may cause the map to fail to display)

• 'dynamic' will display a value from the column next to the choice column for the currently selected view. The iSheet should be structured with a single or multiline text column after each choice/hyperlink column

• 'value' will display the choice column value for the region

• 'none' will remove tooltips

If using the density map (isChoropleth) then setting a column number will only display the region name. Setting 'value' will append the number of times that region appears in the iSheet to the tooltip.

showLegend 

e.g.

showLegend : 'false', 

Setting this to anything other than 'true' will hide the legend from below the map.  

showLegendDefault 

e.g.

showLegendDefault : 'false', 

Setting this to anything other than 'true' will hide the default "Pending" (or however configured with the defaultTitle option) entity from the legend.

legendTitle 

e.g.

legendTitle : 'Risk: ', 

This option will prepend the input text before your legend on the first line. This will default to blank. Please note, if your map contains multiple layers showing different statuses/risks then this text will not change when the user switched between map layers.

sortLegend 

e.g.

sortLegend : 'true', 

Allows for a specific sort order of options in the map legend. By default ('false') the legend will sort based on the order the items appear in the iSheet view. 

• 'true' required the iSheet choice column to be modified with a number and a space before each choice to determine its order e.g., "1 Low" "2 Medium" '3 High"

• 'alphabetical' will sort the legend alphabetically with the defaultTitle added last

Setting sortLegend to 'true' will then remove the preceding numbers and sort the legend appropriately.

mapLastModified 

e.g.

mapLastModified : 'true', 

Appends the latest 'Last modified date' from the iSheet "Last modified" date column to the map legend. The "Last modified date" must be added to the iSheet view for the map to display this. If using tooltips, it may make sense to make Last modified date the first column in the iSheet view (position 0) so that it does not appear in any tooltips. In that case 'nameColumn' should be set to 1 or the new column position of the list of regions.

useLayerMenu 

e.g.

useLayerMenu : 'true', 

Switches from generating a button for each map layer to using a dropdown menu to conserve screen space.

buttonText 

e.g.

buttonText : 'Quick View', 

When useLayerMenu is set to 'true' then buttonText will set the dropdown button text.

quickViewSearchEnabled 

e.g.

quickViewSearchEnabled : 'true', 

When useLayerMenu is set to 'true' then 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 useLayerMenu is set to 'true' and quickViewSearchEnabled is set to 'true' then setting this value will determine how many milliseconds the system will wait before executing the type ahead search.

Density Maps (Choropleth)

The isChropleth option configures the map to count the number of times a region appears in your iSheet and then shades the region lighter or darker relative to the average.

isChoropleth

e.g.

isChoropleth : 'true',

Configures the map to count the number of occurrences of a region name and shade the region based on this number.

choroplethGroupsNumber 

e.g.

choroplethGroupsNumber : '4',

When "isChoropleth" is set to true this will determine the number of groups or color density bands that the map will display. More groups will result in greater granularity but smaller visible differences in color strength between groups.

choroplethLegendTitle

e.g.

choroplethLegendTitle : 'Cases', 

When "isChoropleth" is set to true this will set the title in the map legend. If your map is showing number of cases in each region then you would change this to 'Cases' as above.

choroplethBaseBrightness

e.g.

choroplethBaseBrightness : '120', 

When "isChoropleth" is set to true this will set the brightness for the base color for the map (color set using the otherMapColor option). For a brighter color like red, reducing the choroplethBaseBrightness option to 120 may make differentiating color differences between groups easier.

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

mapLinks

e.g.

mapLinks: 'table', 

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

mapLinks: 'table',     - will show the details for the clicked region in EngineerTable

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

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

tableAllColumns

e.g.

tableAllColumns: 'true', 

By default, when clicking on a region in the map, the table below will only show the column relating to the currently selected layer (choice column). If you have several choice columns in your iSheet but want the table to display the full iSheet row set tableAllColumns to true.

compareLineSize

e.g.

compareLineSize: '10', 

When using panelLinks: table, compare, or filter, this option sets the width of the border around a region when it is clicked and added to the comparison view, a smaller number will be useful for maps that don't take up the full page width.

compareBorderColor

e.g.

compareBorderColor: 'orange', 

When using panelLinks: table, compare, or filter, this option sets the color of the border around a region when it is clicked and added to the comparison view.

Configuring EngineerTable below your map

By default, EngineerTable will load directly below EngineerMap 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 then 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 Map to avoid confusion.

mapLinks: 'table', 

      tableOptions: {

             recordLinks: 'viewItem',

             transposeTable: 'true',

      },

Overlays

EngineerMap can display specific location data on top of the map to represent office locations, real estate holdings, project delivery teams, etc. This requires a separate iSheet to be created with with a view that contains the below columns:

1 Single Line Text column for the location name

1 Single Line Text column for the location Latitude called either Lat or Latitude*

1 Single Line Text columns for the location Longitude called either Long or Longitude*

Optional: 1 Choice column that can be used to set the color of the location icon on the map

Options 1 Hyperlink column that can be used to set a link that will be opened when the point is clicked

Latitude and Longitude must be added for each location in Decimal Degrees e.g:

Name       |   Latitude     |   Longitude

Client1     |    41.4033    |    -2.1740

Check that the first number in your latitude coordinate is between -90 and 90.

Check that the first number in your longitude coordinate is between -180 and 180.

EngineerMap is not able to lookup Zip/Postcodes at this time but Google is able to return lat/long when searching for a city name.

Once the iSheet view is created, add a link to it on the same home/wiki page as your map code (more help here: Add a link to a page with the rich text editor - Thomson Reuters HighQ Knowledge)

Once the link is created, add a new class name to that link by locating this bit of HTML: 

class="CKContextLink" and adding a space inside the last double quote and adding "overlay-link1" so: class="CKContextLink overlay-link1"

Lastly add this option to your map:

overlayViewLink: engineercore_getLinkByClass("overlay-link1"),

Note that this option is not surrounded by single quotes like most others and double quotes are used around the link class name.

Overlay Options 

isOverlayChoropleth

e.g.

isOverlayChoropleth : 'true',

Configures the overlay to count the number of occurrences of an exact match of latitude and longitude and shade the region based on this number counted. 

overlayPointSize

e.g.

overlayPointSize: '2',

Configures the relative size of the overlay points. With maps with more tightly packed points, consider a lower umber such as 2 or 3 to better separate them.

overlayPointColor

e.g.

overlayPointColor: 'blue',

Configures the default color of the overlay points if no status column color exists. Will also be the base color for choropleth points.

overlayShape

e.g.

overlayShape: 'star',

Configures the shape of the overlay points options are: circle, square, star, triangle

overlayLinks 

e.g.

overlayLinks: 'isheet', 

Determines what happens when clicking on an overlay point on the map.

• 'isheet' will link to the iSheet record containing the data for the region

• 'print' will open the HighQ print view for the iSheet record containing data for the region

• 'false' will disable linking

• 'table' will display the row for the overlay point in a table below the map (if EngineerTable is installed and configured)

• 'compare' will add the row for the overlay point to a comparison table below the map (if EngineerTable is installed and configured)

• 'filter' will initially display all rows for the overlay points in a comparison table below the map then (if EngineerTable is installed and configured)