Alberta Compensation Transparency Toolkit

Cross-platform

The Alberta Compensation Transparency Toolkit is a platform-agnostic JavaScript toolkit built to simplify the process of setting up a rich interactive grid for compensation transparency web pages.

Simple

The toolkit eliminates the need for custom programming. It automatically generates a compensation table from the data in a CSV file.

Interactive

The generated table comes with paging, navigation, sorting and filtering functionality. Users can easily browse the data page by page, and search for records by certain criteria.


Figure of how it works
View online sample page

Here are some easy-to-follow steps for using this toolkit. This guide assumes the following prerequisites and access:

  • You are familiar with HTML.
  • You are able to create one or more pages on the website that will be hosting the compensation grid.
  • You are able to generate and to host a CSV (Comma Separated Value) file containing the data.
  • (For CMS users only) You are able to embed script tags in the page.

Overview

Columns on page Columns in CSV Comments
Public Sector Body PublicSectorBody Name of the agency, board, or committee.
Name Name Formatted as Lastname, Firstname.
Position Position  
Year Year Four digits, e.g. 2016.
Compensation Compensation A decimal number that is accurate to two decimal places. Do NOT use any dollar sign or thousand separators (the toolkit will add these automatically).
Other Other Same format as above.
Severance Severance Same format as above.
Attachments ContractAttachment Link to scanned contract. Public accessible PDF file with relative URL e.g. attach/abc.pdf or full URL, however, protocol relative URLs are always advisable: e.g. //www.example.com/attach/abc.pdf.
TerminationAttachment Link to scanned termination agreement. Same requirements as above

Implementation Guide

Host your attachments

Upload your attachment files to your hosting location. Record the URL of each attachment file, as you will need it later on when creating the CSV file. You may use folders to organize files by year or type and/or establishing a simple naming convention to avoid accidental overlaps is advisable.

Create your CSV file

This toolkit requires a CSV file having columns specified above. You can simply download the empty template Excel file, add new rows with your data, and fill in the attachment URLs, then save it as a CSV file. Your finished file should look like this sample CSV file.

Host your CSV file

We suggest naming the file as disclosure.csv and hosting it in the same path as your disclosure page. This is where the toolkit looks for CSV file by default. If the CSV file is hosted in a different location, you will need to provide the URL of the CSV file as explained below.

Modify your disclosure page

Find where you want to embed the table, and insert the lines below.

<div id="grid"> <span class="grid-load-error">There was an error loading the interactive grid. Either one or more 
components are unavailable, or you are not using a supported browser such as Chrome, Firefox, IE9 and greater, Edge or Safari.</span> </div>
<script type="text/javascript" 
  src="//abgov.github.io/ab-compensation-transparency-toolkit/cdn/lib/js/ab-compensation-tools.js">
</script>
Note: the URL above references the latest published version of the toolkit. If you wish to reference a specific version that will not automatically receive fixes, you may reference the list of published versions in the cdn folder, but be sure to reference the URL structure above and just change the filename to the version of your choosing.

If your CSV file does not have the default name or location, insert the lines below instead to explicitly provide the URL. 
<div id="grid"></div>
<script type="text/javascript">
  var csv = "disclosure.csv"; // <-- (Optional) Change to URL of your CSV file.
</script>
<script type="text/javascript" 
  src="//abgov.github.io/ab-compensation-transparency-toolkit/cdn/lib/js/ab-compensation-tools.js">
</script>
Note that optional overrides such as for the CSV URL should be placed before the script that loads ab-compensation-tools.js.

Your web page should be working now.

This toolkit is designed to create the interactive grid component only, at whatever position the lines above are inserted. You will still need to create all surrounding page contents and download links (you may link to the same CSV used in this grid).

Standard text on disclosure page

Public Sector Body Compensation Disclosure

Public sector bodies are now required to post online the names and compensation paid to:

  • all board members
  • employees who earn over $125,000

This is a requirement under the Public Sector Compensation Transparency Act, which applies to:

Learn more about agencies, boards and commissions

Learn more about the Public Sector Compensation Transparency Act

If you want to include the text above, you may insert the code below to the desired location in your disclosure page.

