@bennerinformatics/ember-fw-table 2.0.21 → 2.1.0

package/addon/components/fw-pagination-wrapper.js

@@ -9,124 +9,30 @@ import Table from 'ember-light-table';
 import RSVP from 'rsvp';
 import layout from '../templates/components/fw-pagination-wrapper';
 /**
- * In order to use this component, you also need to install the `ember-cli-pagination` addon
- * to your app. And to make sure that the css looks correct for the pages, in your app.scss file
- * import the styling after all related `ember-fw` imports:
- * ```css
- * @import "ember-fw/pagination/pagination-fw";
- * ```
- *
- * This component works very closely with our Informatics Framework system to create a
- * paginated table, but being such, it also expects certain things from the browse request
- * to get it to work. So that being said, this documentation will need to describe how to use
- * both the client side and the serverside of this component. If you do not use our FW system as
- * your server side, you will need to find a way to get it to return count and limited as is detailed here.
- *
- * ###Client Side
- * There are a few things that are needed to be talked about with the client side. There are some parameters
- * that are needed no matter whether you wrap a table or use a default table. But when it comes to the table,
- * you can use block form, where you specify the table (see [fw-table-sortable](FW-Table-Sortable.html)),
- * or you can pass in extra parameters so this function, and it will make a table for you.
- *
- * ####Mandatory Parameters
- * While below deals with all of the different options that you can pass in as properties to this parameter, as
- * well as all internal properties used by the component by way of explanation, referencing those parameters that
- * are necessary for the proper functioning of this component are helpful here. See below for details about each property:
- *
- * * Basic Properties
- *      - `modelName`
- *      - `defaultSortKey`
- *      - `tableWrapperClass`
- *      - `entriesPerPage`
- * * Action Properties (these need to be actions that are passed in)
- *      - `onSearch`
- *      - `makeQuery`
- *      - `getTitle`
- *      - `getExportColumns`
- *
- * ####Setting Up the Table
- * #####Table Column Usage
- * The following parameters from table columns are utilized in searching and sorting.
- * searchKey: Key to send to the server side when sorting by this column. If unset, defaults to valuePath. Most commonly used when valuePath uses a relationship property, as searchKey can then just use the relationship name.
- * component: To show the loading spinner on the header during searching, component must be set to a header component that shows a spinner when column.loading is true. fw-column-title is an option that will handle this for you.
+ * For an in depth guide on how to implement pagination, including on the server, see our [Paginated Table Concept](https://linformatics.bitbucket.io/docs/addons/client/ember-fw-table/concepts/paginated-table).
+ * All of the possible parameters are documented below. At its most basic, however, there are two ways to use `FwPaginationWrapper` in parameter form or in block form. Here is a brief example of each:
  *
- * #####Block invoking
- * This template is typically invoked in block format, wrapping around the history search panel. When called in block form, a single hash parameter called actions is provided. This contains the following properties:
- * actions.search: Action to call to use search parameter and fetch entries.
- * actions.export: Action to call to fetch all entries and export them into a CSV file.
- *
- * These actions should be used within the search panel to create search and export buttons.
- * Table
- * The results table can be provided in two forms: block format and parameter format.
- * Parameter format
- * Calling the table in parameter format will use a default fw-table-sortable. In this format, the following additional parameters to fw-pagination-wrapper are available:
- * getTableColumns: Action callback to get the table columns. Callback in case it changes on search, but has no parameters
- * emptyText: Text to display when the table is empty. If unset, hides the table when empty.
- * tableActions: Parameter to send into fw-table-sortable’s tableActions
- * Block format
- * Block format allows passing in a custom table component instead of using fw-table-sortable. In this format, the table is included in the block with the search panel. To distinguish the two, a second parameter, table, is included. It will be an object for the table, and null for the search panel. The code below shows an example of using the block format with both parameters:
- * ```hbs
- * <FwPaginationWrapper
- *   …
- *   as |actions table|
- * >
+ * Parameter form:
+ * ```handlebars
+ * <FwPaginationWrapper @modelName="myModel" @defaultSortKey="sortKey" @makeQuery={{action "makeQuery"}} @getTitle={{action "getTitle"}} @getTableColumns={{action "getTableColumns"}} @tableActions={{hash ...}} as |actions|>
+ *   {{!-- Search panel contents --}}
+ *   {{!-- actions.search and actions.export are defined for you to use in this section appropriately--}}
+ * </FwPaginationWrapper>
+ * ```
+ * Block form:
+ * ```handlebars
+ * <FwPaginationWrapper @modelName="myModel" @defaultSortKey="sortKey" @makeQuery={{action "makeQuery"}} @getTitle={{action "getTitle"}} as |actions table|>
  *   {{#unless table}}
  *      {{!-- Search panel contents --}}
+ *      {{!-- actions.search and actions.export are defined for you to use in this section appropriately--}}
  *   {{else}}
  *      {{!-- Table component invocation --}}
+ *      {{!-- actions.sort and table.title, table.suffix, table.entries, and table.sortKey are defined for you to use in this section appropriately--}}
  *   {{/unless}}
  * </FwPaginationWrapper>
  * ```
- * In block format when table is defined, actions contains the following actions:
- * actions.sort: Action to use in fw-table-sortable’s onSort, called when a column is clicked.
- *
- * table contains the following parameters:
- * table.title: Full title for the table, pass to tables as title.
- * table.suffix: Suffix for the table title. Used in some custom table components.
- * table.entries: List of entries to display in the table. Passed to a table as the first unnamed parameter, rows.
- * table.sortKey: Currently active sort key for the table. Passed to a table as defaultSort *
- * ###Server Side
- *
- * The client side performs all history behavior using the browse method of the given model, based on the modelName parameter. The browse route must support several query parameters to handle all cases.
- * Count
- * The count parameter is a boolean that when set to true returns a count of results instead of the results. This is needed to calculate the number of pages available and to show the total in the table title.
- *
- * Count can be performed simply using $this->adapter->count in place of findAll. It takes two parameters, $modelName and $query, same as the first two parameters to findAll. For usage in the table, the result must be placed in a key, “count”, such as with the following code:
- * $count = $this->adapter->count($modelName, $query);
- * return $this->view->helper('json')->add($count, 'count');
- * Limit and Offset
- * The main feature of pagination is the ability to fetch only one page of results at a time, reducing the amount of data fetched in requests.
- * limit:
- * This parameter determines the number of entries per page, as defined by entriesPerPage.
- * This can be accomplished using a filter with $qb->limit.
- * offset:
- * This determines the first entry to be fetched for the limit.
- * This can be accomplished using a filter with $qb->offset.
- *
- * The following code implements both limit and offset:
- * ```js
- * if (isset($options->limit)) {*   $limit = $options->limit;*   $offset = $options->offset ?? 0;*   $this->adapter->addFilter($modelName, function($qb)*       use ($limit, $offset) {*     $qb->limit($limit);*     $qb->offset($offset);*   });
- * }
- * ```
- * Sorting
- * Pagination requires refetching all pages every time the sort order changes, as the first result may not be on the first page. fw-pagination-wrapper handles all the logic needed to do that client side, but it needs to be supported on the server side to work. This requires two parameters:
- * sortKey: Table key to use in sorting
- * ascending: If true, sorts results ascending. If false, sorts them descending.
- *
- * The following code implements sort key and ascending:
- * ```js
- * if (isset($options->sortKey)) {*   $sortKey = alias($options->sortKey);*   $ascending = ($options->ascending ?? 'false') == 'true';*   $ascending = $ascending ? 'ASC' : 'DESC';*   $this->adapter->addFilter($modelName, function($qb)*       use ($sortKey, $ascending) {*     $qb->orderBy($sortKey, $ascending);
- *  });
- * }
- * ```
- * In this code, alias is a function that maps the sortKey from the client side name used in the parameter to the server side name supported by SQL. Point of Sales handles this using a function in the model, called using $this->adapter->aliasKey.
- *
- * Note you may need more complex code to sort by complex table fields, such as a relationship (such as Status’s location name) or a computed value (such as Point of Sales’s transaction log total). An example of this can be found in Point of Sales.
- * Design Considerations
- * It is important to note that if you want to use SQL limiting and offsets, you should do all filtering and sorting using SQL. This means that any filters in PHP need to be migrated to SQL or otherwise some pages will return too few results.
- *
- *
- * @class FW-Pagination-Wrapper
+ * @class FwPaginationWrapper
+ * @module Components
  */
 export default Component.extend({
     layout,
@@ -139,7 +45,7 @@ export default Component.extend({
 
     didReceiveAttrs() {
         this._super(...arguments);
-        if (this.get('searchOnRender')) {
+        if (this.searchOnRender) {
             this.send('search');
         }
     },
@@ -193,7 +99,7 @@ export default Component.extend({
 
     /**
      * Gets the title of this table at the given time
-     * @property getTitle
+     * @method getTitle
      * @type {Action}
      * @return {String} Title of this table
      */
@@ -203,7 +109,7 @@ export default Component.extend({
 
     /**
      * Gets a list of table columns for exporting
-     * @property getTableColumns
+     * @method getTableColumns
      * @type {Action}
      * @return {Array} Array of table columns
      */
@@ -212,19 +118,20 @@ export default Component.extend({
     /**
      * Action to be called when the table search button is pressed.
      * @type {Function}
-     * @property onSearch
+     * @method onSearch
      */
     onSearch() {},
 
     /**
-     * Called to delete the full page of entries
-     * Should be passed in with a function
-     * @property deletePage
+     * Called to delete the full page of entries.
+     * Should be passed in with a function. Button will only appear if this is defined
+     * @method deletePage
+     * @type {Action}
      */
     deletePage: undefined,
 
     /**
-     * Determines permission for deleteTablePermission for fw-table-sortable
+     * Determines permission for deleteTablePermission for `FwTableSortable`. Should probably use a `has-role` helper from Group Control
      * @property deletePagePermission
      * @type {Boolean}
      * @default true
@@ -232,7 +139,7 @@ export default Component.extend({
     deletePagePermission: true,
     /**
      * Makes a query object based on the search fields
-     * @property makeQuery
+     * @method makeQuery
      * @type {Action}
      * @param  {Boolean} count  If true, counting
      * @param  {Number}  page   If defined, page number for a page search
@@ -262,7 +169,7 @@ export default Component.extend({
     emptyText: null,
 
     /**
-     * Actions to pass into the table
+     * Actions to pass into the table. Should be a hash as usual
      * @property tableActions
      * @type {Object}
      */
@@ -280,17 +187,19 @@ export default Component.extend({
      */
 
     /**
-     * Table title at this time
+     * Table title at this time. Internal property. Set by `getTableTitle`
      * @property currentTitle
      * @type {String}
+     * @private
      */
     currentTitle: null,
 
     /**
-     * If true, currently doing the main search
+     * If true, currently doing the main search. Internal property set by search functionality.
      * @property searchingTable
      * @type {Boolean}
      * @default false
+     * @private
      */
     searchingTable: false,
 
@@ -302,32 +211,36 @@ export default Component.extend({
      */
     showExport: true,
     /**
-     * Number of pages being searched
+     * Number of pages being searched. Internal property
      * @property pagesSearching
      * @type {Number}
      * @default 0
+     * @private
      */
     pagesSearching: 0,
 
     /**
-      * Array of entries, indexes are the pages
+      * Array of entries, indexes are the pages. Internal Property for more quickly rendering pages that have been searched this time.
       * @property pageEntries
       * @type {Array}
+      * @private
       */
     pageEntries: null,
 
     /**
-     * Currently selected page
+     * Currently selected page. Internal property to be set by clicking one of the page numbers.
      * @property page
      * @type {Number}
      * @default 1
+     * @private
      */
     page: 1,
 
     /**
-     * Total number of entries
+     * Total number of entries. Internal property set by the count network request.
      * @property count
      * @type {Number}
+     * @private
      */
     count: null,
 
@@ -338,9 +251,10 @@ export default Component.extend({
     lastQuery: null,
 
     /**
-     * Current sort order for the table
+     * Current sort order for the table. Internal property to keep track of current sort key.
      * @type {String}
      * @property currentSortKey
+     * @private
      */
     currentSortKey: null,
 
@@ -355,7 +269,7 @@ export default Component.extend({
      * @internal
      */
     index: computed('page', function() {
-        return this.get('page') - 1;
+        return this.page - 1;
     }),
 
     /**
@@ -365,11 +279,11 @@ export default Component.extend({
      * @internal
      */
     currentEntries: computed('pageEntries.[]', 'index', function() {
-        let entries = this.get('pageEntries');
+        let entries = this.pageEntries;
         if (isNone(entries)) {
             return [];
         }
-        return entries.objectAt(this.get('index'));
+        return entries.objectAt(this.index);
     }),
 
     /**
@@ -387,9 +301,9 @@ export default Component.extend({
      * @internal
      */
     tableSortKey: computed('defaultSortKey', 'currentSortKey', function() {
-        let current = this.get('currentSortKey');
+        let current = this.currentSortKey;
         if (isEmpty(current)) {
-            return `${this.get('defaultSortKey')}:desc`;
+            return `${this.defaultSortKey}:desc`;
         }
         return current;
     }),
@@ -401,12 +315,12 @@ export default Component.extend({
      * @internal
      */
     totalPages: computed('count', 'entriesPerPage', function() {
-        let count = this.get('count');
+        let count = this.count;
         if (isNone(count)) {
             return 0;
         }
 
-        return Math.ceil(count / this.get('entriesPerPage'));
+        return Math.ceil(count / this.entriesPerPage);
     }),
 
     /**
@@ -416,7 +330,7 @@ export default Component.extend({
      * @internal
      */
     showPages: computed('totalPages', function() {
-        return this.get('totalPages') > 1;
+        return this.totalPages > 1;
     }),
 
     /**
@@ -426,7 +340,7 @@ export default Component.extend({
      * @internal
      */
     maxPageButtons: computed('media.{isMobile,isTablet}', function() {
-        let media = this.get('media');
+        let media = this.media;
         if (media.get('isMobile')) {
             return 3;
         }
@@ -444,8 +358,8 @@ export default Component.extend({
      * @internal
      */
     routeName: computed('modelName', function() {
-        let name = this.get('modelName');
-        return this.get('store').adapterFor(name).pathForType(name);
+        let name = this.modelName;
+        return this.store.adapterFor(name).pathForType(name);
     }),
 
     /**
@@ -455,8 +369,8 @@ export default Component.extend({
      * @internal
      */
     tableSuffix: computed('count', 'currentEntries', 'index', function() {
-        let count = this.get('count');
-        let entries = this.get('currentEntries');
+        let count = this.count;
+        let entries = this.currentEntries;
         if (isEmpty(entries)) {
             return `${count} entries`;
         }
@@ -470,7 +384,7 @@ export default Component.extend({
      * @internal
      */
     fullTableTitle: computed('currentTitle', 'tableSuffix', function() {
-        return `${this.get('currentTitle')} - ${this.get('tableSuffix')}`;
+        return `${this.currentTitle} - ${this.tableSuffix}`;
     }),
 
     /**
@@ -484,8 +398,9 @@ export default Component.extend({
     /* Functions */
 
     /**
-     * Queries the serverside to get the total record count
+     * Queries the serverside to get the total record count. Internal method.
      * @method queryCount
+     * @private
      * @return {Promise} Promise that resolves to a number
      */
     queryCount() {
@@ -494,20 +409,21 @@ export default Component.extend({
         query.count = true;
 
         // make request
-        let url = this.get('config').formUrl(this.get('routeName'));
-        return this.get('ajax').request(url, {data: query}).then((({count}) => count)).catch(handleAjaxError.bind(this));
+        let url = this.config.formUrl(this.routeName);
+        return this.ajax.request(url, {data: query}).then((({count}) => count)).catch(handleAjaxError.bind(this));
     },
 
     /**
-     * Query for settign a new sort order
+     * Query for settign a new sort order. Internal method.
      * @method querySort
+     * @private
      * @param  {Number}  page      Page number to start
      * @param  {String}  sortKey   New sort order
      * @param  {Boolean} ascending If true, sorts ascending, false descending
      * @return {Promise}           Promise that resolves to a entry array
      */
     querySort(page, sortKey, ascending) {
-        let query = this.get('lastQuery');
+        let query = this.lastQuery;
 
         // set sort key stuff if present
         if (!isNone(ascending)) {
@@ -518,43 +434,45 @@ export default Component.extend({
         }
 
         // set limits on query
-        let entriesPerPage = this.get('entriesPerPage');
+        let entriesPerPage = this.entriesPerPage;
         query.limit = entriesPerPage;
         query.offset = (page - 1) * entriesPerPage;
 
         // make promise
-        return RSVP.resolve(this.get('store').query(this.get('modelName'), query)).catch(handleAjaxError.bind(this));
+        return RSVP.resolve(this.store.query(this.modelName, query)).catch(handleAjaxError.bind(this));
     },
 
     /**
-     * Fetches the entries for the given page number
+     * Fetches the entries for the given page number. Internal method
      * @method queryPage
+     * @private
      * @param  {Number}  page Page to fetch
      * @return {Promise}      Promise that resolves to an entry array
      */
     queryPage(page) {
         // same as sort, but handles the entries
         return this.querySort(page).then((entries) => {
-            this.get('pageEntries')[page - 1] = entries;
+            this.pageEntries[page - 1] = entries;
             return entries;
         });
     },
 
     /**
-     * Gets all entries for the given query
+     * Gets all entries for the given query. Internal method
      * @method queryAll
+     * @private
      * @return {Promise} Promise that resolves to entries
      */
     queryAll() {
         let query = this.makeQuery({export: true});
-        return RSVP.resolve(this.get('store').query(this.get('modelName'), query)).catch(handleAjaxError.bind(this));
+        return RSVP.resolve(this.store.query(this.modelName, query)).catch(handleAjaxError.bind(this));
     },
 
     actions: {
         /* Search buttons */
 
         /**
-         * This action is called when the search button is pressed
+         * This action is called when the search button is pressed. This is yielded as `actions.search` in the block.
          * @method search
          * @return {Promise} Promise that resolves after searching
          */
@@ -601,7 +519,7 @@ export default Component.extend({
         },
 
         /**
-         * This action is called when the export button is clicked to export all data
+         * This action is called when the export button is clicked to export all data. This is yielded in the block as `actions.export`.
          * @method export
          * @return {Promise} Promise that resolves after exporting the table
          */
@@ -609,9 +527,9 @@ export default Component.extend({
             // TODO: canSearch?
 
             // build table for export
-            let table = new Table(this.getExportColumns());
+            let table = Table.create({columns: this.getExportColumns()});
             return this.queryAll().then((entries) => {
-                table.setRows(entries.sortBy(this.get('defaultSortKey')).reverse());
+                table.setRows(entries.sortBy(this.defaultSortKey).reverse());
                 exportTable(table, `${this.getTitle()} - All Entries`);
             }).catch(handleAjaxError.bind(this));
         },
@@ -619,13 +537,14 @@ export default Component.extend({
         /* Pagination */
 
         /**
-         * This action is called when a page button is clicked to switch pages
+         * This action is called when a page button is clicked to switch pages. This is an internal action used in the page number button.
          * @method setPage
+         * @private
          * @param {Number} page New page number to set
          */
         setPage(page) {
             // clamp page number
-            let max = this.get('totalPages');
+            let max = this.totalPages;
             if (page < 1) {
                 page = 1;
             } else if (page > max) {
@@ -634,7 +553,7 @@ export default Component.extend({
 
             // if we havve entries at the page number, use those
             // if missing, query them
-            if (isNone(this.get('pageEntries').objectAt(page - 1))) {
+            if (isNone(this.pageEntries.objectAt(page - 1))) {
                 this.incrementProperty('pagesSearching');
                 this.set('page', page);
                 this.queryPage(page).then(() => {
@@ -649,7 +568,7 @@ export default Component.extend({
         /* Sorting */
 
         /**
-         * This action resorts the entry by the given column
+         * This action resorts the entry by the given column. This is yielded as `actions.sort`, when table is also defined. To be used in the `onSort` of your `FwSortableTable`.
          * @method sortColumn
          * @param  {Column} column  Column to use for sorting
          * @param  {String} sortKey String to use for sorting in the column
@@ -657,7 +576,7 @@ export default Component.extend({
          */
         sortColumn(column, sortKey) {
             // if the sort key is unchanged, do nothing
-            if (sortKey === this.get('tableSortKey')) {
+            if (sortKey === this.tableSortKey) {
                 return RSVP.resolve();
             }
 
@@ -665,7 +584,7 @@ export default Component.extend({
             column.set('sorting', true);
 
             // search for data
-            let page = this.get('page');
+            let page = this.page;
             return this.querySort(page, column.searchKey || column.valuePath, column.ascending).then((entries) => {
                 // set entries to new list
                 let pageEntries = [];

package/addon/components/fw-row-toggle-index.js

@@ -3,11 +3,11 @@ import layout from '../templates/components/fw-row-toggle-index';
 
 /**
  * Creates a table cell that shows if the row is expanded or hidden on hover, but
- * displays the value otherwise. While this can be called directly using `cellComponent`,
- * the [`rowToggle` util](../classes/BaseCells.html) will display this component if there
- * is a `valuePath` defined. See also [`FW-Row-Toggle`](FW-Row-Toggle.html).
+ * displays the value otherwise. See also [`FwRowToggle`](FwRowToggle.html).
  * @public
- * @class FW-Row-Toggle-Index
+ * @deprecated While this can be called directly using `cellComponent`, you should use the [`rowToggle` util](../classes/BaseCells.html) import, which will display this component if there is a `valuePath` defined.
+ * @class FwRowToggleIndex
+ * @module CellComponents
  */
 export default Toggle.extend({
     layout

package/addon/components/fw-row-toggle.js

@@ -3,14 +3,21 @@ import {computed} from '@ember/object';
 import layout from '../templates/components/fw-row-toggle';
 
 /**
- * Creates a table cell that shows if the row is expanded or hidden. While this can be called directly using `cellComponent`,
- * the [`rowToggle` util](../classes/BaseCells.html) will display this component if there
- * is no `valuePath` defined. See also [`FW-Row-Toggle-Index`](FW-Row-Toggle-Index.html).
- * @class FW-Row-Toggle
+ * Creates a table cell that shows if the row is expanded or hidden. See also [`FwRowToggleIndex`](FwRowToggleIndex.html).
+ *
+ * @deprecated While this can be called directly using `cellComponent`, you should use the [`rowToggle` util](../classes/BaseCells.html) import, which will display this component if there is no `valuePath` defined.
+ * @class FwRowToggle
+ * @module CellComponents
  */
 export default Component.extend({
     layout,
-
+    /**
+     * Computed property used internally to determine whether the "open" or "closed" toggle will be shown based on whether the row is expanded or not
+     * @private
+     * @property toggleClass
+     * @type {Computed}
+     * @return {String} This returns the appropriate Fontawesome class.
+     */
     toggleClass: computed('row.{canExpand,expanded}', function () {
         let classes;
         if (!this.get('row.canExpand')) {

package/addon/components/fw-table-expanded-row.js

@@ -3,17 +3,16 @@ import {computed} from '@ember/object';
 import layout from '../templates/components/fw-table-expanded-row';
 
 /**
- * This component is used internally as the logic behind the rows displayed inside rows
- * It is not included in the exports as it is not intended to be called directly
- * @protected
- * @module Components
- * @submodule Internal
+ * This component is used internally as the logic behind the rows displayed inside rows.
+ * It is not included in the exports as it is not intended to be called directly.
+ * @private
+ * @class FwTableExpandedRow
  */
 export default Component.extend({
     layout,
 
     value: computed('rawValue', function() {
-        let rawValue = this.get('rawValue');
+        let rawValue = this.rawValue;
         let format = this.get('column.format');
 
         if (format && typeof format === 'function') {

package/addon/components/fw-table-expanded-rows.js

@@ -3,19 +3,23 @@ import {computed} from '@ember/object';
 import {isEmpty} from '@ember/utils';
 import {showExpanded} from '../utils/table';
 import layout from '../templates/components/fw-table-expanded-rows';
-
+/**
+ * This component contains all of the hidden rows of `FwTableExpandedRow`. This is also used completely internally and should not be called directly.
+ * @private
+ * @class FwTableExpandedRow
+ */
 export default Component.extend({
     layout,
 
     columns: computed('table.expandedColumns', 'row', 'row.{canExpand}', function() {
-        let row = this.get('row');
-        let table = this.get('table');
+        let row = this.row;
+        let table = this.table;
         return this.get('table.expandedColumns').filter((column) => {
             return showExpanded(table, row, column);
         });
     }),
 
     hasColumns: computed('columns', function() {
-        return !isEmpty(this.get('columns'));
+        return !isEmpty(this.columns);
     })
 });