vaadin-grid-doc.html

<link rel='import' href='vaadin-grid.html'>

<script>
  Polymer.Vaadin = Polymer.Vaadin || {};

  /**
   * Object referencing a cell in the grid body and its data.
   *
   * A `cell` object is passed as a parameter for both column renderers and for
   * the cell class generator.
   *
   * @polymerBehavior cell
   */
  Polymer.Vaadin.Cell = {
    properties: {

      /**
       * Column name of the cell, if specified.
       */
      columnName: String,

      /**
       * The `td` element of the cell.
       */
      element: HTMLElement,

      /**
       * Owner row of the cell. See the API documentation for `row` for more
       * details.
       *
       * @property {row} row
       */
      row: Object,

      /**
       * Contents of the cell, as it is retrieved from the `items` array/function.
       */
      data: Object,

      /**
       * Column index of the cell.
       */
      index: Number
    }
  };

  /**
   * Object for controlling and accessing a column in a `vaadin-grid`.
   *
   * #### Example:
   * ```js
   * var grid = document.querySelector('vaadin-grid');
   *
   * // First get a reference to one column object, which has
   * // all the properties described in this documentation
   * var column = grid.columns[0];
   *
   * // Then get or set any properties of the column, such as 'width'
   * column.width = "200px";
   * ```
   *
   * @polymerBehavior column
   */
  Polymer.Vaadin.Column = {
    properties: {

      /**
       * Flex ratio of the column, used to distribute any available horizontal
       * space among all flexed columns.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].flex = 2;
       * ```
       * #### Declarative example:
       * ```html
       * <!-- If you omit the value of the attribute,
       *      it is considered as "1" -->
       * <col>
       * <col flex>
       * <col flex="2">
       * ```
       *
       * @default -1
       */
      flex: Number,

      /**
       * Set whether it is possible for the user to hide this column or not.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].hidable = true;
       * ```
       * #### Declarative example:
       * ```html
       * <col hidable>
       * ```
       *
       * @default false
       */
      hidable: false,

      /**
       * Hides or shows the column. By default columns are visible before
       * explicitly hiding them. A column can be programmatically hidden even if
       * the `hidable` property would be `false`.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].hidden = true;
       * ```
       * #### Declarative example:
       * ```html
       * <col hidden>
       * ```
       *
       * @default false
       */
      hidden: false,

      /**
       * Sets the hiding toggle's caption for this column. Shown in the grid’s
       * column hiding dropdown menu if the column is hidable. Useful if the
       * header content is something else than text (i.e. a DOM element) or
       * empty.
       *
       * If not specified, the default column header content/text is used.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].hidingToggleText = "Profile picture";
       * ```
       * #### Declarative example:
       * ```html
       * <col hiding-toggle-text="Profile picture">
       * ```
       *
       * @default undefined
       */
      hidingToggleText: String,

      /**
       * Maximum width of the column in pixels.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].maxWidth = 400;
       * ```
       * #### Declarative example:
       * ```html
       * <col max-width="400">
       * ```
       *
       * @default undefined
       */
      maxWidth: Number,

      /**
       * Minimum width of the column in pixels.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].minWidth = 100;
       * ```
       * #### Declarative example:
       * ```html
       * <col min-width="100">
       * ```
       *
       * @default 10
       */
      minWidth: Number,

      /**
       * Name of the column, used in mapping the column to a property in the row
       * item/object provided by the `items` property.
       *
       * Must be a valid JavaScript object reference
       * (e.g. "user.name.first", "url")
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].name = "user.name.first";
       * ```
       * #### Declarative example:
       * ```html
       * <col name="user.name.first">
       *```
       *
       * @default undefined
       */
      name: String,

      /**
       * Custom render function for the column’s data items. Default is
       * undefined.
       *
       * Currently it is not possible to set the renderer declaratively.
       *
       * #### JavaScript example:
       * ```js
       * // Prefix the cell content with a dollar sign
       *  grid.columns[0].renderer = function(cell) {
       *      cell.element.innerHTML = '$' + cell.data;
       *  };
       *  ```
       * @property {function} renderer
       * @param {cell} cell - Reference to the cell being rendered. See the
       * documentation for `cell` for more details.
       * @type {function}
       */
      renderer: function(cell) {},

      /**
       * Enables sorting the column data by the end user.
       *
       * To programmatically or declaratively sort the columns, use the
       * `grid.sortOrder`property, or the `sort-direction` attribute. Columns
       * can be sorted even if this property is `false`, it only controls the
       * end user sorting.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].sortable = true;
       * grid.sortOrder = [{column: 0, direction: "asc"}];
       * ```
       * #### Declarative example:
       * ```html
       * <col sortable sort-direction="asc">
       *```
       *
       * @default false
       */
      sortable: false,

      /**
       * Width of the column in pixels.
       *
       * #### JavaScript example:
       * ```js
       * grid.columns[0].width = 200;
       * ```
       * #### Declarative example:
       * ```html
       * <col width="200">
       * ```
       *
       * @default undefined
       */
      width: Number
    }
  };

  /**
   * Object for accessing and controlling footer rows.
   *
   * #### Example:
   * ```js
   * grid.footer.addRow();
   * var footerCell = grid.footer.getCell(0,0);
   * ```
   *
   * @polymerBehavior footer
   */
  Polymer.Vaadin.Footer = {
    properties: {

      /**
       * Hides all footer rows in the grid if set to `true`.
       *
       * #### JavaScript example:
       * ```js
       * grid.footer.hidden = true;
       * ```
       * #### Declarative example:
       * ```html
       * <tfoot hidden>
       * ```
       *
       * @default false
       */
      hidden: Boolean,

      /**
       * Number of rows in the footer.
       *
       * @default 0
       */
      rowCount: {
        type: Number,
        readOnly: true
      }
    },

    /**
     * Adds a new footer row.
     *
     * @param {number} index - Index of the new footer row. The footer rows in
     * subsequent indexes are shifted by one index. If undefined, the new row is
     * inserted as last
     */
    addRow: function(index) {},

    /**
     * Removes a specific footer row.
     *
     * @param {number} index - Index of the row to be removed.
     */
    removeRow: function(index) {},

    /**
     * Returns an object reference to a particular footer cell.
     *
     * @param {number} rowIndex - Index of the row.
     * @param {number|string} column - Index or name of the column.
     * @return {header-and-footer-cell} An object reference to a particular footer cell.
     */
    getCell: function(rowIndex, column) {},

    /**
     * Sets the CSS class name for a footer row.
     *
     * @param {number} rowIndex - Index of the row.
     * @param {string} className - New class name.
     */
    setRowClassName: function(rowIndex, className) {}
  };

  /**
   * Object for accessing and controlling header rows.
   *
   * #### Example:
   * ```js
   * grid.header.addRow();
   * var headerCell = grid.header.getCell(1,0);
   * ```
   *
   * @polymerBehavior header
   */
  Polymer.Vaadin.Header = {
    properties: {

      /**
       * Hides all header rows in the grid if set to `true`.
       *
       * #### JavaScript example:
       * ```js
       * grid.header.hidden = true;
       * ```
       * #### Declarative example:
       * ```html
       * <thead hidden>
       * ```
       *
       * @default false
       */
      hidden: Boolean,

      /**
       * Index of the default header row if multiple header rows exist.
       *
       * @default 0
       */
      defaultRow: Number,

      /**
       * Number of rows in the header.
       *
       * @default 1
       */
      rowCount: {
        type: Number,
        readOnly: true
      }
    },

    /**
     * Adds a new header row.
     *
     * @param {number} index - Index of the new header row. The header rows in
     * subsequent indexes are shifted by one index. If undefined, the new row is
     * inserted as last.
     */
    addRow: function(index) {},

    /**
     * Removes a specific header row.
     *
     * @param {number} index - Index of the row to be removed.
     */
    removeRow: function(index) {},

    /**
     * Returns an object reference to a particular header cell.
     *
     * @param {number} rowIndex - Index of the row.
     * @param {number|string} column - Index or name of the column.
     * @return {header-and-footer-cell} An object reference to a particular header cell.
     */
    getCell: function(rowIndex, column) {},

    /**
     * Sets the CSS class name for a header row.
     *
     * @param {number} rowIndex - Index of the row.
     * @param {string} className - New class name.
     */
    setRowClassName: function(rowIndex, className) {}
  };

  /**
   * Represents a grid header/footer cell configuration.
   *
   * #### Example:
   * ```js
   * var headerCell = grid.header.getCell(1,0);
   * headerCell.content = document.createElement("input");
   * headerCell.className = "filter";
   * ```
   *
   * @polymerBehavior header-and-footer-cell
   */
  Polymer.Vaadin.HeaderAndFooterCell = {
    properties: {

      /**
       * Class name of the cell.
       */
      className: String,

      /**
       * Contents of the cell. Can be either a string of HTML or a reference to
       * a HTML element
       */
      content: Object,

      /**
       * Number of columns which the cell should span/group.
       *
       * @default 0
       */
      colspan: Number
    }
  };

  /**
   * The grid passes a `params` object as the first parameter to the `items`
   * function. It contains information about the exact items/rows the grid wants
   * to display in its viewport as well as the sort order of the grid (see the
   * documentation for `SortOrder`).
   *
   * The second parameter for the `items` function is a callback function for
   * providing the grid with the requested items. The callback function takes an
   * array containing the items and optinally the total number of items in the
   * data source (see grid's `size` property) as its parameters.
   *
   * #### Example:
   *```js
   * grid.items = function(params, callback) {
   *   var start = params.index;
   *   var end = params.index + params.count;
   *   callback([start...end], totalItems);
   * }
   * ```
   *
   * @polymerBehavior items-function
   */
  Polymer.Vaadin.ItemsFunction = {
    properties: {

      /**
       * Index of the first data item to fetch.
       */
      index: Number,

      /**
       * Number of data items to fetch.
       */
      count: Number,

      /**
       * Sorting order for the fetched data items.
       *
       * See the API documentation for the `sortOrder` property and the
       * “SortOrder” object for more details.
       *
       * @property {Array<SortOrder>} sortOrder
       * @type {Array<SortOrder>}
       * */
      sortOrder: Object
    }
  };

  /**
   * Object referencing to a row and it's data.
   *
   * A `row` object is passed as a parameter to the row class generator
   * function.
   *
   * A `row` object is also referenced from a `cell` object, passed as a
   * parameter to column renderer functions and the cell class generator
   * function.
   *
   * @polymerBehavior row
   */
  Polymer.Vaadin.Row = {
    properties: {

      /**
       * Index of the row.
       */
      index: Number,
      /**
       * Data object of the row, as it is retrieved from the `items` array or
       * function.
       */
      data: Object,

      /**
       * Reference to the grid element/object.
       *
       * @property {HTMLElement} grid
       * @type {HTMLElement}
       */
      grid: Object,

      /**
       * Reference to the `tr` element of the row.
       *
       * @property {HTMLElement} element
       * @type {HTMLElement}
       */
      element: Object
    }
  };

  /**
   * Object for accessing and controlling selected rows of the grid.
   *
   * #### Example:
   * ```js
   * grid.selection.mode = "multi";
   * grid.selection.selectAll();
   * grid.selection.selected(); // [0, 1, 2, 3, ...]
   * grid.selection.selected(function(index) {
   *   // Iterate over the selected indexes without populating an array
   * });
   * ```
   *
   * @polymerBehavior selection
   */
  Polymer.Vaadin.Selection = {
    properties: {

      /**
       * The selection mode dictates how many rows can be selected.
       *
       * #### Possible values:
       * - **disabled**: No rows can be selected.
       * - **single**: A single row can be selected at any given time.
       * - **multi**: Multiple rows can be selected.
       * - **all**: For the end user this is the same as "multi", except that
       * the “select all” checkbox in the grid header is checked. This mode is
       * useful in determining whether to get the `selected` or `deselected`
       * rows array.
       *
       * Setting the selection mode has the side-effect of clearing any previous
       * selection.
       *
       * #### JavaScript example:
       * ```js
       * grid.selection.mode = "multi";
       * ```
       * #### Declarative example:
       * ```html
       * <vaadin-grid selection-mode="multi">
       * ```
       * @default "single"
       */
      mode: String,

      /**
       * Size of the selection (i.e. how many rows are selected).
       */
      size: Number
    },

    /**
     * Select a row.
     * @param {number} index – Index of the row to select.
     */
    select: function(index) {},

    /**
     * Deselect a row.
     * @param {number} index – Index of the row to deselect.
     */
    deselect: function(index) {},

    /**
     * Clear the selection.
     *
     * If the selection mode is "all", calling `clear()` sets the selection mode
     * to "multi" as a side-effect.
     */
    clear: function() {},

    /**
     * Select all rows. Does nothing if the selection mode is not "multi" or
     * "all".
     *
     * If the selection mode is "multi", calling `selectAll()` sets the
     * selection mode to "all" as a side-effect.
     */
    selectAll: function() {},

    /**
     * Selected row indexes.
     *
     * @param {function} iterator (optional) - A function to iterate over the selected indexes. If the function returns values, it is used to map the indexes to a new array.
     * @param {number} startIndex (optional) - Provide a starting index if you wish to process the selection array in batches.
     * @param {number} endIndex (optional) - Used together with startIndex to process the selection in batches.
     * @return {Array<number>} Indexes of the selected rows.
     */
    selected: function(iterator, startIndex, endIndex) {},

    /**
     * Deselected row indexes. Only returns indexes when selection mode is
     * "all", otherwise returns an empty array.
     *
     * @param {function} iterator (optional) - A function to iterate over the deselected indexes. If the function returns values, it is used to map the indexes to a new array.
     * @param {number} startIndex (optional) - Provide a starting index if you wish to process the deselection array in batches.
     * @param {number} endIndex (optional) - Used together with startIndex to process the deselection in batches.
     * @return {Array<number>} Indexes of the deselected rows.
     */
    deselected: function() {}
  };

  /**
   * Object for defining the sorting order of the columns. Used inside the
   * `sortOrder` array property.
   *
   * #### Example:
   * ```js
   * grid.sortOrder = [
   *  {
   *     column: 1,
   *     direction: "asc"
   *   },
   *   {
   *     column: 0,
   *     direction: "desc"
   *   }
   * ];
   * ```
   *
   * @polymerBehavior sort-order
   */
  Polymer.Vaadin.SortOrder = {
    properties: {

      /**
       * Index of the column.
       */
      column: Number,

      /**
       * Sort direction for the given column.
       *
       * #### Possible values:
       * - **asc** - Sort the given column in ascending order (smaller first).
       * - **desc** - Sort the given column in descending order (bigger first).
       *
       * Can be set declaratively:
       * ```html
       * <col sort-direction="asc">`
       * ```
       * The sort order is defined by the column order in this case.
       *
       * @default "asc"
       */
      direction: String
    }
  };
</script>