flow (v2.x): differentiate target and place in navigation events

[x1B]

As outlined in #373, there is currently no way to distinguish between flow-targets (relations from one place to another) and flow-places in navigation events. Both have valid use cases, and both can be used in navigateRequest events, although the event field is named target. However, it is not really obvious what happens if the current place uses a target that is also the name of a place. Further, place names may contain URL syntax, which is not actually allowed for use in event bus topics.
When navigating directly by using links, the target is always set to _self, which is usually incorrect.

Updated/Final/This-Time-For-Real Proposal for Target/Place Distinction

• we distinguish between places and their patterns,
• place names (keys in the places object of the flow definition), like targets, must be valid topics,
• targets and place names may be used as target in navigateRequest events. If the current place has a matching target, that always takes precedence over a place of the same name,
• each place may specify an array of patterns, which are only interpreted by the router (in our case page.js) and are used for interpretation as well as for generation of URLs,
• redirects may specify place parameters for their destination place, using the new redirectParameters.

The previous proposals, for history completeness only:

New Proposal for Target/Place Distinction

• widgets only ever know about and navigate to targets -- never to places,
• in addition to the existing place targets (or relations) there are now global targets, which are defined top-level in the flow definition,
• places can override the global targets by specifying a target of the same name,
• to reference places within the flow definition (e.g. for redirects, and for the right-hand-side of the target definition), the full place name (the URL pattern) must always be specified. This allows us to support more flexible URL patterns and/or alternative routers in the future (flow: pluggable routing #393),
• in the future, we may add names/aliases for the places, to avoid repeating the URL patterns throughout the flow definition,
• entry points / exit points: remove. Too complicated, overly specific (flow (v2.x): remove entry point / exit point functionality #392).

Previous Proposal (just for informational purposes)

What we'd like:

• allow to use "place" instead of "target" in navigateRequests, omitting the place name in the event topic for now,
• in willNavigate, use the resolved place (and the target if available),
• in didNavigate, use the same parameters as willNavigate.

[x1B]

changed description: clarified event parameters

[alex3683]

We also need to add target and place aware apis for the flow service.

[alex3683]

If both place and target are given in the navigateRequest event, an error should be logged (i.e. throw).

[x1B]

Marked breaking because place/target will now need to be differentiated both in navigateRequest events and constructAbsoluteUrl calls.

[x1B]

Updated description to clarify where places/targets will be used in the future

[x1B]

Updated, again

[x1B]

Implemented on master (v2.0.0).

Breaking Change

The format of the flow definition has changed along with the configuration options:

• Routing patterns for places in the flow definition are no longer used as place-IDs,
• From now on, each place ID must be a valid topic,
• Each place may specify an arbitrary number of patterns as an array within the place definition,
• A much larger number of patterns are now supported, namely a large subset of the patterns supported by page.js,
• if no patterns are given, [ "/placeId" ] is used by default (for a place named placeId),
• To reference places (e.g. from targets), the place ID is used (not one of the patterns),
• Router configuration is now set under the key router (router.base, router.query.enabled, router.pagejs).

For details, consult the updated flow manual.