rest-api-property.html

<!--
@license
Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../marked-element/marked-element.html">
<link rel="import" href="rest-api-property-styles.html">

<!--
Renders documentation describing a REST API param, header or body key-value pair.
Give it a `descriptor`-Object attribute, and watch it go!

Example:

    <rest-api-property descriptor="[[descriptor]]"></rest-api-property>

@group REST Elements
@element rest-api-property
@hero hero.svg
-->

<dom-module id="rest-api-property">
  <template>
    <style include="rest-api-property-styles"></style>

    <div id="transitionMask">
      <div id="signature">
        <a id$="[[anchorId]]" href$="#[[anchorId]]" class="name deeplink">{{descriptor.key}}</a><span class="params">(<span>{{_paramText}}</span>)</span>
      </div>
      <div id="details">
        <div id="meta" hidden$="{{_computeHideMeta(descriptor)}}">
          <span id="type" class="type">{{descriptor.type}}</span>
          <span class="annotation">[[_getAnnotation(descriptor)]]</span>
        </div>
        <marked-element id="desc" markdown="{{descriptor.explanation}}" hidden$="{{!descriptor.explanation}}">
          <div class="markdown-html"></div>
        </marked-element>
      </div>
    </div>
  </template>

  <script>
    (function() {
      Polymer({
        is: 'rest-api-property',
        properties: {
          /**
           * REST API param, header or body key-value pair object.
           * @type {{key: string, type: string, optional: boolean, values: Array(string), explanation: string}}
           */
          descriptor: {
            type:     Object,
            observer: '_descriptorChanged',
          },
          _paramText: String,
        },
        listeners: {
          'transitionEnd':       '_onTransitionEnd',
          'webkitTransitionEnd': '_onTransitionEnd',
        },
        ready: function() {
          this._isReady = true;
        },
        /**
         * Resets any state that was set up for transitions.
         *
         * We are careful to reset our explicit heights after a transition
         * completes, so that the property doesn't clip values if the user resizes
         * their viewport.
         */
        _onTransitionEnd: function(event) {
          if (event.path[0] !== this.$.transitionMask) return;
          this.$.transitionMask.style.height = '';
        },
        _descriptorChanged: function() {
          this.toggleAttribute('private',       this.descriptor.private);
          this.toggleAttribute('configuration', this.descriptor.configuration);
          this.toggleAttribute('function',      this.descriptor.function);
          this._paramText = (this.descriptor.params || []).map(function(param) {
            return param.name;
          }).join(', ');
        },
        // hidden if no type and no defaults
        _computeHideMeta: function(descriptor) {
          return descriptor.type === undefined &&  descriptor.values === undefined;
        },
        _getAnnotation: function(descriptor) {
          var annotations = [];
          if (descriptor.optional) {
            annotations.push('optional');
          }
          if (descriptor['values'] !== undefined) {
            annotations.push('Values: ' + descriptor['values']);
          }
          return annotations.join(' – ');
        }
      });
    })();
  </script>
</dom-module>