fgpv-vpgf / geoapi Goto Github PK

License: Other

JavaScript 80.13% HTML 19.64% Shell 0.23%

geoapi's Introduction

RAMP2 FGP Visualiser / Visualisateur pour la PGF PCAR2

Next Version

Version 2 / Version 3 is now retired. We do not expect any further updates, and a number of the underlying libraries are depreciated as well. New visitors are encouraged to consider RAMP 4. Notable changes include:

Updating the UI framework from Angular 1 to Vue 3
Updating the ESRI Mapping API from v3 to v4
An application architecture and API that is more open and adjustable
UI re-design with mobile use in mind

The initial release notes cover the differences, breaking changes, and feature gaps for anyone considering migrating an existing RAMP2 project.

RAMP-PCAR FGPV-VPGF

The Reusable Accessible Mapping Platform (RAMP), also known as the Federal Geospatial Platform Visualiser (FGPV), is a Javascript based web mapping platform that provides a reusable, responsive and WCAG 2.0 "AA" compliant common viewer platform for the Government of Canada.

This is an unsupported product. If you require a supported version please contact [email protected] for a cost estimate. The software and code samples available on this website are provided "as is" without warranty of any kind, either express or implied. Use at your own risk. Access to this GitHub repository could become unavailable at any point in time.

This project is now a monorepo and contains the following repos under the packages folder:

