docs-body-parameters-table.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="../iron-flex-layout/iron-flex-layout.html">
<link rel="import" href="../paper-icon-button/paper-icon-button.html">
<link rel="import" href="../arc-icons/arc-icons.html">
<link rel="import" href="../iron-media-query/iron-media-query.html">
<link rel="import" href="../arc-polyfills/arc-polyfills.html">
<link rel="import" href="../marked-element/marked-element.html">
<link rel="import" href="../raml-behaviors/raml-behavior.html">
<link rel="import" href="../iron-collapse/iron-collapse.html">
<link rel="import" href="docs-parameters-behavior.html">
<link rel="import" href="docs-parameters-table-shared-styles.html">
<link rel="import" href="docs-json-parameters-table.html">
<link rel="import" href="docs-xml-parameters-table.html">
<link rel="import" href="docs-form-parameters-table.html">
<link rel="import" href="docs-body-media-type-selector.html">
<link rel="import" href="raml-type-property-description.html">
<!--
`<docs-parameters-table>` A parameters list and description table for the RAML documentation view

This element renders a table of body type paramteres with the doccumentation.

For headers documentation table pleae, use `<docs-headers-table>` element.
For uri parameters documentation table pleae, use `<docs-parameters-table>`
element.

### Example
```
<docs-body-parameters-table
  type="[[bodType]]"></docs-body-parameters-table>
```

Currently following properties are supported:

- name (required) - name of the property, in case of UIR parameter it should be the parameter itself
- type - the type of the parameter, any RAML allowed value will be accepted
- description - description of the parameter
- required - mark that the property is a required property
- pattern - validation pattern to be applied to the parameter value
- example - example value of the parameter
- min - minimum value of the parametre when the type is numeric
- max - maximum value of the parametre when the type is numeric

### Styling
`<docs-body-parameters-table>` provides the following custom properties and mixins for styling:

Custom property | Description | Default
----------------|-------------|----------
`--docs-parameters-table` | Mixin applied to all parameter table elements | `{}`
`--docs-parameters-url-table` | Mixin applied to this elements | `{}`
`--params-table-header-background-color` | Background color of table header | `#00A1DF`
`--params-table-header-color` | Font color of table header | `rgba(255, 255, 255, 0.87)`
`--params-table-subheader-background-color` | Background color of table subheader | `rgba(0, 161, 223, 0.24)`
`--params-table-subheader-color` | Font color of table subheader | `rgba(0, 0, 0, 0.87)`
`--params-table-row-border-color` | Border color of table's each row | `#00A1DF`
`--params-table-row-background-color` | Background color of table's each row |  `#fff`
`--params-table-row-color` | Font color of table's each row |  `#fff`
`--docs-parameters-table-cell` | Mixin applied to each cell | `{}`
`--docs-parameters-table-meta` | Mixin applied to property's metadata (example, pattern, etc) | `{}`
`--docs-body-parameters-table-json` | Mixin applied to the JSON output | `{}`
`--docs-body-parameters-table-type-name` | Mixin applied to the name of the type | `{}`
`--toggle-button` | Mixin applied to toggle button | `{}`
`--toggle-button-hover` | Mixin applied to the :hover state of toggle button | `{}`

