praxis 0.18.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56c2fbb99665a6c0af6430bb7975fd82f469e58f
-  data.tar.gz: 8b8c200026e69903049082b28dc43cceaf2e8365
+  metadata.gz: 5c3c0d0844cabeb646b294a5a91b3c1fff24c848
+  data.tar.gz: edcb41f6707ec368f6a87f0f6273bc6aef558b7b
 SHA512:
-  metadata.gz: cd790aa9cb59f989310a1977e2b0584717973ed2ab4090a11643cdeb514227c9c504f6260214839e00ccb472170bf507e9de942129c95ce7f25ea913c71624b0
-  data.tar.gz: e4746483a28b0e48e39de2ee7b4dec0aaaa06714dc20112a9f306ce0141af1a525e60bc23a09765d5e124a30fd3263bf2c876f4c54f47f5c4482a9d57105c236
+  metadata.gz: afecbf0a00ee48c51eb9c49a1e0867431569e9136ef74a1e852800d143f5f672d276fa5ba80c1339629faf23d518d50067693ddb4f05702925fa4fb2071131f1
+  data.tar.gz: 6348cd21d00aa34085870a0b8af94a4939b31da4d00c962ab4dd49cb316a699a0412082db7e104c18bfb423a731000f04c86422d228be7ecb2ee156573d0afda

data/CHANGELOG.md

@@ -1,7 +1,63 @@
-# praxis changelog
+# Praxis Changelog
 
 ## next
 
+## 0.19.0
+
+* Handle loading empty `MediaTypeIdentifier` values (to return `nil`)
+* Doc browser now displays examples for action responses.
+* Added `Controller#media_type` helper that returns the `media_type` defined
+for the current response, or defaults to the one defined by the controller's
+resource definition.
+* Added assorted extensions, all under the `Praxis::Extensions` module:
+  * `FieldSelection` adds a new type, `Praxis::Extensions::FieldSelection::FieldSelector`
+    that wraps the `Attributor::FieldSelector` type and improves the definition
+    of parameters for a set of fields. Must be required explicitly from
+    'praxis/extensions/field_selection'.
+      * The parsed set of fields will be available as the `fields` accessor of
+      the loaded value.
+      * For example, to define a parameter that should take a set of fields
+      for a `Person` media type, you would define a `:fields` attribute in the
+      params like: `attribute :fields, FieldSelector.for(Person)`. The parsed
+      fields in the request would then be available with
+      `request.params.fields.fields`.
+  * `Rendering` adds `render` and `display` helper methods to controllers to
+  reduce common boilerplate in producing rendered representations of media types
+  and setting response "Content-Type" headers.
+    * `Controller#render(object, include_nil: false)` loads `object` into the
+    the current applicable `MediaType` (as from `Controller#media_type`) and
+    renders it using the fields provided by `Controller#expanded_fields` (from the
+      `FieldExpansion` extension).
+    * `Controller#display(object, include_nil: false)` calls `render` (above) with
+      `object`, assigns the result to the current `response.body`, sets the
+      response's "Content-Type" header to the appropriate MediaType identifier,
+      and returns the response.
+    * To use this extension, include it in a controller with
+      `include Praxis::Extensions::Rendering`.
+  * `MapperSelectors` adds `Controller#set_selectors`, which sets selectors
+    in the controller's `identity_map` to ensure any fields and associations
+    necessary to render the `:view` and/or `:fields` params specified in the
+    request are loaded for a given model when `identity_map.load(model)` is called.
+    * To use this extension, include it in a controller with
+      `include Praxis::Extensions::MapperSelectors`, and define `before`
+      callbacks on relevant actions that call `set_selectors`. For example:
+      `before actions: [:index, :show] { |controller| controller.set_selectors }`
+  * `FieldExpansion` provides a `Controller#expanded_fields` helper for
+  processing `:view` and/or `:fields` params to determine the final set fields
+  necessary to handle the request.
+    * Note: This is primarily an internal extension used by the `MapperSelectors`
+    and `Rendering` extensions, and is automatically included by them.
+* A slew of Doc browser improvements:
+  * Now uses the new JSON format for responses.
+  * Traits now get exposed in the doc browser.
+  * Now displays examples for requesting actions.
+  * Now correctly displays top-level collections in action payloads.
+  * Has improved scrolling for the sidebar.
+  * Displays more detailed HTML titles.
+  * Has been switched back to having a separate page per action, however actions are now shown in the sidebar.
+  * Will now display multiply nested resources in a proper hierarchy.
+* Fix doc generator to only output versions in index for which we have resources (i.e. some can be nodoc!)
+
 ## 0.18.1
 
 * Fix Doc Browser regression, which would not show the schema in the Resource Definition home page.