ramp-core (previously this repo)
ramp-geoapi (previously https://github.com/fgpv-vpgf/geoApi)
ramp-geosearch (previously https://github.com/RAMP-PCAR/geosearch)
ramp-plugin-areas-of-interest (previously at https://github.com/fgpv-vpgf/plugins)
ramp-plugin-back-to-cart (previously at https://github.com/fgpv-vpgf/plugins)
ramp-plugin-custom-export (previously at https://github.com/fgpv-vpgf/plugins)
ramp-plugin-coordinate-info (previously at https://github.com/fgpv-vpgf/plugins)
ramp-plugin-enhanced-table (previously at https://github.com/fgpv-vpgf/plugins)

Building the project

Install Python 2 if you don't already have it: Python 2.7.18 Download (Python 3 is not supported)

Install the required C++ build tools (2 options)

OPTION 1 (recommended): Install Visual Studio and the required additional package
- Walkthrough for complete Visual Studio installation and additional packages post-install
- Build Tools for Visual Studio 2019
OPTION 2: Directly add windows-build-tools package
```
$ npm install --global windows-build-tools
```
- NOTE: This may stop giving feedback in the console mid-install and seem to hang. However, it appears the required packages are still installed

Install Rush if you don't already have it:

$ npm install -g @microsoft/rush

Clone the repo and use Rush to install dependencies

$ rush update

You might want to run rush update -p --full to cleanly re-install all the dependencies (-p will purge what is currently there)

Build the project:

$ rush build

NOTE: rush build will need to be run before the rush serve statement below any time code is changed in ramp-geoapi to avoid an outdated build

Serve the project:

$ rush serve -p 10 -v

-p 10 specifies the maximum number of concurrent processes to run (we need 8 right now to serve all the packages at the same time)
-v provides verbose output for debugging

If you want to work on only a subset of packages instead you have to run their builds/serves seperately:

// terminal 0
$ cd packages/ramp-core
$ npm run serve

// terminal 1
$ cd packages/ramp-plugin-enhanced-table
$ npm run serve

Lastly open the samples page:

http://localhost:6001/samples/index-samples.html
etc.

For more rush commands or general reading: https://rushjs.io/pages/intro/welcome/

For more info on individual packages builds/documentation read the READMEs in the respective folder.

Documentation

For more information on this project, please see one of the sections below:

Usage
Support

Also, please visit the Documentation Site for additional content on:

Usage

Quick guide

We'll go through the simplest way to use RAMP, for more information see the map author guide

First, grab the most recent release from the github releases Place the files rv-main.js and rv-styles.css within your webpage's folder structure. We usually put our JavaScript files under a js folder and our stylesheets under a css folder.

Then you want to include those files on your page, along with jQuery and the needed polyfills:

Within head

<link rel="stylesheet" href="../../../rv-styles.css" />

Near the end of the body

<script
  src="https://code.jquery.com/jquery-2.2.4.min.js"
  integrity="sha256-BbhdlvQf/xTY9gja0Dq3HiwQF8LaCRTXxZKRutelT44="
  crossorigin="anonymous"
></script>
<!-- Polyfill script here -->
<script src="/js/rv-main.js"></script>

See the doc page for a list of recommended polyfills. In these modern times you may decide it is no longer needed, as most browsers now have built-in support.

Now that you have the required files on your page we should add the map element.

<div
  is="rv-map"
  style="height: 100%; display:flex;"
  rv-langs='["en-CA", "fr-CA"]'
></div>

A map should now load on your page. Theres much more you can do with RAMP, a good place to start is the map author guide

Samples

A collection of sample source files are in the repo.

A live site containing our development sample page is found here.

An example of a production site is the Government of Canada Climate Data Viewer.

Support

Bugs

If you have a bug to report you can open up an issue at https://github.com/fgpv-vpgf/fgpv-vpgf/issues by clicking the green button above the issue list

For more information on contributing read the Contributing Guide. Note there may be some references to the pre-monorepo setup, pull requests are now only needed in one place (this repo).

Contact

The team can be reached at [email protected]

geoapi's People

Contributors

Stargazers

Watchers

geoapi's Issues

add bootstrap component to load JSAPI via script tags

Create setupMap function in mapManager

Requires issue #14 to be completed first
Having configuration schema finalized will be very helpful prior to starting this.
Function name is not set in stone (yet)
Function will take a new map and add visual things to it. See the wiki page for details
Function will have parameters (names not official yet)
- map, an ESRI map object
- settings, a subsection of the config (likely from the map section) that defines what visual things the map should have
Function should iterate over the settings and apply logic for any items present
- as an example, if a scalebar definition was present in the settings, a scalebar should be applied to the map
- for now, just set up the structure for iteration. implementation of specfic cases will be done in other tasks
- rather than using a switch statement, use an object that maps settings key names to the appropriate functions.

add basic layer loader

Trying to pan and zoom at the same time breaks all subsequent zoom attempts

Description

Trying to pan the map using a keyboard as it zooms in or out, prevents any subsequent keyboard-triggered (+/- keys of zoom in/out buttons on the map interface) zoom action from working.

Version tested: v2.4.0-4

Steps to Reproduce

tab to the map
press + and -> keys simultaneously or in a very quick succession
pres + or - key again

Expected Results

The map zooms normally.

Actual Results

The map doesn't want to zoom anymore. There is an uncaught error in the console.

Logging Output / Screenshots

index-fgp-en.html?keys=JOSM:1 Uncaught (in promise) undefined

Generate scale bar

Requires issue #15 to be completed first. See that issue for detail on files & functions involved
Having configuration schema finalized will be very helpful prior to starting this.
Functionality will generate an ESRI Scalebar and apply it to the map (supplied by parameter)
Any additional parameters for scale bar (to be determined when config schema is complete) should be applied (e.g. screen placement, metric vs imperial units?).

Scale bar is present even when we set false in config file

@jolevesq commented on Fri Mar 31 2017

Even when scale bar is false inside configuration file the scale bar is present.

In geoApi mapManager.js line 71 setting.scaleBar is use to check if scale bar need to be there. it should be setting.scaleBar.enabled

Check for multiple initialization

The geoApi initialization may be called multiple times per page. Each call will generate a script tag to load the ESRI JSAPI which will collide when trying to redefine its globals (require, define, ...). Detection should probably happen in geoApi and not its caller.

Create map manager submodule

Requires issue #13 to be completed first
filename mapManager.js
generate file and have appropriate file header comments. See the wiki as an example of how a file should look.
in index.js
- ensure required ESRI API classes are defined in array esriDeps
- ensure function initAll assigns the submodule to the return object

Clean up logging messages in prod

@alyec commented on Tue Feb 14 2017

At least for the prod version we need to clean up noisy logging. Ideally with a rv-logging-level type of attribute, but at the very least removing noisy console activity on the prod build.

@AleksueiR commented on Thu Mar 02 2017

Console logs made by geoApi code are still present.

@milesap commented on Tue Mar 07 2017

A potential roadblock here is that geoAPI is bundled with all other required dependencies (I believe this is lib.js in gulp.config.js). We would need to separate the geoAPI import from the others to let gulp do its thing. We can't strip console logs from everything as we may want to see them, and the current gulp plugin breaks some libraries that use console differently like console && console.log("foo");

@alyec commented on Tue Mar 07 2017

I think this should be a fix on geoApi rather than trying to split out dependencies.

Update layer.js to example quality

Update layer.js with appropriate structure, sample functions, and comments

We need an example of "how things should look" that other contributors can reference. Right now layer.js is about as barebones as it can get. Please make it look like how you want files to look, as it will be referenced as a starting point / example in other tasks.

API Docs for Return Value Functions

Sometimes the functions that are publicly exposed by the API do not exist as a plain function sitting inside a module. Instead, they are the product of a different function that returns a function (the return value is what ends up being the public function.

function myPrivateFunction(apiStuff) {
    //this return function needs to be described in the API Docs
    return (param1, param2) => {
        const p = doStuff(param1);
        return new apiStuff.MyClass(p, param2);
    };
}

module.exports = function (apiStuff) {
    return {
        myPublicFunction: myPrivateFunction(apiStuff)
    };
};

We need a way to document the return value function so the docstrings will appear in the API docs, letting users know the function exists and how to use it.

For an example, see function projectEsriExtentBuilder in file proj.js

Create basemap submodule in geoApi

Requires issue #13 to be completed first
filename basemap.js
generate file and have appropriate file header comments. See the wiki as an example of how a file should look.
in index.js
- ensure required ESRI API classes are defined in array esriDeps
- ensure function initAll assigns the submodule to the return object

Make unit tests for attribute loader

The actual service calls will be faked to make things fast.
It will just test the interface and flow of the attribute module

Create wrapEvents function

Make a new module in geoApi called events. See the wiki for instructions.
Function name is not set in stone (yet)
wrapEvents function will be attached to the return object of the events module.
Function will have parameters (names not official yet)
- esriObject, an ESRI object (at this point, a layer or a map object).
- handlers, an sub-group of an event handler definition object. Subgroup should match the type of esriObject being passed. So if a layer is supplied, handlers.layer would be the input.
Function should wire up any supplied handlers to the corresponding dojo on events on the object
- This allows us to keep Dojo on events contained in geoApi
- Candidate events are on the wiki
- For layers, the click, mouse-over, and mouse-out events only apply to Feature Layers. Utilize function getLayerType in shared.js to determine layer types.
- For layers, the error, update-start, and update-end events should add another property to the event parameter called layer. This will point to the value of target. It will make the value more intuitive.
See RAMP documentation for more info on how ESRI Dojo layer events work
As time permits, some validation on input objects and handlers could be performed. For example, if a caller passes a map object with layer event handlers, freak out with an error

Sample protoype with no validations, parameter enhancements, or mappings from our event names to dojo event names

wrapEvents(esriObject, eventObject) { 
    Object.keys(eventObject).forEach(ourEventName => { 
        esriObject.on(eventMapping[ourEventName], eventObject[ourEventName]); 
    } 
} 

exports = { 
    wrapEvents(esriObject, eventObject) 
}

Create attribute loadFeatureAttribs function

Requires issue #23 to be completed first
Function name is not set in stone (yet)
Should this be a private function?
- It will be used by the public function to execute the details of fetching data from an arcgis map server feature layer endpoint (for both feature layers and constituant layers of dynamic map service layers)
Function will take a layer object and fetch attribute data for that layer. See the wiki page for details
Function will have parameters (names not official yet)
- layerUrl, a url to the ESRI Feature Layer endpoint on an arcserver
Function should return a Promise that resolves with the attribute data after it has been loaded
When fetching features from the REST endpoint, be aware of the service's maximum return value.
- If the number of features exceed this value, then multiple requests need to be made to get data in batches
- See RAMP Code for examples of this
- Note that ArcGIS Server less than 10.1 will not return the services maximum return value. The above file also has work-arounds for this
If possible, take into consideration that we may want to enhance this process to pull only one block of attributes at a time (to support paging on gigantic datasets)

Create overview map logic

Requires issue #15 to be completed first. See that issue for detail on files & functions involved
Having configuration schema finalized will be very helpful prior to starting this.
Details on overview map implementation are still unfinalized
- Use ESRI Widget that isn't very useful at low zoom levels?
- Custom widget/directive that does what we want?

Need ability to access ESRI dojo map events for viewer API

ArcGIS API's working with events demos indicate (near the bottom of the page) that an ESRI event can be stopped.

event.stop(event);

When binding API events on the viewer, it would be nice to bind them directly to the ESRI event. This allows us to make certain map events stoppable via the API (such as an extension which stops an identify click and instead opens a pop-up with info/data).

We could:

Add a function to https://github.com/fgpv-vpgf/geoApi/blob/master/src/events.js which is similar to wrapEvents but only takes one event at a time and returns the dojo/esri event object. Something like function esriOn(mapInstance, eventName, fireCallback);
Correct the current on function in map instances so it points to the esri/dojo on function (this goes against our keeping dojo out of the core though).

Though ESRI's documentation can be flaky sometimes, the method name may have changed or just plain doesn't stop the event. Some testing would be needed.

Set up Protractor test engine on geoApi

@james-rae commented on Wed Nov 16 2016

Will allow us to write additional tests that use the real ESRI API.

More real-world tests
Less mocking fake APIs
Extra checks when we bump a minor version of ESRI API

Ideally, setup files can be stolen from the viewer, and Angular parts removed

Geometry types for dynamic sublayers are not available

Is it possible to tell geometry type for a sublayer of a dynamic layer?
@AleksueiR

from what I can tell, no, not without pinging the server for information on the specific sublayer. Since a dynamic layer does not return any geometry info, it kind-of makes sense why they keep it abstract. as a possible option to make this available, it would be fairly easy for me to enhance the attribute bundle to include the geometry type in the child nodes (as we are already inspecting all the sub-layers when loading geometry). Caveat would be that the information would not be available until attributes loaded, as well if we supress attributes for a sublayer, then the geometry info would also not be loaded.
@james-rae

Test reprojection module

Write basic Jasmine unit tests for the reprojection module. Document heavily to be used as examples for future geoApi unit tests.

Focus manager erroneously triggered

Steps:

click on the map with a mouse
press "Tab" or "Shift + Tab"

"Keyboard focus" dialog gets triggered.

Expected behaviour:
After clicking on the map, the focus should stay/be placed inside the viewer; pressing "Tab" should not trigger the dialog.

test the layer module

Create mapManager wrapEvents function

Function name is not set in stone (yet)
wrapEvents function will be attached to the return object of the mapManager submodule.
Function will have parameters (names not official yet)
- map, an ESRI map object.
- handlers, an event handler definition object
Function should wire up any supplied handlers to the corresponding dojo on events on the map
- This allows us to keep Dojo on events contained in geoApi
- Candidate events are click, extent-change, pan-end, pan-start, update-end, update-start, zoom-end, zoom-start
- The native event arg object will be passed along to the handler functions
See the map manager wiki page and events wiki page for additional information

Setup API Documentation Generator

The fgpv-vpgf project has an API doc generator using djeni. The same type of generator should be set up for the geoApi library.

wms zoom

@mweech commented on Mon May 02 2016

oops

Create attribute loadLayerAttribs function

Requires issue #24 to be completed first
Function name is not set in stone (yet)
Function will take a layer object and fetch attribute data for that layer. See the wiki page for details
Function will have parameters (names not official yet)
- layer, an ESRI layer object
Function should return a Promise that resolves with the attribute data after it has been loaded
See the wiki page for details on how the attributes should be structured, stored, and returned.
Function will examine the type of layer object passed in
- Feature Layer will trigger a feature load on that single layer
  - Leave code stubs to support file-based feature layers. In this case we will need to extract attributes from the features themselves, as no service will exist
- Dynamic Map Service Layer will trigger feature loads on all constituent child data layers
  - There should be support to suppress certain child layers. Need details (comes from config?)
- Other layer types will throw an error (for now)
- We can expand to support more types of layers
- Results are collated into the return object; when everything is loaded, will return on the promise

Basic reprojection module

Reproject a fragment of esriJson. Within the module use terraformer to convert esriJson -> geoJson and reproject the geoJson fragment.

Create attribute submodule in geoApi

Requires issue #13 to be completed first
filename attribute.js
generate file and have appropriate file header comments. See the wiki as an example of how a file should look.
in index.js
- ensure required ESRI API classes are defined in array esriDeps
- ensure function initAll assigns the submodule to the return object

Add comments to gulpfile

gulpfile.js could use some inline documentation, particularly on the feistier tasks such as build

Create basemap makeBasemaps function

Requires issue #20 to be completed first
Having configuration schema finalized will be very helpful prior to starting this.
Function name is not set in stone (yet)
Function will take a configuration collection of basemap metatdata and generate an ESRI Basemap Gallery Dijit popuplated with the basemaps. See the wiki page for details
Function will have parameters (names not official yet)
- settings, a subsection of the config (likely from the basemap section) that defines what basemaps should be loaded in the dijit
Function should iterate over the settings and use the info to generate Basemap Dijits and populate the BasemapGallery object with them
Return the BasemapGallery as a property in a JSON object, as we will be adding functions to this object to maniplate the gallery (extra abstraction since gallery use is fairly simple).

Create mouse co-ordinates logic

Requires issue #15 to be completed first. See that issue for detail on files & functions involved
Having configuration schema finalized will be very helpful prior to starting this.
Details on mouse co-ordinates implementation are still unfinalized
- Use existing code/approach from GCViz?
  - Latest codebase uses proj4 for local co-ordinate calculation
- Make newer angular-friendly thing?
- ESRI screenUtils may be helpful
- Options to position display?

Requires issue #21 to be completed first
Function name is not set in stone (yet)
setBasemap function will be attached to the return object of makeBasemaps function. See #21
Function will have parameters (names not official yet)
- id, the basemap digit id to set as the active basemap.
Function should access the internal BasemapGallery object and set it's active basemap based on the parameter
- This allows us to manipulate the gallery without having non-geoApi code talking directly to the ESRI dijit.

Create north arrow logic

Requires issue #15 to be completed first. See that issue for detail on files & functions involved
Having configuration schema finalized will be very helpful prior to starting this.
Details on North Arrow implementation are still unfinalized
- Use existing code/approach from GCViz?
- Use North Indicator as envisioned in the design mockups? - ftp://69.89.25.92/%5BHouse%20Hippo%5D%20Initiative%20-%20R2%20-%20A04%20%5BExplained%5D%20v0.7.pdf