ember-hash-params
To send data into an Ember application, you usually want to do one of two things:
- Define a dynamic segment in the URL
- Use a query parameter for the route
However, in some cases you might not be able to use either -- if, for example, your URL contains information that you don't want to log to the server. In these cases it can be useful to define parameters through the hash; this addon makes this (somewhat) easier.
For example, you might want to send out a URL to your users that contain some kind of data that might be considered PII. It could look like this:
https://my-cool-deal-site.com#discount-code=123456
That discount code probably shouldn't be logged to your servers, so a query param or URL segment won't do. Since hashes aren't seen by the server, but are seen by the client, it can be a method for communicating without exposing PII to your server logs.
Throughout this documentation (and the code) when I refer to a hash param
, I mean a key-value pair like the one in the URL above. Like query params, they are delimited by an &
, so a couple of params would look like:
https://my-cool-deal-site.com#discount-code=123456&postal-code=94041
Installation
ember install ember-hash-params
Then, install the Router mixin
// app/router.js// ...; const Router = EmberRouter;// ...
Note: This addon depends on the router service polyfill. It will only be included if your Ember version is less than 2.15; you do not have to install it yourself.
Usage
Transitioning with Hash Params
Applying the above mixin allows transitions in Ember to set hash params, when they normally would be blown away by the transition. Much like query params, you specify the hash params at the point that you make the transition:
// app/foo/route.js; Route;
The above transition would set the value of the foo
hash param through the transition. If you wanted to just maintain the current value of all params, you could instead do something like:
// app/foo/route.js; const inject = Ember; Route;
Which would set all of the params after the transition to the value they had before it.
Getting and Setting Values Outside of Transitions
All of that isn't too helpful if you can't actually get the values again. The hashParams
service, however, allows for getting and setting the values in a way that will both update the URL and play nicely with Ember acceptance tests.
const hashParams = ;hashParams; // Return the value of the `foo` paramhashParams; // Return an object of all the params hashParams; // Set the `foo` param to `bar`hashParams; // Replace all hash params with the values in the given object
A Warning
Please -- for your own sake -- don't do this. Don't use this addon; use query params. Ember supports them really nicely, and (while often annoying) they at least are accounted for by the framework's routing model. This is, by all means, a hack.
However, if you have to use hash params (as I do) then this provides an interface for using them that plays nice enough with the Ember router that you can write Acceptance tests that will behave the way you expect them to.