@group RAML Elements
@element docs-parameters-table
@demo demo/docs-body-parameters-table.html
-->
<dom-module id="docs-body-parameters-table">
  <template strip-whitespace>
    <style include="docs-parameters-table-shared-styles"></style>
    <style>
    :host {
      display: block;
      overflow: auto;
      width: 100%;
      @apply --docs-body-parameters-table;
    }

    h4 {
      @apply --docs-body-parameters-table-type-name;
    }

    h4 .label {
      margin-right: 8px;
    }

    paper-listbox paper-item {
      cursor: pointer;
    }

    .type-title {
      @apply --layout-horizontal;
      @apply --layout-center;
    }

    .type-title h4 {
      @apply --layout-flex;
    }

    .toggle-button {
      color: var(--docs-body-parameters-table-toggle-icon-color, rgba(0, 0, 0, 0.54));
      transform: rotateZ(0deg);
      transition: color 0.25s linear, transform 0.3s linear;
      @apply --toggle-button;
    }

    .toggle-button.opened {
      transform: rotateZ(-180deg);
    }

    .toggle-button:hover {
      color: var(--docs-body-parameters-toggle-icon-hover-color, rgba(0, 0, 0, 0.78));
      @apply --toggle-button-hover;
    }

    *[hidden] {
      display: none !important;
    }

    .type-desc {
      margin-bottom: 28px;
      color: rgba(0, 0, 0, 0.74);
      @apply --arc-font-body1;
      @apply --raml-docs-item-description;
    }
    </style>
    <docs-body-media-type-selector hidden$="[[!renderMediaTypeSelector]]" selected-type="{{selectedType}}" body="[[body]]" media-type="{{selectedMediaType}}"></docs-body-media-type-selector>
    <div class="type-title">
      <h4>
        <span class="label">Type</span>
        <span class="value">[[typeName(selectedType)]]</span>
      </h4>
      <span hidden$="[[hideStructureToggle]]">
        <paper-icon-button class$="toggle-button[[_computeToggleClass(structureDisplayOpened)]]" icon="arc:expand-more" on-tap="toggleOpened" title="Toggle structure display"></paper-icon-button>
      </span>
    </div>

    <template is="dom-if" if="[[!isPrimitive]]" restamp>
      <template is="dom-if" if="[[hasValue(selectedType.description)]]" restamp>
        <div class="type-desc">
          <marked-element markdown="[[selectedType.description]]">
            <div class="markdown-html markdown-body"></div>
          </marked-element>
        </div>
      </template>
    </template>
    <template is="dom-if" if="[[isObject]]" restamp>
      <docs-json-parameters-table type="[[typeProperties(selectedType)]]" structure-display-opened="[[structureDisplayOpened]]" narrow="[[narrow]]"></docs-json-parameters-table>
    </template>
    <template is="dom-if" if="[[isJson]]" restamp>
      <iron-collapse opened="[[structureDisplayOpened]]">
        <docs-json-structure-view type="[[selectedType]]" has-type="[[_computeHasDataType(selectedType)]]" narrow="[[narrow]]"></docs-json-structure-view>
      </iron-collapse>
    </template>
    <template is="dom-if" if="[[isXml]]" restamp>
      <docs-xml-parameters-table type="[[selectedType]]" structure-display-opened="[[structureDisplayOpened]]" narrow="[[narrow]]"></docs-xml-parameters-table>
    </template>
    <template is="dom-if" if="[[isPrimitive]]" restamp>
      <iron-collapse opened="[[structureDisplayOpened]]">
        <raml-type-property-description item="[[selectedType]]" display-type narrow="[[narrow]]"></raml-type-property-description>
      </iron-collapse>
    </template>
    <template is="dom-if" if="[[isEmpty]]">
      <p class="no-info">Schema is not defined for this type</p>
    </template>
    <iron-media-query query="max-width: 640px" query-matches="{{narrow}}"></iron-media-query>
  </template>
  <script>
  Polymer({
    is: 'docs-body-parameters-table',

    behaviors: [
      RamlBehaviors.DocsParametersBehavior,
      Polymer.RamlBehavior
    ],
    /**
     * Fired when selected body content type have changed.
     * It is not fired if value is not set or if change was caused by
     * computation of available content types automatically set fist available
     * content type.
     *
     * @event raml-docs-content-type-changed
     * @param {String} value Selected body content type.
     */
    properties: {
      /**
       * An array of the `body` part of the method part of the RAML definition.
       * It is expecting to be an output of the RAML to JS and ransformed with
       * the `raml2obj` library. This is available in `<raml-js-parser>`
       * element.
       */
      body: Array,
      /**
       * Computed value, true if body is set and has any item.
       */
      hasBody: {
        value: false,
        type: Boolean,
        computed: '_computeHasBody(body)',
        notify: true
      },
      /**
       * Computed value depended on number of media types declared in `body`.
       * It is set to true if `body` contains more than one media type.
       *
       * Note, media type selector is always in the DOM and computes
       * `selectedType` property.
       */
      renderMediaTypeSelector: {
        type: Boolean,
        computed: '_computeRenderMediaSelector(body)'
      },
      /**
       * Computed selected type value to display.
       * This value is set by the media types selector.
       */
      selectedType: Object,
      /**
       * Computed selected value of media type.
       * This value is set by the media types selector.
       */
      selectedMediaType: String,
      // Computed value, true if current type is a RAML type definition
      isObject: {
        type: Boolean,
        value: false,
        readOnly: true
      },
      // Computed value, true if current type is a JSON schema
      isJson: {
        type: Boolean,
        value: false,
        readOnly: true
      },
      // Computed value, true if current type is an XML type object
      isXml: {
        type: Boolean,
        value: false,
        readOnly: true
      },
      // Computed value, true if current type is a primitive
      isPrimitive: {
        type: Boolean,
        value: false,
        readOnly: true
      },
      isEmpty: {
        type: Boolean,
        readOnly: true
      },
      /**
       * True when the schema / examples section is displayed.
       * Set this value to change the state.
       */
      structureDisplayOpened: {
        type: Boolean,
        value: true
      },
      // If set then the narrow layout is applied.
      narrow: Boolean,
      /**
       * Computed value, if set it will hide structure display toggle button.
       */
      hideStructureToggle: Boolean
    },

    observers: [
      '_computeType(selectedType)',
      '_autoHide(autoHide, hasBody)'
    ],
    /**
     * Computes the `renderMediaTypeSelector` property value.
     */
    _computeRenderMediaSelector: function(body) {
      return !!(body && body.length > 1);
    },
    /**
     * Computes if current boddy array has any value that can be presented.
     *
     * @param {?Array} body Body declaration for the response / method.
     * @return {Boolean} True if body is set and has any item.
     */
    _computeHasBody: function(body) {
      return !!(body && body.length);
    },
    /**
     * Resets states of computed variables.
     */
    reset: function() {
      this._setIsObject(false);
      this._setIsJson(false);
      this._setIsXml(false);
      this._setIsPrimitive(false);
      this._setIsEmpty(false);
    },
    /**
     * Hides the element by setting `[hidden]` attribute if body is not set
     * and `[auto-hide]` attribute is set.
     *
     * @param {Boolean} autoHide Value of `autoHide` property
     * @param {Boolean} hasBody Value of the `hasBody` property.
     */
    _autoHide: function(autoHide, hasBody) {
      if (!autoHide) {
        return;
      }
      var state = !hasBody;
      this.toggleAttribute('hidden', state);
    },
    /**
     * Computes current selection content type.
     */
    _computeType: function(type) {
      this.reset();
      if (!type) {
        return;
      }
      switch (type.type) {
        case 'object':
        case 'array':
        case 'union':
          this._setIsObject(true);
          break;
        case 'xml':
          this._setIsXml(true);
          break;
        case 'json':
          this._setIsJson(true);
          break;
        default:
          // In RAML 0.8 for schema types there will be no type property.
          // Need to figure it out from the `name` property which is body's
          // content type.
          if (!type.type && type.schema) {
            if (type.key.indexOf('json') !== -1) {
              this._setIsJson(true);
            } else if (type.key.indexOf('xml') !== -1) {
              this._setIsXml(true);
            } else {
              this._setIsPrimitive(true);
            }
          } else if (type.type && typeof type.type === 'string' &&  type.type[0] === '<') {
            // TODO: This is an issue, probably with enhancer. At some point
            // type becomes type content and contains schema.
            this._setIsXml(true);
          } else if (!type.type && type.example) {
            if (type.key.indexOf('json') !== -1) {
              this._setIsJson(true);
            } else if (type.key.indexOf('xml') !== -1) {
              this._setIsXml(true);
            } else {
              this._setIsPrimitive(true);
            }
          } else if (type.type) {
            this._setIsPrimitive(true);
          } else {
            this._setIsEmpty(true);
          }
      }

      this.async(function() {
        this._computeHideStructureToggle();
      }, 1);
    },

    // Toggles type
    toggleOpened: function() {
      this.structureDisplayOpened = !this.structureDisplayOpened;
    },

    // Computes toggle button class name
    _computeToggleClass: function(toggleOpened) {
      var clazz = '';
      if (toggleOpened) {
        clazz += ' opened';
      }
      return clazz;
    },

    _computeHideStructureToggle: function() {
      var value = false;
      if (this.isObject) {
        value = !this.$$('docs-json-parameters-table').hasType;
      } else if (this.isXml) {
        value = !this.$$('docs-xml-parameters-table').hasType;
      } else if (this.isEmpty) {
        value = true;
      }
      this.hideStructureToggle = value;
    },

    _computeHasDataType: function(type) {
      if (!type) {
        return false;
      }
      if (!type.type) {
        return false;
      }
      if (typeof type.type === 'string') {
        return false;
      }
      return true;
    }
  });
  </script>
</dom-module>