New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

flow service: add support for query-strings in URLs #372

Closed
x1B opened this Issue Oct 11, 2016 · 1 comment

Comments

Projects
None yet
2 participants
@x1B
Member

x1B commented Oct 11, 2016

We'd like to be able to have optional routing arguments in the form of query parameters (?key=value&...). These should be converted transparently to/from payload data for navigation events (as long as the corresponding arguments are not formally declared for path segment matching).

@x1B

This comment has been minimized.

Show comment
Hide comment
@x1B

x1B Oct 12, 2016

Member

Upgrade Information

This change introduces deprecations, see below for details.

Place-parameters may now be represented in URLs as query-parameters in addition to the existing representation as path segments. This allows working with places that use multiple optional place parameters, without producing URLs that contain visible placeholders (e.g. instead of /some/place/v1/_/v3/_ you can now have /some/place/v1?param3=v3).

To use query-parameters in URLs, the LaxarJS configuration option flow.query.enabled must be set to true.

The following is true if query-parameters are enabled:

  • when navigating to a URL handled by LaxarJS, query-parameters are automatically translated into data items of the resulting didNavigate event. An exception is made for query-parameters that use the same name as regular place-parameters (path-segments) of the current place. In this case, place-parameters "win".
  • when navigating to a URL handled by LaxarJS, query-parameters without a value are also put into the resulting didNavigate event, with the value true. This allows to specify flags in a compact way.
  • in the flow definition (flow.json), defaults may be specified for query parameters of each place, using the new place property queryParameters. Strings, false and null are allowed as values. If e.g. { x: false, y: "34" } is specified, these are published with any didNavigate event, unless overridden. The default false is meant to complement the parameter-less query string syntax. A default of true is allowed syntactically, but makes no sense. The default null is mainly intended to allow documenting known query parameters.
  • when calculating a URL using axFlowService.constructAbsoluteUrl, query parameters are generated for any of the optional and/or active place parameters that
    • do not correspond to a regular path-segment-style place parameter, and that
    • are different from their default.
      If a place parameter has the value true, a value-less query parameter is generated.
  • when a navigateRequest event is processed by the flow service, the new URL is generated as by axFlowService.constructAbsoluteUrl. That is, query parameters are added as needed.

DEPRECATION INFORMATION

The following methods of the axFlowService are now deprecated:

  • constructAnchor -- this will probably create invalid or useless links if using HTML5 routing. Use constructAbsoluteUrl instead, which also works hash-based URLs as well as for HTML5 URLs.
  • constructPath -- this will probably create invalid or useless links if using query parameters. Use constructAbsoluteUrl instead, which works with and without query parameters.
  • place -- was only for internal use. Subscribe to didNavigate for relevant information.
Member

x1B commented Oct 12, 2016

Upgrade Information

This change introduces deprecations, see below for details.

Place-parameters may now be represented in URLs as query-parameters in addition to the existing representation as path segments. This allows working with places that use multiple optional place parameters, without producing URLs that contain visible placeholders (e.g. instead of /some/place/v1/_/v3/_ you can now have /some/place/v1?param3=v3).

To use query-parameters in URLs, the LaxarJS configuration option flow.query.enabled must be set to true.

The following is true if query-parameters are enabled:

  • when navigating to a URL handled by LaxarJS, query-parameters are automatically translated into data items of the resulting didNavigate event. An exception is made for query-parameters that use the same name as regular place-parameters (path-segments) of the current place. In this case, place-parameters "win".
  • when navigating to a URL handled by LaxarJS, query-parameters without a value are also put into the resulting didNavigate event, with the value true. This allows to specify flags in a compact way.
  • in the flow definition (flow.json), defaults may be specified for query parameters of each place, using the new place property queryParameters. Strings, false and null are allowed as values. If e.g. { x: false, y: "34" } is specified, these are published with any didNavigate event, unless overridden. The default false is meant to complement the parameter-less query string syntax. A default of true is allowed syntactically, but makes no sense. The default null is mainly intended to allow documenting known query parameters.
  • when calculating a URL using axFlowService.constructAbsoluteUrl, query parameters are generated for any of the optional and/or active place parameters that
    • do not correspond to a regular path-segment-style place parameter, and that
    • are different from their default.
      If a place parameter has the value true, a value-less query parameter is generated.
  • when a navigateRequest event is processed by the flow service, the new URL is generated as by axFlowService.constructAbsoluteUrl. That is, query parameters are added as needed.

DEPRECATION INFORMATION

The following methods of the axFlowService are now deprecated:

  • constructAnchor -- this will probably create invalid or useless links if using HTML5 routing. Use constructAbsoluteUrl instead, which also works hash-based URLs as well as for HTML5 URLs.
  • constructPath -- this will probably create invalid or useless links if using query parameters. Use constructAbsoluteUrl instead, which works with and without query parameters.
  • place -- was only for internal use. Subscribe to didNavigate for relevant information.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment