Event Tricks on Non-Fixture Events

[james-rae]

(note this exists in HackMD but duplicating here to keep a this repo full)
(Also, may be worth reading #22 first if you feel you lack context)

In reviewing the candidates for "default" events, it became apparent that there are only a handful of fixture-to-fixture events, and many more core-to-fixture events.

The current proposal of the Events API is very fixture centric, and does not support listening to core events on the main bus (e.g. something like detailsFixture.on('map-click', ...) does not make sense, as the map click event is from the core).

Example

Will use this for all the proposals below as well. Imagine we have a RAMP that only consists of the map, the default grid, and the default details panel.

Our default event interactions are:

• Grid "show details" button will raise a GRID event, details panel will react and show info (pane 3)
• Clicking the map will execute the identify process, raise a GLOBAL event, details panel will react and show results (pane 1)

Current Design

Using the current design (see the blocked PR for it in action), and the concepts in the proposal for default fixtures and events, the event handlers would be defaulted in the following way.

• The grid-to-details event handler would be registered using the grid fixture's on(). It would have a specific, documented handler name, and the handler can be easily removed using that name to target it.
• The map-to-details event handler would be registered using the instance's on(). This has no concept of handler names, and to remove the handler one would need the event name and a pointer to the handler function.

Potential Problem

As shown above, if an implemented wants to remove the defaulted map-to-details event handler, they would need to somehow find the address of the handler function. Likely this will be unreachable inside the core, or they will need some obscure code fragment to get it.

Below are some proposals for how to adjust things to give the same level of flexibility for core events that fixture events currently enjoy.

Idea 1: Event API spreads beyond Fixtures

Involves taking the basecode currently in the blocked PR, and allow it to be applied to other objects. E.g. API map. API "core".

To implement, the set of Event API methods & underlying data structures probably has to become a mixin type thing, or a subobject (i.e. instead of legendFixture.on(...), would be legendFixture.events.on(...)).

Using the above example, this is how modification to default events might work.

const gridFixture = rInstance.fixture.get('grid');
const map = rInstance.map; // this doesn't exist now, but would be analagous to RAMP2 API Map thing

gridFixture.off('grid-to-details-default-name');
map.off('mapclick-to-details-default-name');

Pros:

• Would have a consistent approach all over.
• Code re-use for event management

Cons:

• Certain names become reserved. I.e. could not have a fixture named map as it will collide with events from map
• Has the risk where if objects get recreated, all the events stored on them get killed. Likely a problem for stuff like reprojection.
• Person using these APIs needs to know which object to fetch to access a certain event or handler. Documentation can help but still is more complex than current setup.

Idea 2: Add names to Global Bus

Similar to Idea 2, but instead of using other sub-objects, we just apply the same Event API interface to the global bus. In particular, allow event handlers to have names.

Using the above example, this is how modification to default events might work.

const gridFixture = rInstance.fixture.get('grid');

gridFixture.off('grid-to-details-default-name');
rInstance.off('mapclick-to-details-default-name');

Pros:

• Main bus on/off will now have consistent method signatures with fixtures
• Finding event locations is slightly easier than Idea 1.

Cons:

• More params & wrappers on the main bus interface.

Idea 3: Push it all to global bus

Effectively move the fixture event api thing to the main bus, and everyone just uses that. Fixtures no longer have their own event registration functions.

To help with event discovery, Fixtures could register the event names they expose to the instance during their loaded() phase, so one can request a list of available event names from the instance. There could be an optional param to filter by event name prefix (i.e. fixture name).

Using the above example, this is how modification to default events might work.

rInstance.off('grid-to-details-default-name');
rInstance.off('mapclick-to-details-default-name');

Pros:

• Allows fixture event handlers to be set up before fixtures exist. Something none of the other solutions provide
• Allows an item (fixture, map, etc) to be replaced or refreshed and the event handler will remain in tact. As long as new item uses same event names it should just continue to work.
• Only one spot to register/unregister events. Simplicity?

Cons:

• More params and wrappers on the global bus.
• Knowing the event name to use is a bit more convoluted. Good docs and event names function will help, but still not ideal.

Further Considerations

We may have event handlers that are essential to the inner workings of the RAMP core. If we pick a solution that allows full manipulation of the global bus, we may need a way to flag certain events as locked or private, so that requests via the various API would not be allowed to muck with them. Or alternately they put a warning on the cosole telling the author they are being naughty, but still allowing maximum freedom for the various hacking initiatives.

Old James Hot Take

At the moment the Pros/Cons balance of Idea 3 seem most appealing. That said I have a nagging feeling there is some other consideration I'm missing, and this is why this was not selected in the initial design.

[james-rae]

The consensus was to use "Idea 3 - Global Bus Party". This one had good options and was easiest to pivot away from at a later point in time if we require something fancier.