ramp4-pcar4/ramp4-pcar4

RAMP 4 - The Reusable Accessible Mapping Platform, fourth major version

R4MP

RAMP - The Reusable Accessible Mapping Platform, is a Javascript based web mapping platform that provides a reusable, responsive and WCAG 2.1 AA compliant common viewer for the Government of Canada. The fourth incarnation embraces the following large-scale changes

• 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 previous version (RAMP 2 / RAMP 3) can be found here. Differences between the versions are summarized in the v4.0.0 Release Notes.

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.

Documentation

Documentation Site with unpublished changes can be found here.

Head to the Releases page for version-specific official documentation sites.

Local development

Project Setup

Download the latest Node version, currently v18.3.0 or later.

npm ci

Compile and Hot-Reload for Development

npm run dev

Open https://localhost:5173/demos/index-samples.html in your browser.

Serve via http

npm run dev-http

Build for production

npm run build

The production files will be placed in the dist folder.

Preview production build (after running build)

npm run preview

Open http://localhost:5050 in your browser.

Preview Vitepress documentation

npx vitepress dev docs

Build Vitepress documentation

npm run vite-docs:generate

Static site generated in the vite-docs directory.

Preview/Build TypeDoc documentation

npm run ts-docs:generate

Static site generated in the ts-docs directory. Open index.html to preview.

Recommended IDE Setup

VSCode with the recommended extensions (VSCode should bug you to install them).

Important:

1. Install Volar.
2. Disable/remove Vetur.
3. Type @builtin typescript in the search box on the VSCode extensions tab and disable "TypeScript and JavaScript Language Features". Volar has its own TS language server so we don't want to run two concurrently.

public vs demos folders

The public folder is a static only folder. It contains the help md files and end-user demo assets and the compiled ramp library source code. Files in this folder are not processed by vite and therefore cannot reference outside files. This is useful for testing if things are broken between the develop and production build.

To test the files in the public folder locally:

npm run build
npm run preview

Then open http://localhost:5050/index.html in your browser.

The demos folder is processed by vite and can therefore reference any source file in the repo. This is the starting point for local development. For example, the demos/starter-scripts/main.js file imports { createInstance, geo } from '@/main'; whereas public/starter-scripts/index.js doesn't since RAMP is globally defined by the index.html file when it loads <script src="./lib/ramp.js"></script>.

Run npm run dev then open http://localhost:3000/demos/index.html in your browser.

During build, the public folder contents are placed into the dist folder.

Demo Builds

The demos of the most recent build are available at https://ramp4-pcar4.github.io/ramp4-pcar4/main/demos/index-all.html.

Demo builds are automatically generated for pull requests if you are a member of the ramp4-pcar4 organization and have your visibility set to public.

ramp4-pcar4's Issues

Zooming

Help

Support for Modules/Plugins

Overview is here: ramp4-pcar4/r4design#1

Leverage Esri JSAPI 4.x

Focus Management

GeoSearch

Implement Identify Modes

Likely requires some design and discussion before implemented.

RAMP2 had different identify modes; each could be turned on or off.

• Query would run the query and have results appear on the API endpoint
• Details would cause the details panel to open with the results displayed. Needs Query to be on.
• Marker would drop a glyph on the map where the mouse clicked.
• Highlight would draw the highlighted feature. If Marker is on, would replace the marker. Am uncertain of the details, but am guessing this only applies if Details is on (as person would need to select the feature the highlight), or possibly it would do a highlight if only one feature was in the result set and Details was off.
• Haze would haze out the rest of the map when the Marker or Highlight was showing. Did nothing if both those modes were off.

Revisit if we still want to structure the modes like this, or adjust some. Things to consider:

• Query acts like a master switch, so is somewhat higher level than the other settings
• Details is now tied to a fixture (which can be replaced / removed / have a second fixture wired in) and the Events API.
• Marker, Highlight, and Haze are all sort of tied to the concept of the Highlight layer.

Related: #127

Support for WFS - Web Feature Service layers

Investigate double-call of initRAMP

To duplicate: in public/index.html, put a console log as the first line of initRAMP(). Run the site. Watch the log get written twice.

Add method to get Instances on the RAMP API

The RAMP api (see APIInterface internally) exposes a way to create a new ramp Instance, but does not provide a way to get existing interfaces.

The main use case for this issue is to aid in debugging. E.g. in the console it would often be very helpful to run something like

RAMP.instances[0].fixture[key].doSomething()

Most other use cases are handled as they would be in page code, and the page script has access to the ramp instance variable; that said, there could arise scenarios where that is not the case (e.g. a second script in the page? an outside plugin script?).

If implemented, a decision would be how to access the instances. The example above uses an index, which is easy but also means order of creation would matter. We could also entertain adding the concept of an id to instances, and use that as a key.

We would also need something to store pointers to all the created instances in order to grab and return them.

Edit: it appears the rInstance is public if declared correctly / globally. It's current state of nonsense is likely due to #123 overwriting the variable a second time. Still, determine if a RAMP function is something we want.

i screwed up i'm sorry jon

Monorepo

WCAG 2.1 AA compliance

Documentation

Stuff for the official docsite, JSDoc, repo readme, and whatnot

