@bennerinformatics/ember-fw-table 2.0.21 → 2.1.0

package/addon/components/fw-table-resort.js

@@ -4,26 +4,35 @@ import {alias, filter, filterBy, sort} from '@ember/object/computed';
 import layout from '../templates/components/fw-table-resort';
 
 /**
- * This table contains logic to resort a "table" of models
+ * This table contains client-side logic to resort a "table" of models. This resort table will not call the actual serverside "save" function, so you will need to persist the changes to the database yourself,
+ * but it will do everything else for you (ie all you should have to do is call save, and the reorder will work). A basic usage example is the following:
+ *
  * ```handlebars
  * <FwTableResort @items={{items}} @titleKey='name' @sortKey='sorted' />
  * ```
  *
  * If used in a block format instead, it is possible to fully define the title area, such as to replace it with input fields, which also adds a cheveron to expand if desired
  * ```handlebars
- *  <FwTableResort @sortKey='sorted' as |item expanded|>
+ *  <FwTableResort @items={{items}} @sortKey='sorted' as |item expanded|>
  *      {{input item.name}}
  *  </FwTableResort>
  *  ```
- *
- * @class FW-Table-Resort
+ * Currently the only way to have a display title different from the default sort is to use the block format manually (set the `titleKey` to the desired default sort, and then manually display
+ * the other desired property).
+ * @class FwTableResort
  * @public
+ * @module Components
  */
 const TableResort = Component.extend({
     layout,
     tagName: 'section',
     classNames: ['panel-body', 'fw-table-resort'],
-
+    /**
+     * Required property. This is what you pass the array of items you wish to sort with the table.
+     * @public
+     * @property items
+     * @type {Boolean}
+     */
     /**
     * If true, show an expand button for more fields
     *
@@ -37,14 +46,16 @@ const TableResort = Component.extend({
      * Filter called to check if an item is active
      *
      * @public
+     * @property activeFilter
      * @type {Function}
      */
     activeFilter: null,
 
     /**
-     * Filter called to check if an item is active
+     * Key used to determine if an item is active
      *
      * @public
+     * @property activeKey
      * @type {String}
      */
     activeKey: null,
@@ -99,13 +110,13 @@ const TableResort = Component.extend({
      * Tolerance before dragging starts
      *
      * @public
-     * @property spacing
+     * @property distance
      * @type {Number}
      */
     distance: 0,
 
     /**
-     * A list of all items which will be shown in the table
+     * An internal list of all items which will be shown in the table (takes into account activeKey and activeFilter)
      *
      * @private
      * @property viewableItems
@@ -133,18 +144,18 @@ const TableResort = Component.extend({
         this._super(...arguments);
 
         // determine the default sort order from the sortkey
-        this.set('_sortOrder', [this.get('sortKey')]);
+        this.set('_sortOrder', [this.sortKey]);
         // if we have a fallback for default is null, add that as well
-        if (this.get('titleKey')) {
-            this.get('_sortOrder').pushObject(this.get('titleKey'));
+        if (this.titleKey) {
+            this._sortOrder.pushObject(this.titleKey);
         }
 
         // determine how we will filter the viewable items based on what the user gave
         // if its a key, either filter type
-        let activeKey = this.get('activeKey');
+        let activeKey = this.activeKey;
         if (activeKey) {
             // have a function? use that
-            let activeFilter = this.get('activeFilter');
+            let activeFilter = this.activeFilter;
             if (activeFilter) {
                 defineProperty(this, 'viewableItems', filter(`items.@each.${activeKey}`, activeFilter));
             } else {
@@ -159,15 +170,17 @@ const TableResort = Component.extend({
 
     /**
      * Helper function to sort a list of passed items
+     * @method reorderItems
      * @param  {DS.Model[]} items  Model array
+     * @private
      */
     reorderItems(items) {
-        let activeFilter = this.get('activeFilter');
+        let activeFilter = this.activeFilter;
         if (activeFilter) {
             items = items.filter(activeFilter);
         }
         items.forEach((item, index) => {
-            item.set(this.get('sortKey'), index + 1);
+            item.set(this.sortKey, index + 1);
         });
     },
 
@@ -194,7 +207,7 @@ const TableResort = Component.extend({
          */
         deleteItem(item) {
             this.delete(item);
-            this.reorderItems(this.get('sortedItems'));
+            this.reorderItems(this.sortedItems);
         }
     }
 });

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

@@ -12,12 +12,12 @@ import RSVP from 'rsvp';
  * This table contains logic to show a table as a panel in an app. This table features sorting rows can be expanded
  * to show hidden data
  *  ```handlebars
- * <FwTableSortable @data={{data}} @columns={{columns}} @title='Table' />
+ * <FwTableSortable @data={{model}} @columns={{columns}} @title='Table' />
  * ```
  *
  * If used in a block format instead, it is possible to fully define the title area, replacing the title parameter. The export action is passed as a yield parameter to redefine the export button
  *  ```handlebars
- *  <FwTableSortable @data={{data}} @columns={{columns}} as |export|>
+ *  <FwTableSortable @data={{model}} @columns={{columns}} as |export|>
  *      <strong class='panel-title'>Table</strong>
  *  </FwTableSortable>
  *  ```
@@ -29,7 +29,8 @@ import RSVP from 'rsvp';
  * Alternatively, setting this to `true` or `false` will force the state regardless of a property.
  * By default will show if the property from `valuePath` is not null
  *
- * @class FW-Table-Sortable
+ * @class FwTableSortable
+ * @module Components
  * @extends EmberLightTable
  * @public
  */
@@ -110,6 +111,7 @@ const TableSortable = Component.extend({
      * @public
      * @property headerEmpty
      * @type {Boolean}
+     * @default true
      */
     headerEmpty: true,
     /**
@@ -126,6 +128,7 @@ const TableSortable = Component.extend({
      * @public
      * @property responsive
      * @type {Boolean}
+     * @default false
      */
     responsive: false,
 
@@ -145,10 +148,13 @@ const TableSortable = Component.extend({
      * * `canExport`: if true (default), the column will be included in the export. Set to false to skip exporting the column.
      * * `exportOnly`: if true, the column will not show in the table, but will still be exported.
      *
-     * Additionally, the value `export` is set to true in `format`'s context
+     * Additionally, the value `export` is set to true in `format`'s context.
+     *
+     * If this is set to a string, the string is used as the name of the export button.
      * @public
      * @property canExport
-     * @type {Boolean}
+     * @type {Boolean | String}
+     * @default false
      */
     canExport: false,
 
@@ -158,6 +164,7 @@ const TableSortable = Component.extend({
      * @public
      * @property showHeader
      * @type {Boolean}
+     * @default true
      */
     showHeader: true,
 
@@ -167,6 +174,7 @@ const TableSortable = Component.extend({
      * @public
      * @property showFooter
      * @type {Boolean}
+     * @default true
      */
     showFooter: false,
 
@@ -187,7 +195,7 @@ const TableSortable = Component.extend({
      * @type {Array}
      */
     _defaultSort: computed('defaultSort', function() {
-        let defaultSort = this.get('defaultSort');
+        let defaultSort = this.defaultSort;
         if (isNone(defaultSort)) {
             return [];
         }
@@ -214,11 +222,11 @@ const TableSortable = Component.extend({
      * @type {Array}
      */
     sortOrder: computed('_defaultSort.[]', 'sortColumn', function() {
-        let sortColumn = this.get('sortColumn');
+        let sortColumn = this.sortColumn;
         if (sortColumn) {
-            return [sortColumn].pushObjects(this.get('_defaultSort'));
+            return [sortColumn].pushObjects(this._defaultSort);
         }
-        return this.get('_defaultSort');
+        return this._defaultSort;
     }),
 
     /**
@@ -247,7 +255,7 @@ const TableSortable = Component.extend({
      * @type {String}
      */
     exportTitle: computed('canExport', function() {
-        let canExport = this.get('canExport');
+        let canExport = this.canExport;
         if (canExport === true) {
             return 'Export';
         }
@@ -255,26 +263,34 @@ const TableSortable = Component.extend({
     }),
 
     /**
-     * Called to delete the full page of entries
+     * Called to delete the full page of entries. Pass in the action to be called by the button.
+     *
+     * @property deleteTable
+     * @type {Action}
+     * @default undefined
      */
     deleteTable: undefined,
 
     /**
-     * Determines title for delete function
+     * Determines title for delete function. This will only be used if deleteTable action is passed in.
+     *
+     * @property deleteOverrideTitle
+     * @type {String}
      */
     deleteOverrideTitle: null,
 
     deleteTitle: computed('deleteTable', 'deleteOverrideTitle', function() {
-        if (!this.get('deleteTable')) {
+        if (!this.deleteTable) {
             return null;
         } else {
-            return this.get('deleteOverrideTitle') ? this.get('deleteOverrideTitle') : 'Delete All';
+            return this.deleteOverrideTitle ? this.deleteOverrideTitle : 'Delete All';
         }
     }),
 
     /**
      * Determines if the current user has permission to delete the table (usually has-role helper will be used to determine this)
-     * example: deleteTablePermission=(has-role 'admin')
+     * example: `@deleteTablePermission={{has-role 'admin'}}`. This will only be used if `deleteTable` action is passed in.
+     * @property deleteTablePermissions
      * @type {Boolean}
      * @default true
      */
@@ -288,8 +304,8 @@ const TableSortable = Component.extend({
      */
     // eslint-disable-next-line ember/no-observers
     updateTableRows: observer('sortedData', function() {
-        if (this.get('table')) {
-            this.get('table').setRows(this.get('sortedData'));
+        if (this.table) {
+            this.table.setRows(this.sortedData);
         }
     }),
 
@@ -301,8 +317,8 @@ const TableSortable = Component.extend({
      */
     // eslint-disable-next-line ember/no-observers
     updateTableColumns: observer('columns', function() {
-        if (this.get('table')) {
-            this.get('table').setColumns(this.get('columns'));
+        if (this.table) {
+            this.table.setColumns(this.columns);
         }
     }),
 
@@ -315,8 +331,8 @@ const TableSortable = Component.extend({
     didReceiveAttrs() {
         this._super(...arguments);
         // first, determine our sorting
-        let defaultSort = this.get('_defaultSort');
-        let columns = this.get('columns') || [];
+        let defaultSort = this._defaultSort;
+        let columns = this.columns || [];
         if (!isEmpty(defaultSort)) {
             // make a map of key to ascending
             let [mainKey] = defaultSort;
@@ -330,9 +346,9 @@ const TableSortable = Component.extend({
                 return key === mainKey ? Object.assign({}, column, {sorted: true, ascending}) : column;
             });
         }
-        this.set('table', newTable(columns, this.get('sortedData')));
+        this.set('table', newTable(columns, this.sortedData));
 
-        if (this.get('noPanel')) {
+        if (this.noPanel) {
             this.set('classNames', null);
         }
     },
@@ -386,7 +402,7 @@ const TableSortable = Component.extend({
          * Called by the export button to export the current table data to CSV
          */
         export() {
-            exportTable(this.get('table'), this.get('title'));
+            exportTable(this.table, this.title);
         }
     }
 });

package/addon/documentation.js

@@ -4,64 +4,22 @@
  *  and which is easier to use than its parent. Within it as well, we have added a few extra
  *  things that make more complicated aspects of tables also easier to incorporate (such as
  *  paginated tables). For more information on ember-light-table,
- *  [see their documentation](https://adopted-ember-addons.github.io/ember-light-table/docs).
- *
- * Because of the design of this addon, it is much simpler than some of Informatics other
- * addons. All of the "internal" elements of this addon, which are used within the addon, but
- * are not designed to be used outside, are in an "Internal" submodule.
- * * [Components](Components.html)
- *      - [Main Components](Main.html)
- *      - [Internal Components](Internal.html)
- *      - [Cell Components](Cell.html)
- * * [Utils](Utils.html)
+ *  [see their documentation](https://adopted-ember-addons.github.io/ember-light-table/docs). For a more
+ *  comprehensive guide to Ember FW Table, see our [Ember FW Table](https://linformatics.bitbucket.io/docs/addons/client/ember-fw-table).
+ *  This is just designed to be API docs to briefly describe various elements and how to use them.
  *
  * @module Introduction
  * @main Introduction
  */
  /**
-  * Ember-FW-Table defines many different components that can be used throughout the Informatics apps. To understand what a component is,
-  * [click here](https://guides.emberjs.com/v2.18.0/components/) for Ember's own documentation on components. The main focus of this app
-  * is of course the main table Here contains a list
-  * of all of the different components that are defined by ember-fw. Ember-fw also adds the ability for more advanced components
-  * (which are components that require more than just a simple call to use), such as [Notifications](../classes/NotificationsService.html)
-  *  and [Modals](Modals.html).
+  * Components defined by Ember FW Table.
   *
   * @module Components
   * @main Components
   */
-/**
- * Since the main component that is imported with this addon is to do with the table,
- * there are many components that can be explained in detail, but are really only internal to
- * the addon itself, and probably shouldn't be used without a serious reason. Those listed below
- * are technically able to be used by any app which import the addon, but will probably only be
- * helpful documentation for the developer who develops the ember-fw-table addon.
- *
- * @module Components
- * @submodule Internal
- * @main Internal
- */
 
 /**
- * There are a few other components which are added in this addon, which are built to be used within
- * the app. Of course the largest of these is the fw-table-sortable, after which the addon derives
- * its name, but there are also other supplemental components designed for use with the app.
- *
- * ***
- *
- * ###Classes
- * * [FW-Table-Sortable](../classes/FW-Table-Sortable.html)
- * * [FW-Table-Resort](../classes/FW-Table-Resort.html)
- * * [FW-Pagination-Wrapper](../classes/FW-Pagination-Wrapper.html)
- * * [FW-Delete-Modal](../classes/FW-Delete-Modal.html)
- *
- * @module Components
- * @submodule Main
- * @main Main
- */
-
-/**
- * Some components in this addon were designed to be used with the `cellComponent` value used in the table.
- * For information on how `cellComponent` works, [click here](https://adopted-ember-addons.github.io/ember-light-table/docs/classes/Column.html#property_cellComponent).
+ * Cell Components in Ember FW Table.
  *
  * For each of these cell components, you call them in the following way:
  * ```js
@@ -73,25 +31,32 @@
  * ]
  * ```
  *
- * ***
  *
- * ### Classes
- * * [FW-Cell-Action](../classes/FW-Cell-Action.html)
- * * [FW-Cell-Boolean](../classes/FW-Cell-Boolean.html)
- * * [FW-Cell-Nullable](../classes/FW-Cell-Nullable.html)
- * * [FW-Cell-Permission-Icon](../classes/FW-Cell-Permission-Icon.html)
- * * [FW-Row-Toggle](../classes/FW-Row-Toggle.html)
- * * [FW-Row-Toggle-Index](../classes/FW-Row-Toggle-Index.html)
+ * @module CellComponents
+ * @main CellComponents
+ */
+
+/**
+ * Column Components in Ember FW Table.
+ *
+ * For each of these column components, call them in the following way:
+ *
+ * ```js
+ * columns: [
+ *     {
+ *         label: 'Column',
+ *         component: 'fw-column-title'
+ *     }
+ * ]
+ *
+ * ```
  *
- * @module Components
- * @submodule Cell
- * @main Cell
+ * @module ColumnComponents
+ * @main ColumnComponents
  */
 
 /**
- * Utils is short for Utilities, and they are essentially whatever you need them to be. It is simply a way to import a function that does a certain task.
- * In ember-fw-table, we have a few utils files that have been defined, and each has a couple different functions that are semi-related to each other. So each "class"
- * within the utils module actually is simply a group of related functions exported that can be used after they are imported.
+ * Utils defined in Ember FW Table.
  *
  * @module Utils
  * @main Utils

package/addon/templates/components/fw-delete-modal.hbs

@@ -1,4 +1,4 @@
-<FwFullscreenModal @modal="confirm-choice" @size="md" @model={{hash
+<FwFullscreenModal @modal="confirm-choice" @size="sm" @model={{hash
         confirmButtonText="Delete"
         confirmButtonStyle="danger"
         confirmButtonIcon="fa-regular fa-trash-can"

package/addon/utils/base-cells.js

@@ -1,11 +1,30 @@
 /**
- * DESCRIPTION NEEDED
+ * This util is designed to create the most basic defined cells for you. While it does not cover all the cellComponents, the most commonly used (`FwRowToggle`, `FwRowToggleIndex`, and `FwCellAction`) can be imported
+ * rather than creating the cell object yourself. You would import them in the following way:
+ * ```js
+ *  import {functionName} from '@bennerinformatics/ember-fw-table/base-cells';
+ * ```
+ * After it is imported, the functions below tell you how to implement each one.
  * @class BaseCells
  * @module Utils
  */
 /**
- * Creates a generic row toggle object
- * @param  {Object} extra Additional values to add to the row toggle. Breakpoints is the most common one
+ * Creates a generic row toggle object. If you pass in a `valuePath` to extra, it will format using the `FwRowToggleIndex` component (which displays a value on hover) rather than just the regular
+ * `FwRowToggle`. This should be the first cell defined in the columns arraw. An example use case would be the following (after importing `rowToggle` as defined above):
+ * ```js
+ * //generic rowToggle, no differences
+ * columns: [
+ *   rowToggle(),
+ *   ...
+ * ],
+ * //rowToggle when you need to pass in something to extra, such as valuePath or breakpoints
+ * columns: [
+ *   rowToggle({breakpoints: ['mobile']}),
+ *   ...
+ * ]
+ * ```
+ * @method rowToggle
+ * @param  {Object} extra Additional values to add to the row toggle. Breakpoints is the most common one, but will accept any normal column inputs
  * @return {Object}       Object to use as a row toggle column
  */
 export function rowToggle(extra = {}) {
@@ -22,8 +41,24 @@ export function rowToggle(extra = {}) {
 }
 
 /**
- * Creates a generic action cell
- * @param  {Object} extra Additional values to add to the action buttons. Small is useful to shrink it with breakpoints
+ * Creates a generic action cell, with a delete and edit button. Passing `small` into extra, will display as only icon buttons, whereas the full text will be displayed if it is not set.
+ * This should always be the last cell in your columns array. An example use case would be the following (after importing as above):
+ * ```js
+ * //will render action cell with icon buttons only
+ * columns: [
+ *   ...
+ *   actions({small: true})
+ * ],
+ * //will render action cell with full text of "Edit" and "Delete"
+ * columns: [
+ *   ...
+ *   actions()
+ * ]
+ * ```
+ *
+ * **Note**: You will still need to pass in your edit and delete actions to the `tableActions` in the `FwTableSortable` component in order for this to work properly. This only renders the cell.
+ * @method actions
+ * @param  {Object} extra Additional values to add to the action buttons. Small is useful to shrink it with breakpoints.
  * @return {Object}       Object to use as an actions button column
  */
 export function actions(extra = {}) {

package/addon/utils/export.js

@@ -2,12 +2,13 @@ import EmberObject from '@ember/object';
 import {isEmpty, isNone} from '@ember/utils';
 import Papa from 'papaparse';
 /**
- * Used internally only. DESCRIPTION NEEDED
+ * An internal util that is used in ember-fw-table for the export functionality, both in the `FwTableSortable` and `FwPaginationWrapper`.
  * @class Export
  * @module Utils
  */
 /**
  * Creates a CSV file from a data array and a title
+ * @method createCSV
  * @param  {Array} data        Array of table cells
  * @param  {Title} [name=null] Name to export
  */
@@ -29,6 +30,7 @@ export function createCSV(data, name = null) {
 
 /**
  * Exports an Ember Light Table to CSV
+ * @method exportTable
  * @param  {Table} table             Table class, just needs to include rows and columns
  * @param  {String} [title='Export'] Title to use for exporting
  */

package/addon/utils/formats.js

@@ -2,12 +2,25 @@
 import {htmlSafe} from '@ember/string';
 import {isNone} from '@ember/utils';
 /**
- * DESCRIPTION NEEDED
+ * These utils are designed for helping you be able to easily format a column by passing this function into the `format` attribute of the column. To use these functions, all you need to do
+ * is import them at the top of the Javascript file, with the following import:
+ * ```js
+ * import {functionName} from '@bennerinformatics/ember-fw-table/utils/formats';
+ * ```
+ * Then you use it in the column array to format it appropriately. Each function gives you an example of how to use it.
  * @class Format
  * @module Utils
  */
 /**
- * Format function which replaces the value with a basic Yes/No format for if its true or false
+ * Format function which replaces the value with a basic Yes/No format for if its true or false. Designed to be used in the following way with a boolean column (after importing `formatBoolean` in the way described above):
+ * ```js
+ * column: [{
+ *   label: 'My Boolean',
+ *   valuePath: 'myBoolean',
+ *   format: formatBoolean
+ *   ...
+ * }...],
+ * @method formatBoolean
  * @param  {Any} value Value to test
  * @return {String}    "Yes" if the value is truthy, "No" otherwise
  */
@@ -16,22 +29,56 @@ export function formatBoolean(value) {
 }
 
 /**
- * Generates a format function which returns the value or an italic default text
+ * Generates a format function which returns the value or an italic default text if the value is null. Designed to be used in the following way with a column that may have a null value (after importing `formatNullable` in the way described above):
+ * ```js
+ * column: [
+ *  //if null, will display the default "None" in italics
+ *   {
+ *      label: 'Some Column',
+ *      valuePath: 'someColumn',
+ *      format: formatNullable
+ *      ...
+ *   },
+ *   //if null, will display "No Value" instead of "None" in italics
+ *   {
+ *      label: 'Some Column',
+ *      valueText: 'someColumn',
+ *      format: formatNullable('No Value')
+ *  }
+ * ...],
+ * @method formatNullable
  * @param  {String} [nullText='None'] Text if the value is null
  * @return {Function}                 Function to pass into the column format
  */
 export function formatNullable(nullText = 'None') {
     return function(value) {
         if (isNone(value)) {
-            return this.get('export') ? '' : htmlSafe(`<i>${nullText}</i>`);
+            return this['export'] ? '' : htmlSafe(`<i>${nullText}</i>`);
         }
         return value;
     };
 }
 
 /**
- * Generates a function which formats a moment based on the specified format
- * @param  {String} format       moment format
+ * Generates a function which formats a moment based on the specified format. Designed to be used in the following way with a column displaying a date (after importing `formatMoment` in the way described above):
+ * ```js
+ * column: [
+ *   //will display date as 1970-01-01
+ *   {
+ *      label: 'Some Column',
+ *      valuePath: 'someColumn',
+ *      format: formatMoment('YYYY-MM-DD')
+ *      ...
+ *   },
+ *   //will display date in the table as 1970-01-01, but when exporting display 01-01-1970
+ *   {
+ *      label: 'Some Column',
+ *      valueText: 'someColumn',
+ *      format: formatMoment('YYYY-MM-DD', 'MM-DD-YYYY')
+ *  }
+ * ...],
+ * @method formatMoment
+ * @param  {String} format       moment format. For a list of valid strings, see [Moment docs](https://momentjs.com/docs/#/displaying/format/)
  * @param  {String} exportFormat moment format used on exporting
  * @return {Function}      Function to pass into a column which formats by a moment
  */
@@ -39,7 +86,7 @@ export function formatMoment(format, exportFormat = null) {
     return function(date) {
         if (moment.isMoment(date)) {
             // if we are exporting and have an export format, use that
-            let useFormat = exportFormat && this.get('export') ? exportFormat : format;
+            let useFormat = exportFormat && this['export'] ? exportFormat : format;
             return date.format(useFormat);
         }
     };

package/addon/utils/table.js

@@ -1,11 +1,12 @@
 import {isEmpty} from '@ember/utils';
 /**
- * Used internal only DESCRIPTION NEEDED
+ * This is an internal util that is used to help with the logic for expanded rows.
  * @class TableUtil
  * @module Utils
  */
 /**
  * Checks if a row should be show in expanded view given the context
+ * @method showExpanded
  * @param  {Table}  table  Table class instance
  * @param  {Row}    row    Row class instance
  * @param  {Column} column Column class instance

package/index.js

@@ -5,5 +5,6 @@ module.exports = {
     name: '@bennerinformatics/ember-fw-table',
     included() {
         this._super.included.apply(this, arguments);
-    }
+    },
+    isDevelopingAddon: () => true
 };