data/Gemfile

@@ -1,8 +1,9 @@
 source 'https://rubygems.org'
-
 gemspec
 
 group :test do
   gem 'nokogiri'
   gem 'builder'
+
+  gem 'parslet'
 end

data/README.md

@@ -1,12 +1,23 @@
-# Praxis [![TravisCI][travis-img-url]][travis-ci-url] 
+# Praxis [![TravisCI][travis-img-url]][travis-ci-url] [![Coverage Status][coveralls-img-url]][coveralls-url] [![Dependency Status][gemnasium-img-url]][gemnasium-url]
 
 [travis-img-url]: https://travis-ci.org/rightscale/praxis.svg?branch=master
 [travis-ci-url]:https://travis-ci.org/rightscale/praxis
+[coveralls-img-url]:https://coveralls.io/repos/rightscale/praxis/badge.svg?branch=master&service=github
+[coveralls-url]:https://coveralls.io/github/rightscale/praxis?branch=master
+[gemnasium-img-url]:https://gemnasium.com/rightscale/praxis.svg
+[gemnasium-url]:https://gemnasium.com/rightscale/praxis
 
-Praxis is a framework that takes a different approach to creating APIs, an approach that treats both designers and implementors as first class citizens and hold both their hands throughout the API building process. With Praxis you create an API by iterating through the design, review and implementation phases.
+Praxis is a framework for both _designing_ and _implementing_ APIs.
 
