Skip to content

RAMP v4.0.0
Compare
Choose a tag to compare
@james-rae james-rae released this 09 Dec 15:16
· 481 commits to main since this release
v4.0.0
5deedf0
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

General Info & Usage

This is the initial release of RAMP version 4.

Find a bug? We would love to hear about it.

Documentation

  • Our makeshift "docsite" can be found here. The link is pinned at v4.0.0.
  • The startup page in particular is useful for quickly adding RAMP to a webpage.
  • Some sample pages can be viewed to see the platform in action.
  • The Current Docsite can also be viewed. It may have improved content but may also include changes added after this release.

Breaking Changes

RAMP4 was written from the ground up using different web frameworks (significantly, Angular 1 has been replaced by Vue 3 and the ESRI JS API migrated from v3 to v4). Part of the initiative was to restructure the architecture to mitigate the restrictive nature of RAMP2. As such, pretty much everything is different. The major impacts will be highlighted here.

Instantiation

Instances of RAMP are no longer created with specially attributed divs on the host page.
E.g. <div is="rv-map"></div>

Instances are now generated via javascript calls which target a desired div. This allows page authors more control over when instances get generated.

E.g.

const instanceAPI = RAMP.createInstance(
    document.getElementById('map-div-id'),
    configObject,
    optionsObject
);

See the startup page for further details.

API Interface

The API is entirely different than the RAMP2 API. Notably, there are no observables; an event system is used instead.

Some API objects may be wrapped in Proxys. This is a side effect of Vue Reactivity, and the objects can be interacted with as if the proxy was not there.

Visit the API Section of the docs to see what content is currently available.

Details Templating

RAMP2 details templates used Angular markup. Since RAMP4 uses Vue, any old templates will not work. Manual conversion is required. Visit the details doc page for further information on the new templating system.

Identify Modes

  • highlight and haze are now managed via hilight fixtures.
  • details can be turned off or overridden via the default event handler named ramp_map_identify_opens_identify_results
  • marker has not been implemented yet.

Related: #130

Configuration

The configuration schema is different than RAMP2. Visit the Configuration Section of the docs, or brave the schema file to learn about the RAMP4 configuration.

The library exposes a converter function configUpgrade() which can be used outside of a RAMP instance to upgrade a RAMP2 config file to a RAMP4 config file. The function accepts a single config object, or an array of config object (each object having a unique language code). Any config contents that cannot be converted will be broadcast on the browser console.

const r4config = RAMP.configUpgrade([r2configEN, r2configFR]);

There is also a similar layerConfigUpgrade(r2layerConfig) function that can be used to convert individual layer config objects (e.g. while parsing the output of an RCS response).

RAMP 2 Missing Features

One of the challenges of maintaining RAMP2 was that it had a lot of specific behaviors coded in the core of the library. This made customizations difficult, requiring things like large refactors, numerous config flags and branching logic, or dirty hacks.

RAMP4 embraces a new architecture approach, leveraging something we named fixtures. They are similar to plugins, however most of the "stock" components out of the box (e.g. the legend, the grid) are implemented as fixtures. This allows things to be removed or replaced, and new components to be added. As an example, one could develop an entirely different grid fixture and use it instead of the stock grid fixture provided.

As such, some features from RAMP2 have not been ported, the idea being specific fixtures could be written that would meet specific requirements, rather than us attempting to provide some type of universal solution.

Other features are just not completed yet and may be prioritized in the future.

Autolegend

The legend fixture that ships with the ramp core only supports "structured" legends. Any type of automated adaptive legend construction should be implemented using the RAMP4 architecture: fixtures, events, and the RAMP API.

For simple cases, a fixture or custom script could easily parse the layer configuration and issue API calls on an empty legend to construct basic legend items. This allows the implementer flexibility in how their "autolegend" behaves. In the future, a basic optional fixture that does this may be included as part of the library.

For more complex cases, a custom legend fixture can be developed and replace the default legend fixture.

