Query-Params Lifecycle is Unpredictable, Inconsistent

[jamesarosen]

Overview

The guides for query-params discuss at length how to set query-params, including customizations. They do not, however, formally specify the lifecycle of query-params. Specifically, the following are left unspecified:

• at what point in a transition are query-params synced from the Location to the Controller?
• at what point in a transition are query-params synced from the Controller to the Location?

This ember-twiddle demonstrates some oddities:

1. Load / directly (by typing it into the location bar and pressing Enter). The value from the Controller is "defaultValue", which is the value the Controller specifies as the default. The value from transition.queryParams.q is null. In the Route's model hook, the Controller's value is the default value.
2. Load /?q=something directly. The value from the Controller is "something". The value of transition.queryParams.q is still null. (I think this particular issue is related to the application running in an iframe.) The value that the Route's model hook sees from the controller is "defaultValue", meaning the query-param hasn't been synced to the Controller.
3. Load /?q=forbidden directly. This acts just like the /?q=something case. But if you click the /?q=something link in the footer and then the /?q=forbidden link, it changes. The serializeQueryParam kicks in, changing "forbidden" to null, which affects the location and the value from the Controller. This shows that serializeQueryParam is invoked on every transition after the first.
4. Load /?v=123 directly. Because v isn't declared as a query-param, Ember strips it from the URL. This shows that invalid query-params, but not valid ones are re-serialized during the first transition.

Recommendations

I do not yet have a clear, holistic implementation in mind. I think the following requirements are a bare minimum:

1. Define when transition.queryParams are available and what effects modifications to that object will have.
2. Serialize all query-params back to the Location some time during the first transition just like all other transitions.
3. Define where in the transition (e.g. "before beforeModel" or "between afterModel and setupController") query-params will be synced between the Location and the Controller.
4. Allow routes to manipulate query-params at some point during the beforeModel/model/afterModel/setupController flow.

Use Cases

• A query-param that lets admin users see other users' accounts. The application doesn't know whether the current user is an admin until after the session is established (say, route:application#model). If a non-admin goes to /some-path?userId=3456, the route should clear that query-param after it is established the user lacks permissions.
• A query-param that represents some split-testing state. The user navigates to /some-path and the application generates a split-testing ID on-the-fly, then sets it as a query-param. The Location should immediately reflect this ID. (Having this ID in the URL could make it easier when handling support tickets since it would be clear which version of the interface they were using.)

Existing Work

ember-query-params attempts to move some of the query-param logic into a service. This is good for encapsulating logic around validating, filtering, and manipulating query-params, but doesn't address the lifecycle issues.

Unresolved questions

• When are query-params synced from Location to Controller?
• When are query-params synced from Controller to Location?
• When should they be?

[jamesarosen]

I originally opened this as emberjs/rfcs#192, but @rwjblue suggested I switch to an Issue until we have some sort of implementation plan, which will then become the RFC.

Related: #9819, #11592.

See also http://stackoverflow.com/q/35192211/1190, which works in an action handler, but not in a route hook like afterModel.

[pixelhandler]

@jamesarosen Nice write up :)

I'm curious about where this issue needs to be tracked, Did @rwjblue suggest and Ember.js/issue or and RFC/issue ?

See, ​See CONTRIBUTING.md#requesting-a-feature which recommends creating an RFC Issue to request a feature/enhancement (no need for a PR with RFC, only an issue in the repo)

[jamesarosen]

I'm curious about where this issue needs to be tracked, Did @rwjblue suggest and Ember.js/issue or and RFC/issue ?

As I said above,

I originally opened this as emberjs/rfcs#192, but @rwjblue suggested I switch to an Issue

I assumed he meant an emberjs Issue, but I guess it could have been an RFC Issue. There are many RFC Issues, but the RFC docs don't describe their use-case.

From CONTRIBUTING:

Use RFC issues to propose a rough idea, basically a great place to test the waters.

I think that's exactly the case for this. I wish that information were in the RFC README as well. I had no idea.

[locks]

@jamesarosen @pixelhandler can y'all take care of improving CONTRIBUTING and moving this issue to an rfcs repo issue? Thanks!

[jamesarosen]

Moved to emberjs/rfcs#196