Maps Support

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.


  • EngineerCore URL:

  • EngineerMap URL:

  • MapData URL:


Importing your first map

To simplify the creation of your first map site you can download the template file for a preconfigured site and iSheet - “engineerMap Template.hqa”.

Instructions for importing a site template can be found in the HighQ Knowledge Base - Import a site template - Thomson Reuters HighQ Knowledge

Then, instructions for creating the new site from the template can be found here - Creating a site from a template - Thomson Reuters HighQ Knowledge

Once the site is created, edit the Home Page module and click the first panel, then in the Editor ribbon click the “Source” button.

It’s good practise to keep a copy of code in HighQ when making changes as HighQ offers no version history. So, copy all this text into a new text editor/notepad file. Do this by selecting all the text, copying it, and pasting into a new notepad document.

Using the links from the files you uploaded, replace each of the 3 “flag_50i54j53i54h51k53k54.action” links in the code window. So, for engineerCore, go to your 3 new links that you have stored, copy the string of numbers and letters following the “flag_” for engineerCore by double clicking it and pressing Control+C or (right click and Copy). Then, return to your HighQ window, find the string of numbers and letters following “flag_” that appears after <!-- EngineerCore --> highlighted in the snippet below. Then double click to highlight it and paste your updated link over the top.

Repeat this for engineerMap.

Do the same again for the mapData file which appears slightly further down the code.


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

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

<script>

<![CDATA[

engineerMap({

mapElement:'mapContainer1',

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

Once all 3 have been replaced with the appropriate code. Click Ok on the code panel, and then Click Save to run the code and draw your map! You should see 2 buttons allowing you to switch between map layers and the map itself along with a legend.

Testing and Modifying

You can test the map by adding a new record to the iSheet. Go to the iSheets tab and click “Add” in the top left. Type a region name that appears in your map, so for the US you could use “Colorado” and select some data for the other columns. Click “Save” then return to the Home page and you’ll see the name has updated with your new region shaded.

If the region is not shaded as expected, check the region name is spelt correctly by hovering your mouse over the region to see its name in the system and compare it to what you input.


Modifying the iSheet

  • Renaming a choice column will rename the buttons for the “layers” at the top of the name.

  • Additional Choice columns will create additional "layers" on the map.

  • Adding a Hyperlink column will create a new map layer where each region will link to the URL specified in the iSheet.

  • A text field (Single or Multiline) after a Choice column in the View will apply that text to a tooltip when hovering over a region in the map.

  • Changing the color associated with a choice column option when editing the choice column will change the color of the region on the map, for that layer.

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.

  • Open your view again and HighQ will have created an “Sheet view - export XML link” copy this link as you’ll need it in the next step. It will look like “https://www.lawfirmname.com/lawfirm/sheetViewExportXML.action?metaData.siteID=100&metaData.sheetId=100&metaData.sheetViewID=100&metaData.isheetExportType=xml”


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.

The below is the minimum code needed to run engineerMap – the “flag_” links will need to be replaced with your links from the installation section.

Replace the iSheetViewLink with new link HighQ has created for your new view above. Ensure the link has a single quote (‘) before and after and a trailing comma (,) at the end of the line.


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

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

<script>

<![CDATA[

engineerMap({

mapElement:'mapContainer1',

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

iSheetViewLink: 'https://www.lawfirmname.com/lawfirm/sheetViewExportXML.action?metaData.siteID=100&metaData.sheetId=100&metaData.sheetViewID=100&metaData.isheetExportType=xml',

nameColumn: '0',

});

]]>

</script>

<div id="mapContainer1">&nbsp;</div>

Click Ok and then Save and your map should appear.

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

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

  • Open your view again and HighQ will have created an “Sheet view - export XML link” copy this link as you’ll need it in the next step. It will look like “https://www.lawfirmname.com/lawfirm/sheetViewExportXML.action?metaData.siteID=100&metaData.sheetId=100&metaData.sheetViewID=100&metaData.isheetExportType=xml”


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.

The below is the minimum code needed to run engineerMap in choropleth mode – the “flag_” links will need to be replaced with your links from the installation section.

Replace the iSheetViewLink with new link HighQ has created for your new view above. Ensure the link has a single quote (‘) before and after and a trailing comma (,) at the end of the line.


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

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

<script>

<![CDATA[

engineerMap({

mapElement:'mapContainer1',

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

iSheetViewLink: 'https://www.lawfirmname.com/lawfirm/sheetViewExportXML.action?metaData.siteID=100&metaData.sheetId=100&metaData.sheetViewID=100&metaData.isheetExportType=xml',

nameColumn: '0',

isChoropleth: 'true',

});

]]>

</script>

<div id="mapContainer1">&nbsp;</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 lastModified 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.


iSheetViewLink

e.g.

iSheetViewLink: 'https://www.lawfirm.com/law/sheetViewExportXML.action?metaData.siteID=6&metaData.sheetId=117&metaData.sheetViewID=322&metaData.isheetExportType=xml',


Contains the full URL for the iSheet view that contains the data used to color the map and create the links and tooltips.


nameColumn

e.g.

nameColumn: '0',


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.


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.


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 much be added EXACTLY as they are titles and separated by commas. Do not include a space after the comma or the title will not match.


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.

  • '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

  • '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


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


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.

  • '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

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

  • 'none' will remove tooltips


showLegend

default: 'true'

e.g.

showLegend : 'false',


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


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 alphabetically but if another order is required then the choice column in the iSheet must be modified with a number and a space before each choice to determine its order e.g., "1 Low" "2 Medium" '3 High"


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.


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.


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.