Suzanne Pierce should make software executable by others
Details on how to do this task: Make software executable by others
Appendix D: Extending Aquiferium
The Aquiferium has been developed such that it is relatively easy to update the data used by the current design of the data interactive components and the visual content. However, extending the application by adding new data to the map or wiring up additional map tile services is a somewhat more complicated procedure that will require some knowledge of JavaScript and current web development workflows. Familiarity with the AngularJS framework is also beneficial but not necessarily required. The Aquiferium application must be recompiled after any changes are made to the code base. This document shows step by step instructions for how to extend the mapping services, add additional geodata, and access additional third party resources that describe in detail how to do additional modifications to the map capabilities. To get started, you will need to launch your IDE or text editor of choice and open the file located at //eaa-aquiferium/app/scripts/directives/leaflet-directive.js.
This file contains the code for the entirety of the mapping capability within Aquiferium. It is an Angular directive, which is essentially a way for JavaScript developers to create new or customized components that can be added to a web application using simple HTML tag syntax. In this case, if you were to open the file located at //eaa-aquiferium/app/views/geography.html and look at line 3 you will see the following HTML
code:
<leaflet-map id="map" class="div-fixed z-100" display-recharge- panel="displayRechargePanel()" display-wells-panel="displayWellsPanel()" display- springs-panel="displaySpringsPanel()"></leaflet-map>
Through the use of the Angular directive, any web app developer with access to your directive code file can use it in their project. Simply include it in the framework as a dependency and use the above HTML code snippet alongside the appropriate CSS code. In fact, most of the code snippet is telling the Angular framework how to respond to links specific to the Aquiferium. Therefore, a developer, who only wanted to utilize the mapping capability, could use the following simplified code snippet:
<leaflet-map id="map"></leaflet-map>
Note: All the above code snippets require th CSS code below to also be present within the web application
(the web developer can customize the CSS to their needs):
- map {
width: 100%;
height: 100%;
top: 5% /* Offsets navigation bar */;
right: 0;
bottom: 0;
left: 0;
}
The inclusion of these three pieces – the directive file, the HTML code and the corresponding CSS code - are all that is required to repurpose the mapping capabilities in Aquiferium into any other AngularJS application.
Preparing the Codebase for Development The process for recompiling the Aquiferium codebase is relatively straightforward but requires that the entire codebase be downloaded, to include all assets used by the system (these are currently bundled into the code base). In addition to the appropriate source code, new or bundled assets (in the case of new geodata) that are required by the extensions being made you will need to setup the appropriate development environment to compile the application. The aquiferium codebase will require the installation of Ruby, NodeJS, Compass and Yeoman in order to accomplish this, as well as the dependencies for the project that we will install during the compilation process. The following steps detail how to configure the development environment for
compilation of the code base.
Step 1: Install Ruby, Compass, NodeJS, and Yeoman
Links to these resources are included in Appendix C: Aquiferium Technology to acquire the necessary installation files and instructions. It is required that you install NodeJS before compass or Yeoman because the npm utility for package management used for their installation is included with NodeJS.
The recommended installation sequence is as follows:
1. Ruby
2. NodeJS + NPM
3. Compass
4. Yeoman
Both Ruby and NodeJS + NPM are straight forward installers that handle the process for you. During the installation of Ruby, it is recommended you select the ‘add Ruby to your System Path’ option. Once both Ruby and NodeJS are installed, open a command prompt and execute the following commands to prepare the system and install Compass:
> gem update –system
> gem install compass
> npm install compass
Note: There is a known SSL issue with updating ruby gems in order to install the compass gem properly. See this guide for the solution to that error should you encounter it:
https://gist.github.com/luislavena/f064211759ee0f806c88
Step 2: Install Code Dependencies and Packages
Once you have completed the installation of the utilities required for the development workflow, you need to clone a copy of the online repository to your local system. The clone should result in a directory named eaa- aquiferium wherever you chose to clone the repo. You should then navigate to the root directory of the code base (../eaa-aquiferium) and open a command prompt in this location.
On the command line. Type the following command to install all Node packages required by the Aquiferium:
> npm install
Note: This process may take several minutes as Aquiferium has a large number of package dependencies required to download and install. It is a good idea additionally to run an update on all the packages required by the product to ensure they are current to the latest or specified versions required by the project. To do this run the following command:
> npm update
Now we need to install all the library dependencies required by Aquiferium. To do this, type the following command:
> bower install
If the bower install command exits without creating and installing the dependencies in the folder located at
./eaa-aquiferium/app/bower_components, check the console output to see if you have received an ENOENT
ERROR for any of the packages you were trying to install. If there is an error it, will most likely, be the last one listed in the console. If so, open up the file located at ./eaa-aquiferium/package.json and look for the matching entry to that package that gave the ENOENT ERROR. Delete it from the file (ensuring that the empty line is also removed and that any trailing commas are removed if this changes the last entry in the “dependencies”: {} object). Make sure you have taken note of what dependency had to be removed in case it needs to be reinstalled with npm or bower at a later time. Once you have completed installing the bower dependencies, run the following command to execute the gruntfile.js taskrunner from inside ./eaa-aquiferium to ensure the project is fully setup and ready to develop actively on local:
> grunt serve
The gruntfile.js taskrunner completes a myriad of operations on the code base prepares it for deployment and launches a local web server with the application running inside of it for local development and testing.At this point, you should be able to use the Aquiferium exactly like the deployed online version. You can now begin updating or extending the application as described in the following sections.
Aquiferium has the most popular map tiling services already included with the exception of Google Maps. Due to the complexity of integrating Google Maps into the Aquifeirum application and the fact that its functionality as a tile service is duplicated by Open Street Maps it was determined that the task of code integration was not worth the effort.
Should the inclusion of an additional or map tiling service be necessary, the following code examples demonstrate how to extend the map tiling services available within Aquiferium.
On line 85, insert the following code:
var newMapService_Link = '<a href="http://www.newmapservice.com/">New Map Service</a>';
var newMapService_Url = 'http://newMapTileServer/tile/{z}/{y}/{x}';
var newMapService_Attrib = '© ' + newMapService_Link;
var newMapService_Map = L.tileLayer(newMapService_Url, {
});
On line 520 the baseLayers object for the map is defined. Insert the following code inside this object:
‘newMapService_Map': newMapService_Map,
Note: Care should be taken to ensure inclusion of a trailing comma after this snippet if it is not the last map services listed in the baseLayer object. Vice-versa that there is NO trailing comma if it is the last services listed in the baseLayer object.
Note: The order in which the services are listed here, is the order they will appear on the map for selection.
Note: You should replace all instances of ‘newMapService’ in the code above with a unique name that
describes the map service in some identifiable way. (ex. customMapboxTiles).
That concludes the code changes required to extend the map tiling services available for display in Aquiferium. The application must be recompiled to reflect changes and complete the process. The procedure for recompiling the application is detailed later in this document
In order to add additional geodata layers, in this case geojson data, you will need to duplicate and modify
code within the directive in several places. Additionally you will need already to have the geojson data you
want to include on the map, preferably optimized for web use, and converted to WGS84 projection.
Instructions for the conversion process are as follows.
Note: If additional shapefile optimization is required, that process can be found described at this URL:
http://blog.thematicmapping.org/2012/10/mapping-regions-of-new-zealand-with.html
Step 1: GDAL Installation
In order to convert most geodata files into geoJSON you will need to use the GDAL utility. GDAL stands for Geospatial Data Abstraction Library and is a suite of tools for manipulating, editing, and transforming geodata into and between almost any formats used by GIS systems today. More information about GDAL’s capabilities can be found at this URL: http://www.gdal.org/index.html. GDAL can be downloaded by itself at the following URL: http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries. If you are planning on doing regular manipulation of geodata files and are working in a Windows environment, it is recommended instead that you download and install the OSGeo4W suite of tools, which includes GDAL, from this URL:
http://trac.osgeo.org/osgeo4w/ . Regardless of which utility you select, complete the installation instructions that accompany the application on the vendor’s website and when you are done, resume this process.
Step 2: Convert Shapefiles to GeoJSON WGS84
While there are a great many GIS data formats available, the most common one is the ESRI Shapefile (known by the *.shp) extension. In reality, this is not a single file, but an archived collection of related files that all attribution: newMapService_Attrib describe a specific geographic space and inculcate all the associated data the shapefile represents. To convert the shapefile, you will need to launch the GDAL command prompt, navigate to the directory your shapefile is located in and execute the following command:
> ogr2ogr -f "GeoJSON" -t_srs "WGS84" OUTPUT_FILENAME.json INPUT_FILENAME.shp
This single command will convert the data into geoJSON format as well as alter the mapping projecting to
WGS84 in one pass. If your shapefile has more detailed resolution data than is necessary for the mapping
zoom level you are viewing it at, you can alter the GDAL command to limit the coordinate output included in
the geoJSON file as follows:
> ogr2ogr -f "GeoJSON" -lco COORDINATE_PRECISION=3 -t_srs "WGS84" OUTPUT_FILENAME.json
INPUT_FILENAME.shp
Note: This example limits coordinate output to 3 decimal places, but any whole number can be used here.
This can have dramatic effects on both the output file size and the visual appearance of the geodata on the map. Therefore, some testing may be required to find the correct balance between optimization and display quality desired.
Step 3: Add New GeoJSON to the Application
To ensure that the new geoJSON is available to the Aquiferium for display, a copy of the geoJSON file needs to be placed in the following directory:
//eaa-aquiferium/app/data/geojson/<optional_subfolder>/NEW_GEOJSON_FILE.json
Step 4: Add New GeoJSON to the Map Directive
To make the new GeoJSON file accessible to the users of the Aquiferium, it must now be added into the mapping Directive’s codebase. This will require the insertion of several new lines of code in specific locations as detailed in the following section.
Note: Any hexadecimal colors specified can be changed to the developer’s preference.
On line 150 insert the following code:
var newGeojson_Style = { 'fillColor': #F3F };
var newGeojson_StyleHover = { 'fillColor': #3F3 };
On line 185 insert the following code:
var newGeojson_Geojson = './data/geojson/<optional_subfolder>/NEW_GEOJSON_FILE.json';
On line 211 insert the following code:
var newGeojson_Layer = new L.LayerGroup();
On line 328 insert the following code:
$.getJSON(newGeojson_Geojson, function(data) {processGeojson(data, newGeojson_Layer, newGeojson_Style, newGeojson_StyleHover);
});
Note: Additional interactivity can be added to the GeoJSON layer in the above function, but that process is beyond the scope of this document.
On line 541 insert the following code:
‘New GeoJSON’: newGeojson_Layer,
Note: You should replace all instances of ‘newGeojson‘ in the code above with a unique name that describes your geodata in some identifiable way. (ex. supportRegions_Geojson.json). That concludes the code changes required to extend the geodata available for display in Aquiferium. To complete this process, the application will now need to be recompiled. The procedure for recompiling the application will be detailed later in this document.
If additional markers are desired on the map interface, they can easily be added to the Directive by inserting
the following code at line 456:
var newMarkerLocation = L.latLng(LAT_VAL, LON_VAL);
var newMarkerOptions = { title: ‘New Marker Title’ };
var newMarker = L.marker(newMarkerLocation, newMarkerOptions);
newMarker.addTo(allMarkersLayer);var newMarkerPopupContent = '
New Marker Title
';var newMarkerContentContainer = $('<div />');
newMarkerContentContainer.html(newMarkerPopupContent);
newMarker.bindPopup(newMarkerContentContainer[0]);
Note: You should replace all instances of ‘newMarker’ in the code above with a unique name that describes your marker in some identifiable way. (ex. hqOfficesMarker).
That concludes the code changes required to extend the map markers available for display in Aquiferium. To complete this process, the application will now need to be recompiled. The procedure for recompiling the application will be detailed later in this document.
[[Recompiling the Codebase ]] The primary process of compiling the Aquifeirum is very similar to the process for running it during development. The complexities are handled again by the gruntfile.js taskrunner that prepares the codebase for live deployment rather than local development by executing the following command from the ./eaa-aquiferium/ directory:
> grunt build --force
This will initiate the build process. The output will be logged to the console window for observation or for debugging should there be any errors during the process. Once the build process is complete you will find the final version of the project (the set of files that needs to be uploaded to your web server or copied into your local web server for offline use) in the folder located at ./eaa-aquiferium/dist. The build process has several known bugs that have to be manually corrected as follows in these steps.
Step 1: Fix Missing Dependencies
Open the index file for the distribution build (located at ./eaa-aquiferium/dist/index.html) and insert the following code into the HTML right after the code reading ‘<!—Place favicon.ico and apple-touch-icon.png in the root directory. -->’ but before the subsequent opening <link> tag:
<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300,700'
rel='stylesheet' type='text/css'>
<link href='http://fonts.googleapis.com/css?family=Open+Sans+Condensed:300,700'
rel='stylesheet' type='text/css'>
<link href='http://fonts.googleapis.com/css?family=Ubuntu:400,500,700'
rel='stylesheet' type='text/css'>
<link href='http://fonts.googleapis.com/css?family=Ubuntu+Condensed' rel='stylesheet'
type='text/css'>
<link rel="stylesheet"
href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css">
Step 2: Fix Missing CSS
Ensure appended to the very end of the file located at ./eaa-encompass/dist/styles/ the {hash}.main.css is this style:
.glyph-spacing-right{margin-right:0.5rem;}
Step 3: Replace Missing Images
In the ./eaa-aquiferium/dist/styles folder, create a new folder named images. Navigate to the folder ./eaa- aquiferium/app/bower_components/leaflet/dist/images. Copy all image files from this location into this folder you previously created ( . /eaa-aquiferium/dist/styles).
Step 4: Replace Missing Glyphs
In the folder ./eaa-aquiferium/dist create the following directory structure:
.eaa-aquiferium/dist/bower_components/bootstrap-sass-official/vendor/assets/fonts/bootstrap/
Now navigate to this directory: ./eaa-aquiferium/app/bower_components/bootstrap-sass-official/vendor/assets/fonts/bootstrap/ and copy all the files inside (all named glyphicons-halflings-regular.*) into the last folder you just created in the above directory structure (bootstrap).
Step 5: Update Broken Paths
The image, video and data asset paths will be incorrect after the initial build. There is a bug in the way the path is updated by the task runner that results in an incorrect path to the resources. It requires a find & replace manual update on the files that follow using the specified values.
Find and replace all instances of these string values:
‘../videos/’ with ‘./videos/’
‘/images/’ with ‘../images/’
In these HTML files:
./eaa-aquiferium/dist/geography.html
./eaa-aquiferium/dist/geology.html
./eaa-aquiferium/dist/springs.html
./eaa-aquiferium/dist/conservation.html
And in this CSS file: ./eaa-aquiferium/dist/styles/{hash}.main.css. Additionally, you will need to copy the image and video folders (and all their contents) into the ./eaa-aquiferium/dist folder to address a bug in the renaming of files during the build process.
Find and replace all instances of the string value ‘../../data/’ with ‘./data/’ in the file ./eaa-aquiferium/dist/scripts/{hash}.scripts.js
Step 6: Validate Build Locally
It is recommended you copy the fully updated distribution code to a local web server (Uniform Server or another solution) and test the application outside the development environment. Any missing assets or other errors will be output to the browser console for further debugging if necessary. Once you are certain that your new build is ready for deployment, upload the distribution files to your web server and test the application again online. You should now have your recompiled application running and be able to see the changes you have made or other extensions you have added.
Additional Development
This document has covered all the basic steps involved in setting up the code base, making changes to the code base, and recompiling the code for live deployment. Additional capabilities are beyond the scope of this document and should be considered as another phase in the project’s development lifecycle.
