praxis 0.18.1 → 0.19.0

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

@@ -0,0 +1,87 @@
+app.factory('Repeater', function() {
+  function Repeater(expression) {
+    var match = expression.match(/^\s*([\s\S]+?)\s+in\s+([\s\S]+?)(?:\s+as\s+([\s\S]+?))?(?:\s+track\s+by\s+([\s\S]+?))?\s*$/);
+
+    var lhs = match[1];
+    this.rhs = match[2];
+    this.aliasAs = match[3];
+    this.trackByExp = match[4];
+
+    match = lhs.match(/^(?:(\s*[\$\w]+)|\(\s*([\$\w]+)\s*,\s*([\$\w]+)\s*\))$/);
+
+    this.valueIdentifier = match[3] || match[1];
+    this.keyIdentifier = match[2];
+  }
+
+  Repeater.prototype.$watch = function(fn) {
+    this.$scope.$watchCollection(this.rhs, fn);
+  };
+
+  Repeater.prototype.$transclude = function(length, value, key, index, fn) {
+    var self = this;
+    self._transclude(function(clone, scope) {
+      scope[self.valueIdentifier] = value;
+      if (self.keyIdentifier) scope[self.keyIdentifier] = key;
+      scope.$index = index;
+      scope.$first = (index === 0);
+      scope.$last = (index === (length - 1));
+      scope.$middle = !(scope.$first || scope.$last);
+      // jshint bitwise: false
+      scope.$odd = !(scope.$even = (index&1) === 0);
+      // jshint bitwise: true
+      fn(clone, scope);
+    });
+  };
+
+  return {
+    compile: function(repeatAttr, linkFn) {
+      return function(element, attrs) {
+        var expression = attrs[repeatAttr];
+        var repeater = new Repeater(expression);
+        return function($scope, $element, $attr, ctrl, $transclude) {
+          repeater._transclude = $transclude;
+          repeater.$scope = $scope;
+          linkFn($scope, $element, $attr, ctrl, repeater);
+        };
+      };
+    }
+  };
+});
+app.directive('readableList', function(Repeater) {
+
+  return {
+    restrict: 'E',
+    transclude: true,
+    compile: Repeater.compile('repeat', function($scope, $element, $attr, ctrl, $repeat) {
+      $repeat.$watch(function(inputList) {
+        $element.empty();
+        if (inputList.length == 1) {
+          $repeat.$transclude(1, inputList[0], null, 0, function(clone) {
+            $element.append(clone);
+          });
+        } else {
+          var finalJoin = ' and ';
+
+          var join = ', ',
+              arr = inputList.slice(0),
+              last = arr.pop(),
+              beforeLast = arr.pop();
+
+          _.each(arr, function(data, index) {
+            $repeat.$transclude(inputList.length, data, null, index, function(clone) {
+              $element.append(clone);
+              $element.append(document.createTextNode(join));
+            });
+          });
+          $repeat.$transclude(inputList.length, beforeLast, null, inputList.length - 2, function(clone) {
+            $element.append(clone);
+            $element.append(document.createTextNode(finalJoin));
+          });
+          $repeat.$transclude(inputList.length, last, null, inputList.length - 1, function(clone) {
+            $element.append(clone);
+          });
+        }
+      });
+    })
+  };
+});

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

@@ -0,0 +1,16 @@
+/**
+ * This directive is responsible to render a URL for an action
+ */
+app.directive('url', function() {
+  return {
+    restrict: 'EA',
+    scope: {
+      action: '=',
+      example: '@'
+    },
+    templateUrl: 'views/directives/url.html',
+    link: function(scope, element, attrs) {
+      scope.showExample = scope.example == 'example' || scope.example == 'true' || 'example' in attrs;
+    }
+  };
+});

data/lib/api_browser/app/js/factories/Configuration.js

@@ -7,7 +7,6 @@ app.provider('Configuration', function() {
   this.$get = function() {
     return this;
   };
-}).run(function(Configuration, $rootScope, $document) {
+}).run(function(Configuration, $rootScope) {
   _.extend($rootScope, _.omit(Configuration, '$get'));
-  $document[0].title = Configuration.title;
 });

