---
# System prepended metadata

title: Draft Release
tags: [R4MP]

---

###### tags: `R4MP`

# Draft Release

## General Info & Usage

This is the initial release of RAMP version 4.

Our makeshift "docsite" can be found [here](https://github.com/ramp4-pcar4/ramp4-pcar4/blob/v4.0.0/docs/toc.md). A proper docsite is in the works.

The [startup page](https://github.com/ramp4-pcar4/ramp4-pcar4/blob/v4.0.0/docs/api/startup.md) in particular is useful for quickly making a page.

Some [sample pages](https://ramp4-pcar4.github.io/ramp4-pcar4/main/demos/index-all.html) can be viewed to see the platform in action.

Find a bug? We would [love to hear about it](https://github.com/ramp4-pcar4/ramp4-pcar4/issues).

## Breaking Changes

RAMP4 was written from the ground up using different web frameworks (significantly, Angular 1 has been replaced by Vue 3 and ESRI 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.

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

See the [startup page](https://github.com/ramp4-pcar4/ramp4-pcar4/blob/v4.0.0/docs/api/startup.md) for further details.

### API Interface

The API is entirely different than the RAMP2 API. Notably, there are no [observable](https://rxjs.dev/guide/observable)s; an event system is used instead.

Some API objects may be wrapped in [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)s. 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](https://github.com/ramp4-pcar4/ramp4-pcar4/blob/v4.0.0/docs/toc.md#api-documentation) 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](https://github.com/ramp4-pcar4/ramp4-pcar4/blob/v4.0.0/docs/app/details.md) 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](https://github.com/ramp4-pcar4/ramp4-pcar4/blob/v4.0.0/docs/toc.md#app-configuration) of the docs, or brave the [schema file](https://github.com/ramp4-pcar4/ramp4-pcar4/blob/v4.0.0/schema.json) 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 file, or an array of config files (each file having a unique language code). Any contents of the files that cannot be converted will be broadcast on the browser console. 

```js
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](https://github.com/fgpv-vpgf/rcs) response).

## RAMP4 New Features

The fourth version of RAMP embraces the following large-scale changes

### Panel UI

Panels are a feature of the new interface that provide a flexible and easy means of managing UI controls. Panels are extensively configurable, and can be pinned, minimized, and reorganized on the page according to the user's need.

Panels are primarily, but not necessarily, associated with fixtures, such as the legend, geosearch, or notifications panels.

### Appbar

The Appbar works alongside the panel system, and is used as a starting point for functionality in the app. The Appbar contains buttons used to manage panels for fixtures. Appbar buttons can also be configured to perform custom actions.

### Enhanced Mobile View

RAMP 4 works on mobile and desktop pages equally well without dropping features in either mode. The layout of the app will adapt to the resolution of the screen the app is displayed on. 

## 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](https://github.com/fgpv-vpgf/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.

### 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 avialable via the optional fixture `areas-of-interest`.

Back to Cart, Co-ordinate Info, or anything in the [Contributed Plugins](https://github.com/fgpv-vpgf/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 analagous to graphics in RAMP2 `SimpleLayer`s (#998)
- When loading CSV files via the import wizard, potential co-ordinate fields will not be pre-checked that 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

- Loading Map Image Layers from a Group Layer index may remain in a loading state (#1046) PENDING FIX

### Maptips

Changes to ESRI's [`hitTest`](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html#hitTest) during our development phase has introduced some undesireable 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. 

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

### Appbar

On the left size 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.

### 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.