ember-route-shy-component

ember-route-shy-component

A component that won't render when the application's current route is on a blacklist.

Why

Often, an Ember application will have components or visual elements that are meant to be seen in some scenarios and hidden in others. In many cases, this is handled inherently by having different templates for different routes. In some cases, however, a component that lives in a top-level route -- a navbar, for example -- might need to have its visibility toggled dynamically based upon the current state of the application in a nested child route. ember-route-shy-component helps to handle this.

Basic Usage

ember install ember-route-shy-component

The route-shy component dynamically computes its isVisible property whenever the currentRouteName of the application is changed. If currentRouteName corresponds to any of the items in a blacklist -- through either string comparison or regular expression matching -- Ember will set the component's display property to none.

{{#route-shy blacklist=routesWhereNavbarIsHidden}}
  {{x-navbar}}
{{/route-shy}}

Configuring the Blacklist

Because it's meant to be an edge-case utility as opposed to a design driver, route-shy-component operates around a blacklist.

Regular expressions offer a powerful way to control where/when the component will be displayed. Any item in the blacklist that is a regular expression will be tested against currentRouteName. Otherwise, route-shy will attempt to perform a direct string comparison.

An effective approach for setting the list would be to prepare it as bound data -- in any of the places that your template would already be getting its data from.

A super-simplified example of using model data might looks like this:

<!-- application/routes.js -->

model () {
  return {
    navbar: {
      routesWhereHidden: [
        'application',
        /homepage(?:\.*)/,
        /login(?:\.*)/,
        /register(?:\.*)/
      ]
    }
    ....
  };

<!-- application/template.hbs -->

{{#route-shy blacklist=model.navbar.routesWhereHidden}}
  {{private-navbar}}
{{/route-shy}}

The blacklist could also be set "inline" with a string of spaced-separated names. By default, each name will be treated as a string (i.e, compared directly). You can, however, tell route-shy to treat theses names as regular expressions by setting the forceRegExp attribute to true.

{{#route-shy blacklist="foo bar baz(?:\.*)"}}
  {{private-navbar}}
{{/route-shy}}

Note that this is a far less practical approach than having your blacklist data/logic configured outside of the template. And any attempts to have inline strings tested as regular expressions must leave off the / characters otherwise associated within inline RegExp compilation -- as route-shy, internally will need to pass them to the JavaScript RegExp constructor.

Syncing with external data

As a convenience, route-shy can "sync" the results of its computed isVisible property with a property on a passed in object. This might be useful if another component is attempting to style itself relative to the visibility of components inside of a {{route-shy}} block (e.g., a page component that needs to toggle a padding offset depending on whether its top navbar is visible).

Usage is as simple as declaring an object to syncWith, along with a syncProperty on that object.

{{#route-shy
  blacklist=model.navbar.routesWhereHidden
  syncWith=model.navbar
  syncProperty="isVisible"}}

  {{private-navbar}}

{{/route-shy}}

Developing Locally

Installation

• git clone this repository
• npm install
• bower install

Running

• ember server
• Visit your app at http://localhost:4200.

Running Tests

• npm test (Runs ember try:testall to test your addon against multiple Ember versions)
• ember test
• ember test --server

Building

• ember build

For more information on using ember-cli, visit http://www.ember-cli.com/.