-Building APIs with Praxis will result in faster developer times, and result in very precise documentation that is apt for both human (web browsable) or machine consumption (JSON spec files). A very important feature of Praxis is that while the design and implementation phases are done independently, the resulting system will still ensure that they are always consistent and enforced at all times. This enforcement will automatically hold true throughout any number of iterations of the design-review-implementation phases. You can, once
-and for all, stop worrying about re-generating server code and keeping it in sync with any change to your code and or docs that you make.
+An important part of the framework is geared towards the _design_ aspect of building an API. This functionality empowers architects with tools to design every last aspect of their API, resulting in a complete, web-browsable documentation, which includes automatic generation of examples for resources, parameters, headers, etc...as well as requests and responses for the supported encodings. The design process is iterative, and flows from defining new resources, parameters, etc...to reviewing the resulting docs (usually with some of the potential clients of the API), back to updating the design based on feedback, or expanding it with more resources. The design language (i.e. DSL) of Praxis follows a clean 'ruby-type-syntax' and its final outcome is to generates an output that is both a set of schema documents as well as a web-based API browser (driven by those schemas). This allows Praxis to design APIs that can potentially be implemented in any language.
+
+Another important part of the framework is geared towards helping in the _implementation_ of the API service. In particular, Praxis provides help to Ruby developers for building a service conforming to the designed API. Aside from Ruby there is also sister-project called [Goa](http://goa.design/) that assists in implementing Praxis-like design API using Golang. Since the API design generates schema files very similar in nature to other API document formats like (Swagger, Google Discovery, RAML, etc...) supporting other implementation languages could be easily accomplished in the future by building converters to/from them.
+
+The part of the framework that helps with the ruby service implementation takes an approach that is different from other existing ruby (micro)frameworks such as [Grape](http://www.ruby-grape.org), [Sinatra](https://github.com/sinatra/sinatra), [Scorched](http://scorchedrb.com/), [Lotus](http://lotusrb.org/) or even [RailsAPI](https://github.com/rails-api/rails-api) (now part of Rails). Instead of being developer-centric, it takes an integrated approach treating both designers and implementors as first class citizens throughout the complete API building process. With Praxis you create an API by iterating through the design, review and implementation phases. While Praxis can help Ruby developers in a lot of aspects involved in building a service, the framework is completely componentized as to allow developers to pick and choose which parts to use, which ones not to use, and which other technologies to integrate with. The framework provides help in many areas, for example: all aspects of request and response validation, automatic type-coercion, consistent error-responses, routing and url generation, advanced template/media-type definition and rendering, domain-modeling, optional database ORM (for high-perfomance large datasets), DB integration (with an efficient identityMap), a plugin and extensible framework to easily hook into, available integrations such as newrelic, statsd, etc...
+
+There is a long list of benefits that come from using Praxis. From those, here are a couple of the salient themes:
+* Designing APIs with Praxis result in a very precise, consistent and beautiful API documentation that it is apt for both human (web browsable) or machine consumption (JSON spec files).
+* Building Ruby APIs with Praxis will result in much faster developer times, and more importantly with a resulting service that will ensure that its implementation is always consistent with its design, and it is enforced at all times.
 
 ## Quickstart
 ```bash
@@ -14,7 +25,7 @@ and for all, stop worrying about re-generating server code and keeping it in syn
 gem install praxis
 
 # Generate a praxis application named my-app in ./my-app
-praxis generate my-app
+praxis example my-app
 
 # Run it!
 cd my-app
@@ -22,29 +33,8 @@ bundle
 rackup
 ```
 
-## Philosophy
-Praxis is a practical implementation of a few guiding principles. In part:
-
-### REST APIs should be consistent
-REST APIs should follow consistent design in patterns and action semantics.
-This includes software patterns for creating applications like code
-organization; application patterns like logging, middleware, query filtering,
-and application bootstrapping; and API routing structures and REST verb
-semantics for exposed resources.
+Or better yet, checkout a simple, but functional [blog example app](https://github.com/rightscale/praxis-example-app) which showcases a few of the main design and implementation aspects that Praxis has to offer.
 
-### Apps should focus on real business logic
-Applications should be able to focus on application logic, avoiding most of the
-boilerplate code required to build API services.
-
-### API design should be separate from implementation
-Applications should maintain separation of concerns between API design and
-implementation. An API designer should be able to fully construct an API
-skeleton without writing a single line of application code.
-
-### APIs must have great documentation
-It should be possible to generate consistent and detailed documentation. This
-should be done by inspecting real code, to avoid relying on humans to do a good
-job keeping the docs and the code in sync everytime they make code changes.
 
 ## Mailing List
 Join our Google Groups for discussion, support and announcements.
@@ -54,6 +44,10 @@ Join our Google Groups for discussion, support and announcements.
 * [praxis-development](http://groups.google.com/d/forum/praxis-development) (discussion about the
   development of Praxis itself)
 
+Join our slack support and general announcements channel for on-the-spot answers to your questions:
+* To join our slack chat please go to: http://praxis-framework.herokuapp.com and sign in for an account.
+* Once you have an account, hop onto the chat at http://praxis-framework.slack.com
+
 And follow us on twitter: [@praxisapi](http://twitter.com/praxisapi)
 
 ## Contributions

data/lib/api_browser/app/index.html

@@ -1,16 +1,16 @@
 <!doctype html>
-<html>
+<html ng-app="DocBrowser">
 <head>
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
-  <title>API Browser</title>
+  <title ng-bind="subtitle ? title + ' – ' + subtitle : title">API Browser</title>
   <meta name="description" content="">
   <meta name="viewport" content="width=device-width">
   <!-- bower:css -->
   <!-- endbower -->
   <link rel="stylesheet" href="css/main.css">
 </head>
-<body ng-app="DocBrowser">
+<body>
   <div ui-view=""></div>
   <!-- build:js({.tmp,app}) scripts/praxis.js -->
   <!-- bower:js -->

data/lib/api_browser/app/js/app.js

@@ -1,6 +1,9 @@
 var app = angular.module('PraxisDocBrowser', ['ui.router', 'ui.bootstrap', 'ngSanitize']);
 
-app.config(function ($stateProvider, $urlRouterProvider) {
+app.config(function ($stateProvider, $urlRouterProvider, $uiViewScrollProvider) {
+
+  $uiViewScrollProvider.useAnchorScroll();
+
   $urlRouterProvider
     .otherwise('/');
 
@@ -22,7 +25,24 @@ app.config(function ($stateProvider, $urlRouterProvider) {
       url: '/:version/type/:type',
       templateUrl: 'views/type.html',
       controller: 'TypeCtrl'
-    }).state('root.controller.action', {
-      url: '/:action'
+    })
+    .state('root.action', {
+      url: '/:version/controller/:controller/:action',
+      templateUrl: 'views/action.html',
+      controller: 'ActionCtrl'
+    })
+    .state('root.trait', {
+      url: '/:version/trait/:trait',
+      templateUrl: 'views/trait.html',
+      controller: 'TraitCtrl'
+    })
+    .state('root.builtin', {
+      abstract: true,
+      url: '/builtin',
+      template: '<ui-view/>'
+    })
+    .state('root.builtin.field-selector', {
+      url: '/field-selector',
+      templateUrl: 'views/builtin/field-selector.html'
     });
 });

data/lib/api_browser/app/js/controllers/action.js

@@ -1,32 +1,44 @@
-app.controller('ActionCtrl', function($scope, $stateParams, Documentation, normalizeAttributes) {
+app.controller('ActionCtrl', function($scope, $stateParams, Documentation, normalizeAttributes, PageInfo) {
   $scope.controllerName = $stateParams.controller;
   $scope.actionName = $stateParams.action;
   $scope.apiVersion = $stateParams.version;
 
+  Documentation.controller($stateParams.version, $stateParams.controller).then(function(response) {
 
-  // Extract the example and attach it to each attribute
-  _.forEach(['headers', 'params', 'payload'], function(n) {
-    var set = $scope.action[n];
-    if (set) {
-      normalizeAttributes(set, set.type.attributes);
+    $scope.controller = response;
+    PageInfo.title = $scope.controller.display_name + ' » ' + $scope.actionName;
+    $scope.action = _.find(response.actions, function(action) { return action.name === $scope.actionName; });
+    if (!$scope.action) {
+      $scope.error = true;
+      return;
     }
-  });
-
-  $scope.responses = [];
-  _.forEach($scope.action.responses, function(response, name) {
-    response.name = name;
-    response.options = {
-      headers: response.headers
-    };
-    $scope.responses.push(response);
+    // Extract the example and attach it to each attribute
+    _.forEach(['headers', 'params', 'payload'], function(n) {
+      var set = $scope.action[n];
+      if (set) {
+        normalizeAttributes(set, set.type.attributes);
+      }
+    });
 
-    if(response.parts_like) {
-      response.parts_like.isMultipart = true;
-      response.parts_like.options = {
-        headers: response.parts_like.headers
+    $scope.responses = [];
+    _.forEach($scope.action.responses, function(response, name) {
+      response.name = name;
+      response.options = {
+        headers: response.headers
       };
-      $scope.responses.push(response.parts_like);
-    }
+
+      response.numExamples = _.keys(_.get(response, 'payload.examples')).length;
+
+      $scope.responses.push(response);
+
+      if(response.parts_like) {
+        response.parts_like.isMultipart = true;
+        response.parts_like.options = {
+          headers: response.parts_like.headers
+        };
+        $scope.responses.push(response.parts_like);
+      }
+    });
   });
 
   $scope.hasResponses = function() {

data/lib/api_browser/app/js/controllers/controller.js

@@ -1,32 +1,10 @@
-app.controller('ControllerCtrl', function($scope, $stateParams, Documentation, $anchorScroll, $timeout) {
+app.controller('ControllerCtrl', function($scope, $stateParams, Documentation) {
   $scope.controllerName = $stateParams.controller;
   $scope.apiVersion = $stateParams.version;
 
-  Documentation.getController($stateParams.version, $stateParams.controller).then(function(response) {
-    $scope.controller = response.data;
+  Documentation.controller($stateParams.version, $stateParams.controller).then(function(response) {
+    $scope.controller = response;
   }, function() {
     $scope.error = true;
   });
-
-  $scope.$on('$stateChangeSuccess', function(e, state, params) {
-    if (state.name == 'root.controller.action') {
-      (function scrollTo(id, time) {
-        if (angular.element('#' + id).length > 0) {
-          if (time > 20) {
-            $timeout(function() {
-              $anchorScroll.yOffset = angular.element('.header .navbar');
-              $anchorScroll(id);
-            }, 400);
-          } else {
-            $anchorScroll.yOffset = angular.element('.header .navbar');
-            $anchorScroll(id);
-          }
-        } else {
-          $timeout(function() {
-            scrollTo(id, 2 * time);
-          }, time);
-        }
-      })('action-' + params.action, 10);
-    }
-  });
 });

data/lib/api_browser/app/js/controllers/menu.js

@@ -2,53 +2,70 @@ app.controller('MenuCtrl', function($scope, $state, Documentation) {
   var parentLookup = {};
   $scope.versions = [];
   $scope.resources = {};
-  $scope.others = {};
+  $scope.schemas = {};
+  $scope.traits = {};
   $scope.selectedVersion = '';
   $scope.currentType = '';
   $scope.active = {};
 
-  var menuPromise = Documentation.getIndex().success(function(index) {
-    _.forEach(index, function(items, version) {
-      $scope.versions.push(version);
-      var resources = $scope.resources[version] = [];
-      var others = $scope.others[version] = [];
+  Documentation.versions().then(function(versions) {
+    $scope.versions = versions;
+    _.each(versions, function(version) {
+      Documentation.items(version).then(function(items) {
+        var resources = $scope.resources[version] = [];
+        var schemas = $scope.schemas[version] = [];
+        var traits = $scope.traits[version] = [];
+        var children = [];
+        _.each(items.resources, function(item, name) {
+          var link = { name: item.display_name, stateRef: '' };
 
-      _.forEach(items, function(item, name) {
-        var link = { name: name, stateRef: '' };
-        if (item.parent) {
-          link.parent = item.parent;
-        }
-        if (item.controller) {
-          parentLookup[item.controller] = link;
-          link.stateRef = $state.href('root.controller', { version: version, controller: item.controller });
-          link.typeName = item.controller;
-          resources.push(link);
-        } else if (item.media_type) {
-          link.stateRef = $state.href('root.type', { version: version, type: item.media_type });
-          link.typeName = item.media_type;
-          others.push(link);
-        } else if (item.kind) {
-          link.stateRef = $state.href('root.type', { version: version, type: item.kind });
-          link.typeName = item.kind;
-          others.push(link);
-        }
-      });
-      function getPath(r) {
-        if (r.parent) {
-          var path = getPath(parentLookup[r.parent]) + ':' + _.last(r.typeName.split('-'));
-          return path;
-        }
-        return _.last(r.typeName.split('-'));
-      }
-      $scope.resources[version] = _.map(_.sortBy(resources, getPath), function(r) {
-        r.grandfather = grandfatherType(r.typeName);
-        return r;
+          parentLookup[name] = link;
+          link.stateRef = $state.href('root.controller', { version: version, controller: name });
+          link.id = name;
+
+          link.actions = _.map(item.actions, function(action) {
+            var actionLink = { name: action.name, stateRef: '' };
+            parentLookup[name + '_action_' + action.name] = actionLink;
+            actionLink.parent = name;
+            actionLink.stateRef = $state.href('root.action', { version: version, controller: name, action: action.name });
+            actionLink.id = name + '_action_' + action.name;
+            actionLink.isAction = true;
+            actionLink.parentRef = link;
+            return actionLink;
+          });
+          link.childResources = [];
+          if (item.parent) {
+            link.parent = item.parent;
+            children.push(link);
+          } else {
+            resources.push(link);
+          }
+        });
+        _.each(items.schemas, function(item, name) {
+          var link = { name: item.display_name, stateRef: '' };
+          link.stateRef = $state.href('root.type', { version: version, type: item.id });
+          link.id = name;
+          schemas.push(link);
+        });
+        _.each(items.traits, function(item, name) {
+          var link = { name: name, stateRef: '' };
+          link.stateRef = $state.href('root.trait', { version: version, trait: name });
+          link.id = name;
+          traits.push(link);
+        });
+        _.each(children, function(link) {
+          if (parentLookup[link.parent]) {
+            link.parentRef = parentLookup[link.parent];
+            parentLookup[link.parent].childResources.push(link);
+          } else {
+            throw 'No parent resource found';
+          }
+        });
       });
     });
     var numeralVersions = _.filter($scope.versions, function(n) { return !isNaN(parseFloat(n)); })
                            .sort(function(a,b) { return parseFloat(b) - parseFloat(a); });
     $scope.selectedVersion = $state.params.version || numeralVersions[0] || $scope.versions[0];
-
   });
 
   $scope.select = function(version) {
@@ -59,25 +76,18 @@ app.controller('MenuCtrl', function($scope, $state, Documentation) {
     return $scope.resources[$scope.selectedVersion];
   };
 
-  $scope.availableOthers = function() {
-    return $scope.others[$scope.selectedVersion];
+  $scope.availableSchemas = function() {
+    return $scope.schemas[$scope.selectedVersion];
   };
 
-  function grandfatherType(id) {
-    var self = parentLookup[id];
-    if (self.parent) {
-      return grandfatherType(self.parent);
-    }
-    return id;
-  }
+  $scope.availableTraits = function() {
+    return $scope.traits[$scope.selectedVersion];
+  };
 
   $scope.$on('$stateChangeSuccess', function(e, state, params) {
     if (params.version) $scope.selectedVersion = params.version;
-    $scope.currentType = params.controller || params.type;
-    menuPromise.then(function() {
-      $scope.selectedGrandfatherType = params.controller && grandfatherType(params.controller);
-    });
-    $scope.active.resources = state.name !== 'root.type';
+    $scope.active.resources = state.name !== 'root.type' && state.name !== 'root.trait';
     $scope.active.schemas = state.name === 'root.type';
+    $scope.active.traits = state.name === 'root.trait';
   });
 });

data/lib/api_browser/app/js/controllers/trait.js

@@ -0,0 +1,10 @@
+app.controller('TraitCtrl', function ($scope, $stateParams, Documentation) {
+  $scope.traitName = $stateParams.trait;
+  $scope.apiVersion = $stateParams.version;
+
+  Documentation.trait($stateParams.version, $scope.traitName).then(function(data) {
+    $scope.trait = data;
+  }, function() {
+    $scope.error = true;
+  });
+});

data/lib/api_browser/app/js/controllers/type.js

@@ -4,16 +4,19 @@
   $scope.controllers = [];
   $scope.views = [];
 
-  Documentation.getType($stateParams.version, $scope.typeId).then(function(response) {
-    $scope.type = response.data;
-    $scope.views = _(response.data.views)
+  Documentation.type($stateParams.version, $scope.typeId).then(function(data) {
+    $scope.type = data;
+    $scope.views = _(data.views)
       .map(function(view, name) { return _.extend(view, { name: name }); })
       .select(function(view) { return view.name !== 'master'; })
       .value();
     normalizeAttributes($scope.type, $scope.type.attributes);
 
-    Documentation.getIndex().success(function(response) {
-      $scope.controllers = _.select(response[$scope.apiVersion], function(item) { return item.controller && item.media_type == $scope.type.name; });
+    Documentation.items($scope.apiVersion).then(function(response) {
+      $scope.controllers = _.select(response.resources, function(item, id) {
+        item.id = id;
+        return item.media_type.id == $scope.type.id;
+      });
     });
   }, function() {
     $scope.error = true;

data/lib/api_browser/app/js/directives/fixed_if_fits.js

@@ -10,8 +10,15 @@ app.directive('fixedIfFits', function($timeout) {
         var height = _(element.find('.tab-content .tab-pane').get()).map(function(el) {
           return angular.element(el).height();
         }).max() + element.offset().top;
-        if (height < $(window).height()) {
-          element[0].style.width = element.width() + 'px';
+        var mq = window.matchMedia('(min-width: 768px)');
+        if (height < $(window).height() && mq.matches) {
+          var padding = 20;
+          element[0].style.width = (element.width() + padding) + 'px';
+          element[0].style.paddingRight = padding + 'px';
+          var navbarHeight = '' + ($('.navbar').height() || 60) + 'px';
+          element[0].style.height = 'calc(100vh - ' + navbarHeight + ')';
+          element[0].style.paddingBottom = '30px';
+          element[0].style.overflow = 'auto';
           element[0].style.position = 'fixed';
         }
       }, 100);

data/lib/api_browser/app/js/directives/menu_item.js

@@ -0,0 +1,59 @@
+app.directive('menuItem', function($compile, $stateParams) {
+
+  function checkIfShouldShow(scope, params) {
+    var currentId = params.action ? params.controller + '_action_' + params.action : (params.controller || params.type || params.trait);
+    scope.isActive = scope.link.id === currentId;
+
+    function checkLink(link) {
+      if (link.id === currentId || link.parent === currentId) {
+        return true;
+      } else {
+        if (link.parentRef) {
+          var matches = function(r) { return r.id === currentId; };
+          if (!link.isAction) {
+            if ((link.parentRef.childResources || []).some(matches)) return true;
+          }
+          if ((link.parentRef.actions || []).some(matches)) return true;
+        }
+
+        return (link.childResources || []).some(checkLink) || (link.actions || []).some(checkLink);
+      }
+    }
+    scope.shouldShow = scope.toplevel || checkLink(scope.link);
+  }
+
+  function link(scope) {
+    scope.$on('$stateChangeSuccess', function(e, state, params) {
+      checkIfShouldShow(scope, params);
+    });
+    checkIfShouldShow(scope, $stateParams);
+  }
+
+  return {
+    restrict: 'E',
+    templateUrl: 'views/directives/menu_item.html',
+    scope: {
+      link: '=',
+      toplevel: '='
+    },
+    // hackery to make a recursive directive
+    compile: function(element) {
+      var contents = element.contents().remove();
+      var compiledContents;
+      return {
+        post: function(scope, element){
+          // Compile the contents
+          if(!compiledContents) {
+            compiledContents = $compile(contents);
+          }
+          // Re-add the compiled contents to the element
+          compiledContents(scope, function(clone) {
+            element.append(clone);
+          });
+
+          link(scope, element);
+        }
+      };
+    }
+  };
+});