Merge pull request #12051 from EricSchank/patch-1

[DOC release] document current-when argument for link-to #12038

packages/ember-routing-htmlbars/lib/keywords/link-to.js

@@ -140,6 +140,35 @@ import merge from 'ember-metal/merge';
   To override this option for your entire application, see
   "Overriding Application-wide Defaults".
 
+  ### Keeping a link active for other routes
+
+  If you need a link to be 'active' even when it doesn't match
+  the current route, you can use the the `current-when`
+  argument.
+
+  ```handlebars
+  {{#link-to 'photoGallery' current-when='photos'}}
+    Photo Gallery
+  {{/link-to}}
+  ```
+
+  This may be helpful for keeping links active for:
+
+  * non-nested routes that are logically related
+  * some secondary menu approaches
+  * 'top navigation' with 'sub navigation' scenarios
+
+  A link will be active if `current-when` is `true` or the current
+  route is the route this link would transition to.
+
+  To match multiple routes 'space-separate' the routes:
+
+  ```handlebars
+  {{#link-to 'gallery' current-when='photos drawings paintings'}}
+    Art Gallery
+  {{/link-to}}
+  ```
+
   ### Supplying a model
   An optional model argument can be used for routes whose
   paths contain dynamic segments. This argument will become