<div id="content">
  <div class="article">
    <h1>Public Sector Body Compensation Disclosure</h1>
    <p>Public sector bodies are now required to post online the names and compensation paid to:</p>
    <ul>
      <li>all board members</li>
      <li>employees who earn over $125,000</li>
    </ul>
    <p>This is a requirement under the <i>Public Sector Compensation Transparency Act</i>, which applies to:</p>
    <ul>
      <li>agencies, boards and commissions governed by the
        <a href="http://www.qp.alberta.ca/574.cfm?page=A31P5.cfm&leg_type=Acts&isbncln=9780779761333&display=html">
          <i>Alberta Public Agencies Governance Act</i></a>
      </li>
      <li><a href="https://www.assembly.ab.ca/links.htm">independent offices of the Legislature</a></li>
      <li>employees of Covenant Health</li>
    </ul>
    <p><a href="http://www.alberta.ca/agency-governance.cfm">Learn more about agencies, boards and commissions</a></p>
    <p><a href="https://www.justice.alberta.ca/programs_services/law/Publications_Library_Law/PublicSectorCompTransAct.aspx">
        Learn more about the <i>Public Sector Compensation Transparency Act</i></a></p>
  </div>
</div>

(Optional) Self-hosting Assets

By default, this toolkit leverages Content Distribution Networks for the script, image and style assets. This section contains more advanced instructions for those who prefer to self-host all toolkit assets. These steps are not required for the system to function, but may in some cases be preferable or required by your website administrator.

Host your CSV file if you have not already, refer to the above section for details.

Setup self-hosted assets

Download and unzip the toolkit package, and upload its contents to the desired path on your web server or as assets in your CMS. The package has three subdirectories:

  • lib/js/ contains the JavaScript files;
  • lib/css/ contains the CSS files and images.
  • lib/jsgrid/ contains resources for the jsgrid library.

Modify your disclosure page

Find where you want to embed the table, insert the lines below. Look for the files in subdirectories specified above. 

<div id="grid"></div>
<script type="text/javascript">
  var csv
    = "disclosure.csv";                    // <-- (Optional) Change to URL of your CSV file.
  var jquery_js
    = "lib/js/jquery-1.8.3.min.js";        // <-- URL of self-hosted jquery-1.8.3.min.js (optional if your site already loads jQuery >= 1.8.3)
  var jsgrid_js
    = "lib/jsgrid/jsgrid.min.js";          // <-- URL of self-hosted jsgrid.min.js
  var papaparse_js
    = "lib/js/papaparse.min.js";           // <-- URL of self-hosted papaparse.js
  var jsgrid_css
    = "lib/jsgrid/jsgrid.min.css";         // <-- URL of self-hosted jsgrid.min.css
  var jsgrid_theme_css
    = "lib/jsgrid/jsgrid-theme.min.css";   // <-- URL of self-hosted jsgrid-theme.min.css
  var grid_css
    = "lib/css/ab-compensation-tools.css"; // <-- URL of self-hosted ab-compensation-tools.css.
</script>
<script type="text/javascript"
  src="js/ab-compensation-tools.js">       // <-- URL of self-hosted ab-compensation-tools.js
</script>

The self-hosted URL variables listed above are all optional. If not included, the toolkit will use to the default CDN link for the corresponding file.

(Advanced) Grid Customization

From release v1.1, the toolkit provides a callback function to customize the grid, e.g. hide a column, change column width, etc. The toolkit does not enable this feature by default, so you can safely ignore this section if not using it.

The mechanism

To enable grid customization, you need to define callback function gridConfigCallback. If the function is defined, the toolkit will invoke it before rendering the grid, with two pass-by-reference arguments.

  • The first argument points to gridConfig, the configuration object of jsgrid library. In the function body, you can modify the configuration referenced by the argument, and the grid will render accordingly.
  • The second argument points to the same jQuery object used by the toolkit, please use it for your jQuery calls to keep the same.

    With the improved compatibility from release v1.2 , the default global $ can be a different version of jQuery or something defined by another library.

Define the callback function

Customization may include many scenarios, and we will only show how to define the callback function. To explore all the possibilities of customization, we recommend you to read jsgrid online document and review the toolkit's source code.

Find where you want to embed the table, and insert the lines below. 

<div id="grid"></div>
<script type="text/javascript">
  var gridConfigCallback = function (config, $) {
    // Make your customizations here
    // Use $ for jQuery calls, e.g. $.fn.jquery;
  };
</script>
<script type="text/javascript" 
  src="//abgov.github.io/ab-compensation-transparency-toolkit/cdn/lib/js/ab-compensation-tools.js">
</script>

Notice:

  • The function should be defined before the script that loads ab-compensation-tools.js. If you use optional overrides such as csv and other variables, define the function in the same script block.
  • The function should not return any value, any not null return value may cause errors.

Help and Debugging

Bugs and other issues can be reported to the GitHub project issue tracker. If you wish to customize the solution or contribute fixes, the master branch will receive more frequent updates and is best suited for local testing and debugging.