Bookmarking

The RAMP2 bookmarking function was convenient, but also inflexible in what data it could store. The RAMP4 philosophy is pages should implement their own bookmarking, thus allowing developers control over data, formats, and behavior. Data can be extracted and set via the API.

In the future, we may explore rudimentary bookmarking (as a convenience for simple and common requirements), and develop more helper routines on the API to support the extraction and setting of application state.

RCS Integration

Similar to bookmarking, any integration with RCS has been removed from the RAMP core. Developers can now write scripts or fixtures to integrate with any data source they choose, leveraging the API to co-ordinate with the RAMP instance.

WMS Styles

The ability to pick alternate styles on WMS layers is currently not supported. This also impacts the legend graphic that is automatically downloaded. The default style will be used. (#603)

Customized Exports

A rudimentary export fixture has been developed (export). Sub-components of that fixture are also implement as fixtures, meaning developers willing to deep-dive can write modified/replacement components for desired customizations. Alternately new export fixtures can be written from scratch.

That said, the RAMP2 "custom export plugin" framework has not been ported and is not compatible with RAMP4.

Plugins

Most RAMP 2 plugins have not been migrated. The exception is Areas of Interest, which is available via the optional fixture areas-of-interest.

Back to Cart, Co-ordinate Info, or anything in the Contributed Plugins repo would require a migration and likely should be implemented as fixtures.

Other Missing Features

  • There is no UI support (e.g. indicators in the legend) for layers which are only visible at specific scales (#1054)
  • There is no support for timed-refresh layers (i.e. layers with data that gets refreshed every given interval) (#1018)
  • Hovertips are not supported on graphic-layer graphics. These would be analogous to graphics in RAMP2 SimpleLayers (#998)
  • When loading CSV files via the import wizard, potential co-ordinate fields will not be pre-checked to ensure they contain valid lat/lon numbers (#958)
  • Cannot have a specific data grid auto-open at application start via configuration (#909)
  • There is no on-screen "bounding box" to be displayed for layers. It is questionable if this will ever be implemented (#194)
  • The legend does not support the customization of the symbology stack
  • There is no support for a "blank" basemap
  • Grid columns do not support a "Selector" type filter

Known Issues

Maptips

Changes to ESRI's hitTest during our development phase has introduced some undesirable behaviors regarding maptips.

  • Cannot derive topmost feature on a layer without a drawOrder, or with drawOrder on a non-unique field (#931)
  • If a raster layer is covering a vector layer, the maptip engine currently cannot realize this and will show maptips for the covered vector features (#800)
  • No maptips on highlighted features (#1320)

New Things

Panel API

While RAMP2 had fixed panels in fixed positions, RAMP4 utilizes a Panel API for a more flexible experience. Panels open left to right across the screen; if a new panel has no room, the leftmost panel is minimized.

Panels can be manually repositioned, minimized, pinned (i.e. avoid auto-minimization), and can optionally be sized. They are primarily, but not necessarily, associated with fixtures, such as the legend, geosearch, or grid.

Panels also assist in a friendlier mobile experience. On a phone-sized screen, only one panel is visible at a time and will occupy the majority of the viewing space.

Appbar

On the left side of the UI is an appbar. This tracks any open panels (similar to how a Windows Task Bar tracks windows), and can also host buttons to launch panels. Minimized panels can be restored via the appbar.

Appbar buttons can also be configured to perform custom actions.

Notification API

Developers can now easily display notifications to users via a simple API.

Faster Reprojection

Changes to the ESRI API map architecture allow RAMP4 to reproject to a different basemap schema without needing to reload the active layers.

Full Layer Reordering

Additional changes to the ESRI API allow raster and vector type layers to be mixed in the layer stack; they are no longer segregated to their own stacks. RAMP4 provides a dedicated reordering UI to allow users to adjust the positioning. It is no longer bound to the legend structure.

Assets 3