@bennerinformatics/ember-fw-table 2.0.20 → 2.1.0

package/README.md

@@ -1,5 +1,11 @@
 # ember-fw-table
 
+We have a couple of documentation websites, which may help in using this package:
+
+[Ember FW Table Docs](https://linformatics.bitbucket.io/docs/addons/client/ember-fw-table) give a more robust guide to some of the important features of the package.
+
+[Ember FW Table API Docs](https://linformatics.bitbucket.io/docs/addons/client-api/ember-fw-table) are api documentation for each of our components, which are generated from code comments. 
+
 This README outlines the details of collaborating on this Ember addon.
 
 ## Installation

package/addon/classes/Row.js

@@ -1,74 +1,80 @@
-import {computed, defineProperty, observer} from '@ember/object';
-import {alias} from '@ember/object/computed';
-import LightRow from 'ember-light-table/classes/Row';
-import {showExpanded} from '../utils/table';
-
-/**
- * Function to create the canExpand computed property
- * @param  {array} keys Array of keys to watch
- * @return {computed}   Computed property
- */
-function canExpand(keys) {
-    return computed('table.{alwaysExpand,hasExpandedColumns}', ...keys, function() {
-        // start with some short exits
-        // no expanded columns is false
-        if (!this.get('table.hasExpandedColumns')) {
-            return false;
-        }
-        // if it has an expanded column that always shows, automatically true
-        if (this.get('table.alwaysExpand')) {
-            return true;
-        }
-
-        // try and find any column that has something
-        return this.get('table.expandedColumns').any((column) => {
-            return showExpanded(this.get('table'), this, column);
-        });
-    });
-}
-
-/**
- * Personal copy of Ember Light Table row to support the can expand property
- * @type {EmberObject}
- * @extends EmberLightTable/Row
- * @class Row
- */
-export default class Row extends LightRow.extend({
-    /**
-     * Parent table instance
-     * @property table
-     * @type {Table}
-     */
-
-    /**
-     * Checks if the row is currently allowed to expand
-     * @type {boolean}
-     */
-    canExpand: alias('table.hasExpandedColumns'),
-
-    /** Disables expanded state if canExpand is false */
-    expanded: computed('canExpand', '_expanded', {
-        get() {
-            return this.get('canExpand') && this.get('_expanded');
-        },
-        set(_, value) {
-            value &= this.get('canExpand');
-            this.set('_expanded', value);
-            return value;
-        }
-    }),
-
-    /**
-     * Observer to update canExpand if the expanded keys ever changes
-     */
-    // eslint-disable-next-line ember/no-observers
-    updateColumns: observer('table.expandedKeys', function() {
-        defineProperty(this, 'canExpand', canExpand(this.get('table.expandedKeys')));
-    })
-}) {
-    constructor({content, table}) {
-        super(content);
-        this.set('table', table);
-        defineProperty(this, 'canExpand', canExpand(table.get('expandedKeys')));
-    }
-}
+import {computed, defineProperty, observer} from '@ember/object';
+import {alias} from '@ember/object/computed';
+import LightRow from 'ember-light-table/classes/Row';
+import {showExpanded} from '../utils/table';
+
+/**
+ * Function to create the canExpand computed property
+ * @param  {array} keys Array of keys to watch
+ * @return {computed}   Computed property
+ */
+function canExpand(keys) {
+    return computed('table.{alwaysExpand,hasExpandedColumns,expandedColumns}', ...keys, function() {
+        // start with some short exits
+        // no expanded columns is false
+        if (!this.table.hasExpandedColumns) {
+            return false;
+        }
+        // if it has an expanded column that always shows, automatically true
+        if (this.table.alwaysExpand) {
+            return true;
+        }
+
+        // try and find any column that has something
+        return this.table.expandedColumns.any((column) => {
+            return showExpanded(this.table, this, column);
+        });
+    });
+}
+
+/**
+ * Personal copy of Ember Light Table row to support the can expand property
+ * @type {EmberObject}
+ * @extends EmberLightTable/Row
+ * @class Row
+ */
+export default class Row extends LightRow.extend({
+    /**
+     * Parent table instance
+     * @property table
+     * @type {Table}
+     */
+
+    /**
+     * Checks if the row is currently allowed to expand
+     * @type {boolean}
+     */
+    canExpand: alias('table.hasExpandedColumns'),
+
+    /** Disables expanded state if canExpand is false */
+    expanded: computed('canExpand', '_expanded', {
+        get() {
+            return this.canExpand && this.get('_expanded');
+        },
+        set(_, value) {
+            value &= this.canExpand;
+            this.set('_expanded', value);
+            return value;
+        }
+    }),
+
+    /**
+     * Observer to update canExpand if the expanded keys ever changes
+     */
+    // eslint-disable-next-line ember/no-observers
+    updateColumns: observer('table.expandedKeys', function() {
+        defineProperty(this, 'canExpand', canExpand(this.table.expandedKeys));
+    }),
+
+    init({content, table}) {
+        this._super(...arguments);
+        this.table = table;
+        defineProperty(this, 'canExpand', canExpand(table.get('expandedKeys')));
+    }
+}) {
+    // constructor({content, table}) {
+    //     super(content);
+    //     this.table = table;
+    //     defineProperty(this, 'canExpand', canExpand(table.get('expandedKeys')));
+    // }
+}

package/addon/classes/Table.js

@@ -1,147 +1,152 @@
-import LightTable from 'ember-light-table/classes/Table';
-import Row from './Row';
-import {A as emberArray} from '@ember/array';
-import {computed} from '@ember/object';
-import {filter} from '@ember/object/computed';
-import {isEmpty, isNone} from '@ember/utils';
-
-/**
- * Create a collection of Row objects with the given collection
- * @method createRows
- * @static
- * @param  {Array}  rows     Passed in rows
- * @param  {Table}  table    Table instance
- * @return {Array}           Array of table rows
- */
-function createRows(rows = [], table) {
-    return rows.map((r) => new Row({content: r, table}));
-}
-
-/**
- * Personal copy of the table class with some additional computed properties
- *
- * @class Table
- * @extends EmberLightTable/Table
- */
-/*
- * TODO: needs to implement some additional row methods as right now only setRows is wrapped
- */
-export class Table extends LightTable.extend({
-    /**
-     * Table columns without export only columns
-      * @property tableColumns
-      * @type {Ember.Array}
-     */
-    tableColumns: filter('columns.@each.exportOnly', function(column) {
-        return !column.get('exportOnly');
-    }),
-
-    /**
-     * @property visibleColumnGroups
-     * @type {Ember.Array}
-     */
-    visibleColumnGroups: computed('tableColumns.[]', 'tableColumns.@each.{isHidden,isVisibleGroupColumn}', function() {
-        return this.get('tableColumns').filter((c) => {
-            return c.get('isVisibleGroupColumn') || (!c.get('isGroupColumn') && !c.get('isHidden'));
-        });
-    }).readOnly(),
-
-    /**
-     * @property visibleSubColumns
-     * @type {Ember.Array}
-     */
-    visibleSubColumns: computed('tableColumns.@each.visibleSubColumns', function() {
-        return emberArray([].concat(...this.get('tableColumns').getEach('visibleSubColumns')));
-    }).readOnly(),
-
-    /**
-     * @property allColumns
-     * @type {Ember.Array}
-     */
-    allColumns: computed('tableColumns.@each.subColumns', function() {
-        return this.get('tableColumns').reduce((arr, c) => {
-            arr.pushObjects(c.get('isGroupColumn') ? c.get('subColumns') : [c]);
-            return arr;
-        }, emberArray([]));
-    }).readOnly(),
-
-    /**
-     * List of all columns that can show in expanded view, it will be filtered again later
-     *
-     * @private
-     * @property expandedColumns
-     * @type {Array}
-     */
-    expandedColumns: filter('allColumns.@each.{isHidden,showExpanded,cellComponent}', function(column) {
-        // if the column is not hidden, skip it
-        if (!column.get('isHidden')) {
-            return false;
-        }
-        // if hidden, ask the column if we should show it
-        let showExpanded = column.get('showExpanded');
-        if (!isNone(showExpanded)) {
-            return showExpanded;
-        }
-
-        // by default, show if the value path is empty and its not a row toggle
-        return column.get('cellComponent') !== 'fw-row-toggle';
-    }).readOnly(),
-
-    alwaysExpand: computed('expandedColumns.@each.canExpand', function() {
-        return this.get('expandedColumns').any((column) => column.get('showExpanded') === true);
-    }),
-
-    expandedKeys: computed('expandedColumns.[]', function() {
-        let keys = [];
-        this.get('expandedColumns').forEach((column) => {
-            // check if we have a specific expansion property
-            let showExpanded = column.get('showExpanded');
-            if (typeof showExpanded === 'string') {
-                keys.pushObject(showExpanded);
-            } else {
-                // otherwise, try the value path
-                if (column.get('valuePath')) {
-                    keys.pushObject(column.get('valuePath'));
-                }
-            }
-        });
-
-        return keys;
-    }),
-
-    /**
-     * Returns true if the table currently contains hidden columns
-     *
-     * @private
-     * @property hasHiddenColumns
-     * @type {Boolean}
-     */
-    hasExpandedColumns: computed('expandedColumns', function() {
-        return !isEmpty(this.get('expandedColumns'));
-    }),
-
-    /**
-     * Replace all the row's content with content of the argument. If argument is an empty array rows will be cleared.
-     * @method setRows
-     * @param  {Array} rows
-     * @return {Array} rows
-     */
-    setRows(rows = []) {
-        return this.get('rows').setObjects(createRows(rows, this));
-    }
-}) {
-    constructor({columns, rows}) {
-        super(columns, []);
-        this.setRows(rows);
-    }
-}
-
-/**
- * Creates an instance of the table class, mimicking the new Table constructor of the parent
- * @param  {Array} columns Table columns
- * @param  {Array} rows    Table rows
- * @return {Table}         Table class to use in ember-light-table
- */
-export default function newTable(columns, rows) {
-    return new Table({columns, rows});
-}
+import LightTable from 'ember-light-table/classes/Table';
+import Row from './Row';
+import {A as emberArray} from '@ember/array';
+import {computed} from '@ember/object';
+import {filter} from '@ember/object/computed';
+import {isEmpty, isNone} from '@ember/utils';
+
+/**
+ * Create a collection of Row objects with the given collection
+ * @method createRows
+ * @static
+ * @param  {Array}  rows     Passed in rows
+ * @param  {Table}  table    Table instance
+ * @return {Array}           Array of table rows
+ */
+function createRows(rows = [], table) {
+    return rows.map((r) => Row.create({content: r, table}));
+}
+
+/**
+ * Personal copy of the table class with some additional computed properties
+ *
+ * @class Table
+ * @extends EmberLightTable/Table
+ */
+/*
+ * TODO: needs to implement some additional row methods as right now only setRows is wrapped
+ */
+export class Table extends LightTable.extend({
+    /**
+     * Table columns without export only columns
+      * @property tableColumns
+      * @type {Ember.Array}
+     */
+    tableColumns: filter('columns.@each.exportOnly', function(column) {
+        return !column.get('exportOnly');
+    }),
+
+    /**
+     * @property visibleColumnGroups
+     * @type {Ember.Array}
+     */
+    visibleColumnGroups: computed('tableColumns.[]', 'tableColumns.@each.{isHidden,isVisibleGroupColumn}', function() {
+        return this.tableColumns.filter((c) => {
+            return c.get('isVisibleGroupColumn') || (!c.get('isGroupColumn') && !c.get('isHidden'));
+        });
+    }).readOnly(),
+
+    /**
+     * @property visibleSubColumns
+     * @type {Ember.Array}
+     */
+    visibleSubColumns: computed('tableColumns.@each.visibleSubColumns', function() {
+        return emberArray([].concat(...this.tableColumns.getEach('visibleSubColumns')));
+    }).readOnly(),
+
+    /**
+     * @property allColumns
+     * @type {Ember.Array}
+     */
+    allColumns: computed('tableColumns.@each.subColumns', function() {
+        return this.tableColumns.reduce((arr, c) => {
+            arr.pushObjects(c.get('isGroupColumn') ? c.get('subColumns') : [c]);
+            return arr;
+        }, emberArray([]));
+    }).readOnly(),
+
+    /**
+     * List of all columns that can show in expanded view, it will be filtered again later
+     *
+     * @private
+     * @property expandedColumns
+     * @type {Array}
+     */
+    expandedColumns: filter('allColumns.@each.{isHidden,showExpanded,cellComponent}', function(column) {
+        // if the column is not hidden, skip it
+        if (!column.get('isHidden')) {
+            return false;
+        }
+        // if hidden, ask the column if we should show it
+        let showExpanded = column.get('showExpanded');
+        if (!isNone(showExpanded)) {
+            return showExpanded;
+        }
+
+        // by default, show if the value path is empty and its not a row toggle
+        return column.get('cellComponent') !== 'fw-row-toggle';
+    }).readOnly(),
+
+    alwaysExpand: computed('expandedColumns.@each.canExpand', function() {
+        return this.expandedColumns.any((column) => column.get('showExpanded') === true);
+    }),
+
+    expandedKeys: computed('expandedColumns.[]', function() {
+        let keys = [];
+        this.expandedColumns.forEach((column) => {
+            // check if we have a specific expansion property
+            let showExpanded = column.get('showExpanded');
+            if (typeof showExpanded === 'string') {
+                keys.pushObject(showExpanded);
+            } else {
+                // otherwise, try the value path
+                if (column.get('valuePath')) {
+                    keys.pushObject(column.get('valuePath'));
+                }
+            }
+        });
+
+        return keys;
+    }),
+
+    /**
+     * Returns true if the table currently contains hidden columns
+     *
+     * @private
+     * @property hasHiddenColumns
+     * @type {Boolean}
+     */
+    hasExpandedColumns: computed('expandedColumns', function() {
+        return !isEmpty(this.expandedColumns);
+    }),
+
+    /**
+     * Replace all the row's content with content of the argument. If argument is an empty array rows will be cleared.
+     * @method setRows
+     * @param  {Array} rows
+     * @return {Array} rows
+     */
+    setRows(rows = []) {
+        return this.rows.setObjects(createRows(rows, this));
+    },
+
+    init({columns, rows}) {
+        this._super(...arguments);
+        this.setRows(rows);
+    }
+}) {
+    // constructor({columns, rows}) {
+    //     super(columns, []);
+    //     this.setRows(rows);
+    // }
+}
+
+/**
+ * Creates an instance of the table class, mimicking the new Table constructor of the parent
+ * @param  {Array} columns Table columns
+ * @param  {Array} rows    Table rows
+ * @return {Table}         Table class to use in ember-light-table
+ */
+export default function newTable(columns, rows) {
+    return Table.create({columns, rows});
+}

package/addon/components/fw-cell-action.js

@@ -1,15 +1,19 @@
-import Component from '@ember/component';
-import layout from '../templates/components/fw-cell-action';
-
-/**
- * This cell contains buttons to edit and delete a model, which can have actions passed in
- * The edit action is expected to be passed in as tableActions.edit, while delete as tableActions.delete
- *
- * Setting the variable "small" in the column will cause the buttons to display smaller
- * The easiest way to add this cell is through the base cell in utils, for more information, [click here](../classes/BaseCells.html)
- * @public
- * @class FW-Cell-Action
- */
-export default Component.extend({
-    layout
-});
+import Component from '@ember/component';
+import layout from '../templates/components/fw-cell-action';
+
+/**
+ * This cell contains buttons to edit and delete a model, which can have actions passed in.
+ * The edit action is expected to be passed in as `tableActions.edit`, while delete as `tableActions.delete`.
+ * This component will only give you two actions, so if you need a more complicated component than edit and delete,
+ * you will need to create your own cell component.
+ * Setting the variable `small` in the column will cause the buttons to display smaller.
+ *
+ * The easiest way to add this cell is through the base cell in utils, for more information, [click here](../classes/BaseCells.html). In most cases, it is best
+ * to use the util rather than this cell component directly.
+ * @public
+ * @class FwCellAction
+ * @module CellComponents
+ */
+export default Component.extend({
+    layout
+});

package/addon/components/fw-cell-boolean.js

@@ -1,12 +1,13 @@
-import Component from '@ember/component';
-import layout from '../templates/components/fw-cell-boolean';
-
-/**
- * Displays a cell containing a boolean as either "Yes" or "No"
- * @public
- * @deprecated Use utils/formats.formatBoolean
- * @class FW-Cell-Boolean
- */
-export default Component.extend({
-    layout
-});
+import Component from '@ember/component';
+import layout from '../templates/components/fw-cell-boolean';
+
+/**
+ * Displays a cell containing a boolean as either "Yes" or "No".
+ * @public
+ * @deprecated You should use the [`formatBoolean` in the Format Util](../classes/BaseCells.html) instead.
+ * @class FwCellBoolean
+ * @module CellComponents
+ */
+export default Component.extend({
+    layout
+});

package/addon/components/fw-cell-nullable.js

@@ -1,12 +1,15 @@
-import Component from '@ember/component';
-import layout from '../templates/components/fw-cell-nullable';
-
-/**
- * Creates a table cell that displays a default value if null.
- * That value defaults to "None", but can be changed by setting the nullText property in a column
- * @public
- * @class FW-Cell-Nullable
- */
-export default Component.extend({
-    layout
-});
+import Component from '@ember/component';
+import layout from '../templates/components/fw-cell-nullable';
+
+/**
+ * Creates a table cell that displays a default value if null.
+ * That value defaults to "None", but can be changed by setting the `nullText` property in a column.
+ * @deprecated You should use the [`formatNullable` in the Format Util](../classes/BaseCells.html) instead.
+ * @public
+ * @class FwCellNullable
+ * @module CellComponents
+ *
+ */
+export default Component.extend({
+    layout
+});

package/addon/components/fw-cell-permission-icon.js

@@ -1,12 +1,28 @@
-import Component from '@ember/component';
-import layout from '../templates/components/fw-cell-permission-icon';
-
-/**
- * Displays a cell containing a boolean as either "Yes" or "No"
- * @public
- * @deprecated Use utils/formats.formatBoolean
- * @class FW-Cell-Permission-Icon
- */
-export default Component.extend({
-    layout
-});
+import Component from '@ember/component';
+import layout from '../templates/components/fw-cell-permission-icon';
+
+/**
+ * This component displays the permission icon for the table on the Permissions page. It should be used in the following way:
+ * ```js
+ * columns: [{
+ *   label: 'Admin',
+ *   valuePath: 'admin',
+ *   cellComponent: 'fw-cell-permission-icon',
+ *   align: 'center',
+ *   width: '80px'
+ * }]
+ * ```
+ * This component will take the value, and display the proper Fontawesome icon based on its value. The value should be one of the following three numbers:
+ *
+ * - 0 means that that role does not have access to that feature, and it will display a red X.
+ * - 1 means that that feature is controlled by access control, not by Group Control, and it will display a lock icon in the primary color of the app
+ * - 2 means that that role has access to that feature, and will display a green check mark.
+ * - If the value is anything else, the cell will just be empty
+ *
+ * @public
+ * @class FwCellPermissionIcon
+ * @module CellComponents
+ */
+export default Component.extend({
+    layout
+});

package/addon/components/fw-column-sortable.js

@@ -3,11 +3,19 @@ import {computed} from '@ember/object';
 import layout from '../templates/components/fw-column-sortable';
 
 /**
- * Displays a column title which can show a sorting icon
+ * Displays a column title which can show a sorting icon if a network request is still active. This can be used for your columns when using the [FwPaginationWrapper](../classes/FwPaginationWrapper.html),
+ * so that sorting works properly. It should be set as the columns component (not the cellComponent), like so:
+ * ```js
+ *  columns: [{
+ *   label: 'Name',
+ *   valuePath: 'name',
+ *   component: 'fw-column-sortable'
+ *  }...]
+ * ```
+ * If you do this, when you are sorting the table within the paginated wrapper, it will display a spinning icon letting the user know that the sort is loading.
  * @public
- * @class FW-Column-Sortable
- * @module Components
- * @submodule Internal
+ * @class FwColumnSortable
+ * @module ColumnComponents
  */
 export default Component.extend({
     layout,

package/addon/components/fw-column-title.js

@@ -1,13 +1,21 @@
-import Sortable from './fw-column-sortable';
-import layout from '../templates/components/fw-column-title';
-
-/**
- * Displays a column title which will truncate with an ellipsis if too long
- * @public
- * @class FW-Column-Title
- * @module Components
- * @submodule Internal
- */
-export default Sortable.extend({
-    layout
-});
+import Sortable from './fw-column-sortable';
+import layout from '../templates/components/fw-column-title';
+
+/**
+ * This column component extends [`fw-column-sortable` component](../classes/FwColumnSortable.html), so it will display a sort-icon, but it also display a column title
+ * which will truncate with an ellipsis if too long. This can be used for your columns when using the [FwPaginationWrapper](../classes/FwPaginationWrapper.html),
+ * so that sorting works properly. It should be set as the columns component (not the cellComponent), like so:
+ * ```js
+ *  columns: [{
+ *   label: 'Name',
+ *   valuePath: 'name',
+ *   component: 'fw-column-title'
+ *  }...]
+ * ```
+ * @public
+ * @class FwColumnTitle
+ * @module ColumnComponents
+ */
+export default Sortable.extend({
+    layout
+});