docs-parameters-behavior.html

<!--
@license
Copyright 2016 The Advanced REST client authors
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.
-->
<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../arc-polyfills/arc-polyfills.html">
<script>
(function() {
  window.RamlBehaviors = window.RamlBehaviors || {};
  /**
   * Use `RamlBehaviors.DocsParametersBehavior` to implement a custom element
   * that is rendering a parameters table in the RAML documentation view.
   * @polymerBehavior RamlBehaviors.DocsParametersBehavior
   */
  window.RamlBehaviors.DocsParametersBehavior = {
    properties: {
      // If set automatically hides the element which doesn't have parameteres set
      autoHide: {
        type: Boolean,
        value: false
      },
      // RAML base types
      baseTypes: {
        type: Array,
        value: function() {
          return ['object', 'array','integer', 'string','number','boolean',
            'datetime','file', 'null','any'];
        }
      },
      /**
       * A list of examples in the definition.
       * This is a computed value for both `example` and `examples` properties.
       *
       * This is not computed automatically. Set the type object change observer. See the
       * `_computeExamples()` function for more information.
       *
       * If you see this documentation it means that the element that implements this behavior is
       * not using examples and it's not relevant for this element.
       */
      examples: Array,
      // Computed value if current type has examples.
      hasExamples: {
        type: Boolean,
        value: false,
        notify: true,
        computed: '_computeHasExamples(examples.*)'
      },
      // If true then the narrow layout is applied.
      narrow: {
        type: Boolean,
        reflectToAttribute: true
      }
    },
    /**
     * Check if passed object is set.
     * 0 (zero) returns true while empty string returns false.
     *
     * @return {Boolean} True/False depending if passed object has a value.
     */
    hasValue: function(obj) {
      var type = typeof obj;
      if (type === 'number' && obj === 0) {
        return true;
      }
      if (type === 'boolean') {
        return true;
      }
      if (type === 'string' && obj === '') {
        return true;
      }
      return !!obj;
    },
    /**
     * Gets a value of an object.
     * It returns the same object except if the value is empty string. Then it
     * return `(empty string)` label.
     *
     * @param {any} obj Object to evaludate
     * @return {any} the same object
     */
    getValue: function(obj) {
      var type = typeof obj;
      if (type === 'string' && obj === '') {
        return '(empty string)';
      }
      return obj;
    },
    /**
     * in RAML `properties` property of the type object is an object.
     * To make it useful while itereing using `dom-repeat` this function
     * produces an array of objects. Object content is the same as
     * RAML parser's. Object's key is the same as the `name` property in the
     * object.
     *
     * ## Example
     * Source object:
     * ```javascript
     *  properties: {
     *    available: {
     *      description: 'description',
     *      displayName: 'available',
     *      name: 'available',
     *      required: true
     *    }
     *  }
     * ```
     * becomes:
     * ```javascript
     *  properties: [
     *    {
     *      description: 'description',
     *      displayName: 'available',
     *      name: 'available',
     *      required: true
     *    }
     *  ]
     * ```
     * @param {Object} obj The original RAML parser properties value.
     * @return {Array}
     */
    readProperties: function(obj) {
      if (!obj) {
        return [];
      }
      if (obj instanceof Array) {
        return obj;
      }
      var names = Object.keys(obj);
      if (!names) {
        return [];
      }
      names.sort();
      return names.map(function(i) {
        var _obj = obj[i];
        _obj.key = i;
        return _obj;
      });
    },

    _computeEnumValue: function(enumValue) {
      if (!enumValue || !enumValue.length) {
        return '';
      }
      if (typeof enumValue === 'string') {
        return enumValue;
      }
      enumValue = enumValue.map(function(item) {
        if (typeof item === 'string') {
          if (item === '') {
            return '""';
          }
          return item;
        }
        return item.displayName || item.name || item.key;
      });
      return enumValue.join(', ');
    },

    /**
     * Computes list of examples.
     * This function to be used with object sub-properties observer:
     * ```
     * examples: {
     *   type: Array,
     *   computed: '_computeExamples(type.*)'
     * }
     * ```
     * or in the observers list.
     */
    _computeExamples: function(record) {
      var object = record.base;
      if (!object) {
        return undefined;
      }
      if (object.examples && object.examples.length) {
        return object.examples;
      }
      if (object.example) {
        if (typeof object.example === 'string') {
          return [object.example];
        } else {
          return [JSON.stringify(object.example, null, 2)];
        }
      }
      return undefined;
    },
    // Computes boolean value when the `examples` property change.
    _computeHasExamples: function(record) {
      var object = record.base;
      if (!object) {
        return false;
      }
      return !!object.length;
    },
    // Checks if the item has a maximum or max property.
    _hasMaximum: function(item) {
      return !!(item && (item.max || item.maximum || item.max === 0 ||
        item.maximum === 0));
    },
    // returns item's maximum or max property.
    _getMaximum: function(item) {
      if (!item) {
        return;
      }
      if (!!item.max || item.max === 0) {
        return item.max;
      }
      if (!!item.maximum || item.maximum === 0) {
        return item.maximum;
      }
    },
    // Checks if the item has a maximum or max property.
    _hasMinimum: function(item) {
      return !!(item && (item.min || item.minimum || item.min === 0 ||
        item.minimum === 0));
    },
    // returns item's maximum or max property.
    _getMinimum: function(item) {
      if (!item) {
        return;
      }
      if (!!item.min || item.min === 0) {
        return item.min;
      }
      if (!!item.minimum || item.minimum === 0) {
        return item.minimum;
      }
      return item && (item.min || item.minimum);
    },
    // Checks if the item has a maximum or max property.
    _hasExamples: function(item) {
      return !!(item && item.examples && item.examples.length);
    },
    // returns item's maximum or max property.
    _getExamples: function(item) {
      if (!this._hasExamples(item)) {
        return;
      }
      return item.examples.map(function(item) {
        if (typeof item === 'string') {
          return item;
        }
        return item.value;
      }).join('\n');
    },
    // Returns true if `displayName` is set and it's different that `name`
    _hasDisplayName: function(item) {
      return !!(item && item.displayName && item.displayName !== item.name);
    },

    /**
     * Used by schema display elements.
     * Returns a value for 'hidden' attribute to hide the schema title label
     * when schema is RAML 0.8 definition.
     *
     * @param {Object} type RAML type definition.
     * @return {Boolean} True when not schema with label to display.
     */
    _computeSchemaTypeHidden: function(type) {
      if (!type || !type.schema) {
        return true;
      }
      if (type.schema && type.schema === type.schemaContent) {
        return true;
      }
      return false;
    },
    /**
     * Computes schema's label to display in schema viewer.
     * @param {Object} type RAML type definition.
     * @return {String|undefined} Label to display in schema viewer or undefined.
     */
    _computeSchemaLabel: function(type) {
      if (!type || !type.schema) {
        return;
      }
      if (type.schema && type.schema === type.schemaContent) {
        return;
      }
      return type.schema;
    }
  };
})();

</script>