Engineer.Map Support

Installation Documentation, Advanced Configuration + FAQs

Index >

Introduction 

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

  

Prerequisites 

  

Installation

Download engineerMap.zip and extract the contents (engineerMap.js, engineerCore.js) 

Download the mapData 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 3 uploaded files, we'll need to reference these when using the map in each HighQ site. Right click on the file in the filename column and click copy link then paste the link into a new text or Word document to keep them handy, you can use the format below. 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: 


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


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

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

<div id="mapContainer1">

<script> 

      engineerMap({ 

     mapElement:"mapContainer1", 

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

   }); 

</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 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 your view (please note, the map will not show if your iSheet is empty)


Add to your Home/Wiki page 

Go to the Home or Wiki page where you would like your map 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.

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

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

<div id="mapContainer1">

<script> 

    <![CDATA[ 

      engineerMap({ 

     mapElement:"mapContainer1", 

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

        isChoropleth: "true", 

   }); 

]]> 

</script> 

</div> 

 

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


mapElement 

e.g.

mapElement:'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 element can use any term between the quotes in the id= attribute as long as it corresponds exactly with the mapElement 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.


isChoropleth

default: 'false'

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. See the "Density Maps (Choropleth)" section of this guide for more details.


choroplethGroupsNumber 

default: '3'

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

default: 'Occurrences'

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

default: '150'

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.


useSelector 

defaults to selecting all Choice and Hyperlink columns in the iSheet view

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


borderColor 

default: 'white'

e.g.

borderColor : 'black', 


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


fontSize

default: '10px'

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

default: '1.5'

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 

default: 'lightgrey'

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 

default: 'slategrey'

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 

default: 'black'

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 

default: 'white'

e.g.

mapNormalText : 'brown', 


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


mapHoverText 

default: 'darkslategrey'

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 

default: 'lightslategrey'

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 

default: 'Other'

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 

default: 'Pending'

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 

default: 'Pending'

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 

default: 'isheet'

e.g.

mapLinks : 'search', 


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


mapLinkOverride 

default: none

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

default: false

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 

default: 'blank'

e.g.

mapLinkTab : 'self', 


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


lblText 

default: 'initial'

e.g.

lblText : 'none', 


Determines if regions should be labelled with their initials ('initial') or none ('none').


tooltipColumn 

default: 'none'

e.g.

tooltipColumn : '3', 


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


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 

default: 'true'

e.g.

showLegend : 'false', 


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


showLegendDefault 

default: 'true'

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 

default: ' '

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 

default: 'false'

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. 


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


mapLastModified 

default: 'false'

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.


showTable 

default: 'false'

e.g.

showTable : 'true', 


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

Enables a dynamic table below the map that will display a subset of the data corresponding to the currently select map view.


By default, Engineer Table will load directly below Engineer Map 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.


showTable : 'true', 

      tableOptions: {

             recordLinks: 'viewItem',

             transposeTable: 'true',

      },



compareMode 

default: 'false'

e.g.

compareMode : 'true', 


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

Enables a dynamic table below the the map that will display a subset of the data corresponding to the currently select map view. Clicking on a region will filter the table to only show data corresponding to that region, clicking again will remove the filter. Clicking another region will add the data for that region to the table allowing for simple comparison of regions.


filterCompareMode

default: 'false'

e.g.

filterCompareMode: 'true', 


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

This functions similarly to compareMode above, the only difference being that the generated comparison table will only show rows corresponding to currently selected choice column from the layer menu or buttons above the map.


compareLineSize

default: '8'

e.g.

compareLineSize: '10', 


When using compareMode 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

default: '#e40fda'

e.g.

compareBorderColor: 'orange', 


When using compareMode this option sets the color of the border around a region when it is clicked and added to the comparison view.


useLayerMenu 

default: 'false'

e.g.

useLayerMenu : 'true', 


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


buttonText 

default: 'Select Layer'

e.g.

buttonText : 'Quick View', 


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


quickViewSearchEnabled 

default: 'false'

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 

default: '500'

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.


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

default: 'false'

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

default: '10'

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

default: '#000'

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

default: 'circle'

e.g.

overlayShape: 'star',


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



overlayShape

default: 'circle'

e.g.

overlayShape: 'star',


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


overlayLinks 

default: 'false'

e.g.

overlayLinks: 'isheet', 


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