data/lib/api_browser/app/js/factories/Documentation.js

@@ -1,13 +1,55 @@
-app.factory('Documentation', function($http) {
+/**
+ * This service gives access to the documentation metadata
+ */
+app.factory('Documentation', function($http, $q) {
+  var versions = $q.when($http.get('api/index-new.json', { cache: true }).then(function(data) {
+    return $q.all(_.map(data.data.versions, function(version) {
+      return $http.get('api/' + version + '.json', {cache: true}).then(function(versionData) {
+        return [version, versionData.data];
+      });
+    })).then(_.zipObject);
+  }));
+
   return {
-    getIndex: function() {
-      return $http.get('api/index.json', { cache: true });
+    /**
+     * Returns an array of version strings
+     */
+    versions: function() {
+      return versions.then(_.keys);
     },
-    getController: function(version, name) {
-      return $http.get('api/' + version + '/resources/' + name + '.json', { cache: true });
+    /**
+     * Returns a list of controllers and types, useful for generating navigation
+     */
+    items: function(version) {
+      return versions.then(function(v) { return v[version]; });
     },
-    getType: function(version, name) {
-      return $http.get('api/' + version + '/types/' + name + '.json', { cache: true });
+    /**
+     * Returns description of a controller
+     */
+    controller: function(version, name) {
+      return this.items(version).then(function(v) {
+        var controller = v.resources[name];
+        controller.id = name;
+        return controller;
+      });
+    },
+
+    /**
+     * Returns a description of a type
+     */
+    type: function(version, name) {
+      return versions.then(function(v) {
+        return v[version].schemas[name];
+      });
+    },
+
+    /**
+     * Returns a description of a trait
+     */
+    trait: function(version, name) {
+      return versions.then(function(v) {
+        return v[version].traits[name];
+      });
     }
   };
 });

data/lib/api_browser/app/js/factories/PageInfo.js

@@ -0,0 +1,9 @@
+app.service('PageInfo', function($rootScope) {
+  this.title = null;
+  var self = this;
+  $rootScope.$watch(function() {
+    return self.title;
+  }, function() {
+    $rootScope.subtitle = self.title;
+  });
+});

data/lib/api_browser/app/js/factories/normalize_attributes.js

@@ -2,11 +2,10 @@ app.factory('normalizeAttributes', function() {
   function normalize(type, attributes, parent) {
     _.forEach(attributes, function(attribute, name) {
       var path = parent.concat([name]);
-      var example = JSON.stringify(_.get(type.example, path), null, 2);
       if (!attribute.options) attribute.options = {};
-      if (example) attribute.options.example = example;
       if (attribute.values != null) attribute.options.values = attribute.values;
       if (attribute.default != null) attribute.options.default = attribute.default;
+      if (attribute.example != null) attribute.options.example = attribute.example;
       if (attribute.type && attribute.type.attributes) {
         normalize(type, attribute.type.attributes, path);
       }

data/lib/api_browser/app/js/factories/template_for.js

@@ -36,6 +36,8 @@ app.provider('templateFor', function() {
       switch ($family) {
         case 'hash':
           return 'views/types/standalone/struct.html';
+        case 'array':
+          return 'views/types/standalone/array.html';
         default:
           return 'views/types/standalone/default.html';
       }
@@ -48,6 +50,9 @@ app.provider('templateFor', function() {
       if ($type === 'Links') {
         return 'views/types/embedded/links.html';
       }
+      if ($type === 'Praxis::Extensions::FieldSelection::FieldSelector') {
+        return 'views/types/embedded/field-selector.html';
+      }
       switch ($family) {
         case 'hash':
           return 'views/types/embedded/struct.html';
@@ -60,14 +65,14 @@ app.provider('templateFor', function() {
   this.register(function labelResolver($typeDefinition, $requestedTemplate, primitives) {
     'ngInject';
     if ($requestedTemplate === 'label') {
-      if (_.contains(primitives, $typeDefinition.name)) {
-        return 'views/types/label/primitive.html';
-      } else if ( $typeDefinition.member_attribute !== undefined ) {
-        if ( _.contains(primitives, $typeDefinition.member_attribute.type.name)){
+      if ( $typeDefinition.member_attribute !== undefined) {
+        if ($typeDefinition.member_attribute.anonymous || _.contains(primitives, $typeDefinition.name)) {
           return 'views/types/label/primitive_collection.html';
         } else{
           return 'views/types/label/type_collection.html';
         }
+      } else if ($typeDefinition.anonymous || _.contains(primitives, $typeDefinition.name)) {
+        return 'views/types/label/primitive.html';
       } else if ($typeDefinition.link_to) {
         return 'views/types/label/link.html';
       }

data/lib/api_browser/app/sass/modules/_sidebar.scss

@@ -3,9 +3,6 @@
 // ------------------------------
 
 .sidebar {
-  @media (min-width: $screen-sm-min) {
-    width: 160px;
-  }
   @media (min-width: $screen-lg-min) {
     width: 250px;
   }
@@ -20,25 +17,66 @@
 }
 
 .sidebar {
+  .open .dropdown-menu {
+    margin-left: 15px;
+  }
   .list-group {
     margin-bottom: 0;
     margin-top: 0;
-  }
-  .list-group-item {
-    border-width: 1px 0;
-    word-break: break-word;
-    &:first-of-type {
+    & > menu-item:first-of-type > .menu-item {
       border-radius: 0;
       border-top: 0 none;
     }
-    &:last-of-type {
-      border-bottom: 0 none;
-    }
-    &.child-resource {
-      padding-left: 2.5em;
+  }
+  .action {
+    background: $table-bg-accent;
+    font-size: 11px;
+    font-weight: bolder;
+  }
+  .menu-item {
+    position: relative;
+    display: block;
+    // Place the border on the list items and negative margin up for better styling
+    margin-bottom: -1px;
+    background-color: $list-group-bg;
+    border: 1px solid $list-group-border;
+    border-width: 1px 0;
+    word-break: break-word;
+    a {
+      display: block;
+      padding: 10px 15px;
+      // Hover state
+      &:hover,
+      &:focus {
+        text-decoration: none;
+        background-color: $list-group-hover-bg;
+      }
+
+      // Active class on item itself, not parent
+      &.active,
+      &.active:hover,
+      &.active:focus {
+        z-index: 2; // Place active items above their siblings for proper border styling
+        color: $list-group-active-color;
+        background-color: $list-group-active-bg;
+        border-color: $list-group-active-border;
+        font-weight: bolder;
+      }
     }
-    &.group-selected {
-      border-left: 2px solid $link-color;
+    .menu-item {
+      a.action { padding: 10px 2.5rem; }
+      a.main { padding: 10px 2rem; }
+      a.main::before {
+        content: "↳"
+      }
+      .menu-item {
+        a.action { padding: 10px 3.5rem; }
+        a.main { padding: 10px 3rem; }
+        .menu-item {
+          a.action { padding: 10px 4.5rem; }
+          a.main { padding: 10px 4rem; }
+        }
+      }
     }
   }
 }
@@ -73,6 +111,7 @@
       a {
         border-bottom: 0;
         font-size: 12px;
+        padding: 10px 5px;
         &:hover {
           background-color: #fff;
           border-color: transparent;

data/lib/api_browser/app/sass/praxis.scss

@@ -53,3 +53,7 @@
     }
   }
 }
+
+h4, h5 {
+  font-weight: 600;
+}

data/lib/api_browser/app/views/action.html

@@ -4,72 +4,103 @@
 <div ng-if="action">
   <div class="row">
     <div class="col-lg-12">
-      <h2>
-        {{ action.name }}
-      </h2>
-      <p ng-repeat="url in action.urls">
-        <span class="label label-default verb" ng-class="url.verb | lowercase">{{ url.verb }}</span> <b>{{ url.path }}</b>
-      </p>
+      <h1>
+        <a ui-sref="root.controller({version: apiVersion, controller: controller.id})">{{controller.display_name}}</a> » {{ action.name }}
+      </h1>
+      <url action="action"></url>
       <p ng-bind-html="action.description | markdown"></p>
+      <p class="traits" ng-if="action.traits.length > 0">
+        This action is&nbsp;
+        <readable-list repeat="trait in action.traits"><a ui-sref="root.trait({version: apiVersion, trait: trait})">{{trait}}</a></readable-list>.
+      </p>
     </div>
   </div>
 
   <div class="row" ng-if="action.headers.type.attributes">
     <div class="col-lg-12">
-      <h3>Request Headers</h3>
+      <h2>Request Headers</h2>
       <type-placeholder details="action.headers.type.attributes" type="action.headers.type" template="standalone"></type-placeholder>
     </div>
   </div>
 
   <div class="row" ng-if="action.params.type.attributes">
     <div class="col-lg-12">
-      <h3>Request Parameters</h3>
+      <h2>Request Parameters</h2>
       <type-placeholder details="action.params.type.attributes" type="action.params.type" template="standalone"></type-placeholder>
     </div>
   </div>
 
   <div class="row" ng-if="action.payload.type">
     <div class="col-lg-12">
-      <h3>Request Body</h3>
+      <h2>Request Body</h2>
       <type-placeholder type="action.payload.type" template="standalone" details="action.payload.type.attributes"></type-placeholder>
     </div>
   </div>
 
+  <div class="row">
+    <div class="col-lg-12">
+      <h2>Request Example</h2>
+      <div ng-if="!action.payload.examples">
+        <h4>URL</h4>
+        <url action="action" example></url>
+        <div ng-if="action.headers.example">
+          <h4>Headers</h4>
+          <pre><span ng-repeat="(header, value) in action.headers.example">{{header}}: {{value}}
+</span></pre>
+        </div>
+      </div>
+      <tabset ng-if="action.payload.examples">
+        <tab ng-repeat="(type, example) in action.payload.examples" heading="{{type}}">
+          <h4>URL</h4>
+          <url action="action" example></url>
+          <div ng-if="action.headers.example">
+            <h4>Headers</h4>
+            <pre><span ng-if="example.content_type">Content-Type: {{example.content_type}}
+</span><span ng-repeat="(header, value) in action.headers.example">{{header}}: {{value}}
+</span></pre>
+          </div>
+          <h4>Request body</h4>
+          <pre>{{ example.body }}</pre>
+        </tab>
+      </tabset>
+    </div>
+  </div>
+
   <div class="row" ng-if="hasResponses()">
     <div class="col-lg-12">
-      <h3>Responses</h3>
-      <div class="table-responsive">
-        <table class="table table-striped table-bordered">
-          <thead>
-            <tr>
-              <th>Code</th>
-              <th>Name</th>
-              <th>Media Type</th>
-              <th>Description</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr ng-repeat="response in responses">
-              <td>
-                <span ng-if="response.isMultipart">
-                  <em>Parts Like:</em>
-                </span>
-                <span>{{response.status}}</span>
-              </td>
-              <td>
-                {{response.name}}
-              </td>
-              <td>
-                {{response.media_type.id || response.media_type.identifier}}
-              </td>
-              <td>
-                <attribute-description attribute="response"></attribute-description>
-              </td>
-            </tr>
-          </tbody>
-        </table>
+      <h2>Responses</h2>
+      <div class="panel panel-default" ng-repeat="response in responses">
+        <div class="panel-heading"><h4 class="panel-title">{{response.name}}</h4></div>
+        <div class="panel-body">
+          <div class="row">
+            <div class="col-md-4">
+              <h5>Status</h5>
+              <p>{{ response.status }}</p>
+              <div ng-if="response.examples.json">
+                <h5>Content-Type</h5>
+                <p>{{ response.examples.json.content_type }}</p>
+              </div>
+              <div ng-if="response.payload.id">
+                <h5>Media Type</h5>
+                <p><type-placeholder template="label" type="response.payload"></type-placeholder></p>
+              </div>
+            </div>
+            <div class="col-md-8">
+              <div ng-if="response.payload.examples">
+                <h5>Response Example</h5>
+                <tabset ng-if="numExamples > 1">
+                  <tab ng-repeat="(type, example) in response.payload.examples" heading="{{type}}">
+                    <pre>{{ example.body }}</pre>
+                  </tab>
+                </tabset>
+                <div ng-if="response.numExamples == 1">
+                  <pre ng-repeat="(type, example) in response.payload.examples">{{ example.body }}</pre>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
       </div>
     </div>
   </div>
 </div>
-<hr class="action-divider" />

data/lib/api_browser/app/views/builtin/field-selector.html

@@ -0,0 +1,24 @@
+<div class="row">
+  <div class="col-lg-12">
+    <h1 class="page-header">FieldSelector</h1>
+
+    <p>Field Selectors allow you to specify in a request exactly what data you
+      wish to recieve in the response. This allows the client to get an efficient
+      response with only the fields required.</p>
+    <p>The fields can come from the endpointʼs associated Schema, or from an
+      attribute exposed in any of the views of the resource. Multiple fields are
+      separated by commas.</p>
+    <p>You can also select properties from nested schemas from parent schema
+      using curly braces. For example <code>title,user{name,email}</code> would lead to a
+      response like this:</p>
+    <pre>{
+  "title": "Nice Blog Post",
+  "user": {
+    "name": "John Appleseed",
+    "email": "john@example.com"
+  }
+}</pre>
+    <p>If you do not specify attributes of nested properties, the <code>default</code>
+      view will be used to render them.</p>
+  </div>
+</div>

data/lib/api_browser/app/views/controller.html

@@ -7,7 +7,13 @@
       <h1 class="page-header">
         {{ controller.name | resourceName }}
       </h1>
-       <p ng-bind-html="controller.description | markdown"></p>
+
+      <p ng-bind-html="controller.description | markdown"></p>
+
+      <p class="traits" ng-if="controller.traits.length > 0">
+        This resource is&nbsp;
+        <readable-list repeat="trait in controller.traits"><a ui-sref="root.trait({version: apiVersion, trait: trait})">{{trait}}</a></readable-list>.
+      </p>
     </div>
   </div>
   <div class="row" ng-if="controller.actions.length">
@@ -25,13 +31,10 @@
         <tbody>
           <tr ng-repeat="action in controller.actions">
             <td>
-              <a ui-sref="root.controller.action({action: action.name, controller: controllerName, version: apiVersion})">{{ action.name }}</a>
+              <a ui-sref="root.action({action: action.name, controller: controllerName, version: apiVersion})">{{ action.name }}</a>
             </td>
             <td>
-              <div ng-repeat="url in action.urls">
-                <div class="label label-default verb" ng-class="url.verb | lowercase">{{ url.verb }}</div>
-                <strong>{{ url.path }}</strong>
-              </div>
+              <url action="action"></url>
             </td>
             <td style="font-size: 110%;">
               <p ng-bind-html="action.description | markdown"></p>
@@ -49,8 +52,4 @@
     <h2>Schema</h2>
     <p ><b>Internet Media-type: {{ controller.media_type.identifier }}</b></p>
   </div>
-  <h1>Actions</h1>
-  <div ng-controller="ActionCtrl" ng-repeat="action in controller.actions">
-    <div id="action-{{action.name}}" ng-include="'views/action.html'"></div>
-  </div>
 </div>

data/lib/api_browser/app/views/directives/menu_item.html

@@ -0,0 +1,8 @@
+<div class="menu-item" ng-if="shouldShow">
+  <a href="{{link.stateRef}}"
+     ng-class="{active: isActive, 'child-resource': link.parent, 'action': link.isAction, 'main': !link.isAction}">
+    {{ link.name }}
+  </a>
+  <menu-item ng-repeat="action in link.actions" link="action"></menu-item>
+  <menu-item ng-repeat="resource in link.childResources" link="resource"></menu-item>
+</div>

data/lib/api_browser/app/views/directives/url.html

@@ -0,0 +1,3 @@
+<p ng-repeat="url in action.urls">
+  <span class="label label-default verb" ng-class="url.verb | lowercase">{{ url.verb }}</span>&nbsp;<b>{{ showExample ?  url.example : url.path }}</b>
+</p>

data/lib/api_browser/app/views/layout.html

@@ -2,7 +2,7 @@
 
 <div class="container" ng-cloak>
   <div class="row">
-    <div class="col-sm-3" ng-controller="MenuCtrl" ng-include="'views/menu.html'"></div>
-    <div class="col-sm-9" ui-view=""></div>
+    <div class="col-sm-4 col-md-3" ng-controller="MenuCtrl" ng-include="'views/menu.html'"></div>
+    <div class="col-sm-8 col-md-9" ui-view="" autoscroll="true"></div>
   </div>
 </div>

data/lib/api_browser/app/views/menu.html

@@ -6,7 +6,7 @@
           <button type="button" class="btn btn-success" dropdown-toggle ng-disabled="disabled">
             {{:: versionLabel}}: {{selectedVersion}} <span class="caret"></span>
           </button>
-          <ul class="dropdown-menu col-sm-12" role="menu">
+          <ul class="dropdown-menu" role="menu">
             <li ng-repeat="version in versions">
               <a ng-click="select(version)" dropdown-toggle>{{version}}</a>
             </li>
@@ -23,23 +23,17 @@
       <tabset justified="true" class="tab-list-group">
         <tab heading="Resources" active="active.resources">
           <div class="list-group">
-            <a ng-repeat="link in availableResources()"
-               href="{{link.stateRef}}"
-               class="list-group-item"
-               ng-hide="expandChildren && link.parent && selectedGrandfatherType != link.grandfather"
-               ng-class="{active: link.typeName == currentType, 'child-resource': link.parent, 'group-selected': selectedGrandfatherType ==  link.grandfather}">
-              {{ link.name }}
-            </a>
+            <menu-item ng-repeat="link in availableResources() | orderBy: 'name'" link="link" toplevel="true"></menu-item>
           </div>
         </tab>
         <tab heading="Schemas" active="active.schemas">
           <div class="list-group">
-            <a ng-repeat="link in availableOthers()"
-               href="{{link.stateRef}}"
-               class="list-group-item"
-               ng-class="{active: link.typeName == currentType}">
-              {{ link.name }}
-            </a>
+            <menu-item ng-repeat="link in availableSchemas() | orderBy: 'name'" link="link" toplevel="true"></menu-item>
+          </div>
+        </tab>
+        <tab heading="Traits" active="active.traits" ng-if="availableTraits().length > 0">
+          <div class="list-group">
+            <menu-item ng-repeat="link in availableTraits() | orderBy: 'name'" link="link" toplevel="true"></menu-item>
           </div>
         </tab>
       </tabset>

data/lib/api_browser/app/views/navbar.html

@@ -2,7 +2,7 @@
   <div class="navbar navbar-default navbar-fixed-top" role="navigation">
     <div class="container">
       <div class="navbar-header">
-        <a class="navbar-brand" href="#">{{:: title}}</a>
+        <a class="navbar-brand" href="#/">{{:: title}}</a>
       </div>
     </div>
   </div>

data/lib/api_browser/app/views/trait.html

@@ -0,0 +1,13 @@
+<div ng-if="error" class="alert alert-danger">
+  <p>The requested trait could not be found.</p>
+</div>
+<div ng-if="trait">
+  <div class="row">
+    <div class="col-lg-12">
+      <h1>
+        {{ traitName | resourceName }}
+      </h1>
+    </div>
+  </div>
+  <div ng-if="trait.description" ng-bind-html="trait.description | markdown"></div>
+</div>