Implement Layer Reloading

This will likely require some upfront design work.
Things to consider

• trigger for this should be accessible via the core api / layer api
• geoapi layer objects have a special parameter to preserve uid values when reloading a layer
• strech goal: find a good way to preserve non-service based layer data to allow stuff like geoJson, csv, etc, to be reloaded. Suggest preserving the ESRI Json that is fed into the local layer.
• ensure things listening to events on the geoapi layers get refreshed so that they are listening to the new layer object
  • given the tricky nature of this (always watching for a reload, having to re-set appropriate listeners), it might be advantageous to wait until #173 is completed. Once the layer objects are inside of the RAMP core, they can just use the ramp event bus. No more custom listeners on custom events on the layer objects.
• more...

Crazy idea. Have the concept of reloading retain the same RAMP layer object. The internal ESRI layer would get destroyed/recreated, but the layer shell remains. Would solve our stale pointers problem. Would require some re-structuring of the "layer load" sequence, like how things get added to the map. This might also mean taking some concepts of "layer blueprint" and pushing them inside the layer, especially if we want to allow things like file layers to reload.

Feature Highlighting

This will likely require some upfront design work.
Things to consider

• GeoAPI does have a highlight layer, but it is essentially untested
• In RAMP2, the "fogging" of the map behind the highlight was done by directly manipulating the SVG that represented the ESRI map. If we do the same, will need to see if things are different in ESRI 4, and be aware that WebGL may be used instead of SVG.
• An API function to request a highlight sounds like a fine idea
• Functions to get individual geometries from a layer already exist in GeoAPI

Related design discussion #837

Overview Map

Extra Scrollbar in Grid Panel

Could get this to happen in Chrome, not in Firefox.

Open the Grid panel. Grid needs to be long enough to trigger the scroll bar to show more rows.
A second scroll bar appears on the panel. Suspect the grid is just a touch too big for the panel and is triggering the panel contents scroll.

Add nice title to Grid panel

Grid panel currently has no title, just the search box on the right side.

Add some appropriate text. See what RAMP2 is showing. If nothing helpful there, would suggest something like Features - <Sublayer name>

Details Pane

Add Zoom-to button to Feature Details

In the individual feature view of the details fixture (3rd screen, I believe), we can add a Zoom to magnifying glass action button that will zoom the map to the feature's location.

User Interface Design - Mockups

A design proposal is published on HackMD: https://hackmd.io/kAPwqjkZQA-cWohYbmZiXw

North Indicator

Implement zoom-to button in grid rows

Clicking the zoom to button in the grid should zoom the map to the feature in the grid row. Zoomies occur.

Feature Hovertips

Implement details button in grid rows

Clicking the details button in the grid should trigger the details view for the row in question.

This interaction should use the default events paradigm with the EventsAPI so it can be adjusted if need be.

Hamburger Menu

Language Switch

Replace lodash

We are using the lodash library in one spot to do deep cloning.

Suggest find a smaller library, or write (or steal) a simple deep clone method (in all likelihood we only need to handle string/number/boolean/object/array)

Update doc to reflect Ramp Instances

There is a good amount of early doc (mainly in JSDoc function headers, might exist in the docs markdown as well) that was written when RAMP. was thought to be the main entry point to the application.
Now that we have Ramp Instances, the doc should be updated.

E.g. RAMP.panel would now be rInstance.panel

Layer Settings

Legend Structures

Add feature symbols to Identify results list

On the details fixture that is part of the core fixture suite, the second screen (the one that lists identify results for a specific layer) can have the symbol for each feature to the left of the feature name.

Add hovertips to Appbar icons

Hovering over appbar icons currently does nothing. "Guess and click" interface.

Add hovertips, and if there is not any tip text setting in the configuration/settings for making an appbar button, add those two.

Tips should be language sensitive.

Support for Esri Map Image layers

Export

Add crosshairs selection tool

See RAMP2 for example. Open the side, use arrow keys to pan, behold the crosshairs.

Attempt to steal/reuse the RAMP2 code as much as possible.

Support for Tiled Services

Fancy-up stock feature details view

A number of visual improvements can be made to the individual feature view of the details fixture (3rd screen, I believe).

• Hide rvInteractive and rvSymbol fields
• Duplicate the designated name field as a title of the screen
• Have the feature symbol somewhere prominent (right justified in the title?)

Navigation Controls

Support for Esri Feature layers

Data Table

Basic state saving

Anything to do with state saving. Could be a recreation of the URL "bookmark", could be something newfangled. Also anything with the underlying structure in the core to support state save & restore

Support for flat file formats (GeoJSON, CSV)

Basemap Selector

Improve contrast of identify results counts

In the details fixture, first screen, the counts of results per layer is a light grey. This likely fails the contrast thresholds for accessibility. Make darker or add a dark background.

Keyboard support for map pan and zoom

Use whatever keys were designated in RAMP2.

Likely arrows for panning, plus and minus for zoom (be sure to double check)

Use proper symbols on grid rows

The grid row symbols currently are using a hardcoded symbol. Use the actual symbol for each feature.

Support for Time-enabled Esri layers

Support for WMS - Web Map Services