hedgeserv / ember-table

Ember Table

A table built using Ember.js that lazily renders rows.

This is an Ember-CLI wrapper around Addepar's Ember Table..

Ember Table allows you to handle very large data sets by only rendering the rows that are being displayed. It is written as an ember component with an API that is easy to understand and extend.

Demo and Documentation

http://addepar.github.com/ember-table/

Installing in your Ember CLI app

JS Bin Starter Kit

http://emberjs.jsbin.com/bihemir/edit

Installation with Ember CLI (Recommended)

**ember-cli >= 0.2.0**
ember install:addon ember-table
      
**ember-cli >= 0.2.3**
ember install ember-table

Once it's installed, you can customize the look of ember-table with CSS.

upgrading ember-cli

• npm uninstall -g ember-cli

• npm cache clean

• bower cache clean

• npm install -g [email protected]

• rm -rf node_modules bower_components dist tmp

• npm install

• bower install

• please refer to: ember-cli-upgrading

Installation with Bower (Globals-Based Version)

bower install ember-table --save

Or, just include dist/ember-table.js and dist/ember-table.css in your app.

Using Ember Table with bower is deprecated and will eventually be removed. We recommend that you migrate your apps to Ember CLI! Documentation has been updated to show Ember CLI usage. If you need documentation for globals-based use, please check out version 0.4.1 of Ember Table and follow the setup instructions under "Running Old Versions" to display the old guides.

Developing or Testing

After cloning this repo, install dependencies and run the demo app:

$ npm install
$ ember serve

You can view the examples at http://localhost:4200.

You can run the tests at http://localhost:4200/tests. Tests are a work in progress - no need to run them right now.

Before submitting a pull request, please compile the globals-based version of Ember Table (the dist folder):

$ npm install -g grunt-cli      # install grunt
$ grunt dist

Running Old Versions (pre-0.4.3)

If you are running an old version of Ember Table (pre-0.4.3), setup for development uses grunt and node rather than ember serve:

$ npm install -g grunt-cli
$ npm install
$ bower install
$ grunt
$ node examples.js              # run the demo app

You can then view the examples at http://localhost:8000/gh_pages.

Using with other Ember versions

Support for Ember 1.9, 1.10, and 1.11 (1.11.1 required) is available via branches of that name (e.g. ember-1.9)

Dependencies

• ember
• jquery-ui
• jquery.mousewheel
• antiscroll

Browser Support

We aim to support the last two major versions of every common browser.

If you need to support further browsers, we welcome pull requests with fixes.

Touch support may work but has not been tested.

Contributing

Got something to add? Great! Bug reports, feature ideas, and (especially) pull requests are extremely helpful, and this project wouldn't be where it is today without lots of help from the community.

Please read the contribution guidelines for directions on opening issues and working on the project.

Versioning

Ember Table uses Semantic Versioning to keep track of releases using the following format:

<major>.<minor>.<patch>

In a nutshell, this means:

• Breaking changes to the API or behavior increases the major version
• Adding functionality in a backwards-compatible way increases the minor version
• Making backwards-compatible bug fixes increases the patch version

Maintainers

Update version numbers and release using https://github.com/webpro/grunt-release-it:

$ vim CHANGELOG.md
$ grunt release-it:<options>

By default, this will release a new patch version. Other suggested commands:

$ grunt release-it:minor
$ grunt release-it:major
$ grunt release-it:X.Y.Z

Ember Table uses the "distribution repository" feature of release-it to push to the gh-pages branch and update documentation. When prompted, do NOT update the tag for the distribution repository. We'll streamline the release process a bit more soon.

Copyright and License

Copyright © 2013 Addepar, Inc. All Rights Reserved

Licensed under the BSD License (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE.md file.

ember-table's Issues

Collapsing row does not hide its children

Collapsing row does not hide its children.

The issue appeared after commit b14f078.

[PRIORITY 4] Multi-Column Sort Support

Description

To provide a facility for both a default implementation of, as well as rendering of the state of, data that has been sorted by multiple attributes. The default implementation should be able to handle a standard sort function on a series of columns where ascending/descending is provided. Regardless of whether the data is being sorted by default in ember-table or by an external data provider, ember-table should be able to render sort indicators on each sorted column based on metadata.

Requirements

Include a default implementation of multi-column sort

• 'Regular' click on a column header should make that the only column that is being used for the sort
• Repeated 'Regular' clicks on a column that is already sorts should cycle between ascending and descending
• 'Control/Command' click on column should add or remove it from the set of sorted columns
• Use the standard JS sort function on each sorted column
• Provide a facility to offload the sorting to an external provider/function
  • This should still use the default click behavior to control the column set / directions

Include a facility for rendering the state of sorted data

• ember-table should expose a property that includes metadata about the sorted columns and their directions
  • This property should be populated by the default sort implementation
  • This property to be editable from the outside when using some other method from controlling the sort order
• A default ascending / descending indicator should be rendered in the header of each sorted column
  • Default should indicate the order
  • There should be an ability to provide custom view/component to the sort indicator

Acceptance Criteria

Feature: Multi-Column Sorting
  In order to perform complex sorts on multi-column datasets
  As a user presented with a grid
  I need an intuitive an set of controls to specify which columns to sort on

  Scenario: Regular click when no existing sorting should sort ascending on column
    Given a grid with no existing sorting
    When a column is regular clicked
    Then the data is sorted ascending on the clicked column
     And an action is triggered with the sort metadata
     And the sort meta data is updated
     And the clicked column header indicates ascending sort

  Scenario: Control/Command click when no existing sorting should sort ascending on column
    Given a grid with no existing sorting
    When a column is control/command clicked
    Then the data is sorted ascending on the clicked column
     And an action is triggered with the sort metadata
     And the sort meta data is updated
     And the clicked column header indicates ascending sort

  Scenario: Data sorted ascending on a single column reverses when the column is regular clicked
    Given a grid that is sorted on a single column
     And the sort direction is ascending
    When a column is regular clicked
    Then the data is sorted descending on the clicked column
     And an action is triggered with the sort metadata
     And the sort meta data is updated
     And the clicked column header indicates descending sort

 Scenario: Data sorted ascending on a single column unsorts when the column is control/command clicked
   Given a grid that is sorted on a single column
    And the sort direction is ascending
   When a column is control/command clicked
   Then the data is unsorted
    And an action is triggered with the sort metadata
    And the sort meta data is updated
    And the clicked column header indicates no sort

  Scenario: Data sorted descending on a single column reverses when the column is regular clicked
    Given a grid that is sorted on a single column
     And the sort direction is descending
    When a column is regular clicked
    Then the data is sorted ascending on the clicked column
     And an action is triggered with the sort metadata
     And the sort meta data is updated
     And the clicked column header indicates ascending sort

 Scenario: Data sorted descending on a single column unsorts when the column is control/command clicked
   Given a grid that is sorted on a single column
    And the sort direction is ascending
   When a column is control/command clicked
   Then the data is unsorted
    And an action is triggered with the sort metadata
    And the sort meta data is updated
    And the clicked column header indicates no sort

  Scenario: Data sorted on a single column regular click on different column changes sort to that column
    Given a grid that is sorted on a single column
    When a different column is regular clicked
    Then the data is sorted only on the new column
     And an action is triggered with the sort metadata
     And the sort meta data is updated
     And the clicked column header indicates ascending sort
     And the previously sorted column header indicates no sort

  Scenario: Data sorted on a single column control/command click on different column adds the column to the sort
    Given a grid that is sorted on a single column
     When a different column is control/command clicked
     Then the new column is added to the sort order after the previous column
      And the previous column now indicates it is the first column sorted
      And the previous column maintains the same sort order
      And the new column indicates that it is the second column sorted
      And the new column is indicates it is sorted ascending
      And the sort metadata is updated
      And an action is triggered with the sort metadata

  Scenario: Data sorted on a multiple columns control/command click on different column adds the column to the sort
    Given a grid that is sorted on a multiple columns
     When a different column is control/command clicked
     Then the new column is added to the sort order after the previous columns
      And the previous columns maintain the same sort order
      And the new column indicates that it is the second column sorted
      And the new column is indicates it is sorted ascending
      And the sort metadata is updated
      And an action is triggered with the sort metadata

  Scenario: Data sorted on a multiple columns regular click on different column changes sort to that column
    Given a grid that is sorted on a multiple columns
     When a different column is regular clicked
     Then the data is sorted only on the new column
      And an action is triggered with the sort metadata
      And the sort meta data is updated
      And the clicked column header indicates ascending sort
      And the previously sorted column headers indicate no sort

  Scenario: Data sorted on a multiple columns regular click on existing column toggles direction for that column
    Given a grid that is sorted on a multiple columns
     When a existing sorted column is regular clicked
     Then the direction for the sorted column reverses
      And the clicked column indicates the new sort direction
      And the sort metadata is updated
      And an action is triggered with the sort metadata

  Scenario: Data sorted on a multiple columns control/command click on existing column removes column from sort
    Given a grid that is sorted on a multiple columns
     When a existing sorted column is control/command clicked
     Then the data is no longer sorted using that column
      And the clicked column indicates no sort
      And all remaining columns have their sort order indicator updated
      And the sort metadata is updated
      And an action is triggered with the sort metadata

[PRIORITY 1] Large Dataset Support

Description

Extend ember-table-addon such that is can support partial / lazily-loaded datasets that are transparently loaded in chunks as the user scrolls down the rows of the table, much like an infinite scroll but with a defined max size. ember-table-addon should be modified to provide the necessary events/actions about the current state of the table (i.e., scroll position) that would be needed to know when to fetch a new chunk, but the actual management/tracking of chunked data should be handled by a separate data-provider.

Requirements

• Everything about lazily-loaded data should be optional. Meaning, there should be no changes to how anyone uses ember-table-addon today or even after this work if they do not want lazily loaded data
  • This also applies to the initial call to the load the data. Meaning, the server decides if it wants to chunk the data, so the data provider must be able to interrogate the response to see if it is the full dataset or if the data is chunked
  • The chunk size should be controlled by the server and not dictated by ember-table
• Management of when/what to lazily-load to be done by a separate (i.e. not directly by ember-table-addon) data-provider. I can be bundled with ember-table-addon
• Any model objects and data-provider should use ember-data
• The data-provider will need to pass the current grid sort order to the server so that the data can be returned in the order that it is being sorted
  • When the sort order is changed, if the client still only has a portion of the data, it needs to dump all of the data it currently has, and start a new query to the server
  • When the sort order is changed, if the client has all of the data, it can do the correct sorting client-side
• ember-table-addon will need to be able to understand the notion of a partial data-set so that it can do the following:
  • Render a scrollbar that represents the 'full size' of the dataset, even when only part of the dataset has been loaded
  • Provide events or actions to the data-provider so that it knows the current position within the dataset so that the provider can decide if it needs load another chunk
  • Adding a new chunk of data should not cause ember-table-addon to fully rerender as that partially defeats the purpose of this performance optimization
• Include and publish a separate node-module to NPM to provide any necessary server-side interfaces necessary to facilitate the chunking of data
• Assuming acceptable performance, there is no need to evict records after they are loaded, so there is no need to support reloading chunks as a user scrolls up/down the table
• This functionality should not require all usage of ember-table-addon to render models that extend any particular base class. However, in order to support chunked data, it can require the rendered models to extend a base class
• The existing virtual scroll container used by ember-table-addon must continue to be used. (Meaning, do not change to something like ember-list-view)

Test

• Include qunit-based unit tests for all new components created or for any existing ember-table-addon components that are modified
• Ensure those tests run correctly via ember-cli / testem
• ember-table-addon should maintain out-of-the-box compatibility with Jenkins by following current best-practices

Acceptance Criteria

All of these are applicable: https://github.com/hedgeserv/ember-table-addon-demo-app/wiki
Additionally:

Feature: Large Dataset Support
  In Order to interact with a large datatset
  As a user
  I want to have the best possible performance

  Scenario: Data provider should not know ahead of time and handle complete data
    Given there are 1000 rows
      And the server does not return any chunking metadata
     Then the dataset should be assumed to be complete
      And and rendered according to the size of the presentation limit

Scenario: Data provider should not know ahead of time and handle chunked data
    Given there are 1000 rows
      And the server does return chunking metadata
     Then the dataset should be assumed to be chunked
      And and the first chunk should be rendered
      And and the chunk size should be set from the metadata

  Scenario: Scroll bar shows correct size, even with partial data
    Given there are 1000 rows
    And a presentation limit of 50 rows
    When initially presenting the rows
    Then only the first 50 rows should be shown
    And the the scroll affordance should indicate the total size of 1000 rows

  Scenario: Changing sort order does not reload data for complete datasets
    Given There are 1000 rows
    And All 1000 rows have been loaded
    When The user changes the sort order
    Then No new data is requested from the backend
    And The new first chunk of data should be rendered

  Scenario: Changing sort order restarts data loading for partial datasets
    Given There are 1000 rows
    And Only 200 rows have been loaded
    When The user changes the sort order
    Then All loaded rows should be discarded
    And A new first chunk of data should be loaded
    And The new first chunk of data should be rendered

Extras

Keep an eye on this story. Seems like other are looking for similar things and that Addepar may not be immediately be interested in this change if its done in a way that complicates the core of ember-table: Addepar#307

[PRIORITY 2] Column Groups

Description

Provide a facility to visually group columns together into column-groups. This is a very common practice when applying grids to finance concepts as a way to 'shorten' the amount of text that needs to go into the header when there are related columns. For example, if the grid includes data about people, you may wish to show multiple attributes about their hair, such as the Length and the Color and group them together under a shared header 'Hair'.

Requirements

• A grouped column should be provided in the columns array passed to ember-table just like any other column
  • It should include a property that is an array of the inner columns for the group
  • The same current properties of a Em.Table.ColumnDefinition should control what header renderer to use for the group header (headerCellViewClass for example). You may need to provide a new default for a grouped column
• The width of a grouped column should not be independently setable, it is derived from the width of its children
• Only the inner columns should be resizable, the group itself is not
• When column drag/drop is enabled
  • From the grouped header, the entire group is the unit that is dragged/dropped
  • Within the group, the inner columns can be dragged/dropped to reorder within the group
• There is no notion of 'sorting' at the column group level, only on the inner columns
• Include a CSS class(es) to support the following:
  • styling for the entire group
  • styling for each column in the group
  • styling for the first column in the group
  • styling for the last column in the group
  • styling for the separator between groups

Test

• Include mocha-based unit tests for all new components created or for any existing ember-table-addon components that are modified
• Ensure those tests run correctly via ember-cli / testem
• ember-table-addon should maintain out-of-the-box compatibility with Jenkins be following current best-practices

Acceptance Criteria

Feature: Grouped Columns
  In Order to sort data in grouped columns
  As a user of a gird with grouped columns
  I have to sort the inner columns

  Scenario: Column group header should not have a sort indicator
    Given a grid with grouped columns
    And sorting is enabled
    When at least one of the inner columns for the group is sorted
    Then the sorted inner column should indicate the sort direction
    And grouped column should not have a sort indicator

   Scenario: Column group header should not be sortable
    Given a grid with grouped columns
    And sorting is enabled
    When the user clicks on the grouped header
    Then the sorting of the data should not change
    And no sorting actions should be emitted

   Scenario: Columns in a column group should be sortable
    Given a grid with grouped columns
    And sorting is enabled
    When the user clicks on the header of an inner column in a group
    Then the sorting of the data should change
    And a sorting action should be emitted

Feature: Grouped Columns
  In Order to reorder grouped columns
  As a user of a gird with grouped columns
  I have to know which header to drag

  Scenario: Dragging the column group header should reorder with entire group
    Given a grid with grouped columns
    And reorderable columns is enabled
    When a user drags the column group header
    Then the entire grouped column should move
    And should move to the correct position on the grid when released
    And a reorder action should be triggered

  Scenario: Dragging an inner column header should reorder that column within the group
    Given a grid with grouped columns
    And reorderable columns is enabled
    When a user drags an inner column header
    Then only the column should move
    And the column should not be releasable outside of the group
    And upon release, the new order within the group should be applied
    And a reorder action should be triggered

Feature: Grouped Columns
  In Order to resize grouped columns
  As a user of a gird with grouped columns
  I have to use the inner columns to expand the width of the group

  Scenario: Dragging the left column separator on grouped column should resize the neighboring column
    Given a grid with grouped columns
    And resizable columns is enabled
    When a user drags the left column separator on a grouped column
    Then the user should get the resize cursor
    And and the neighboring column to the left should resize
    And the grouped column should not resize

  Scenario: Dragging the right column separator on grouped column should resize the last inner column
    Given a grid with grouped columns
    And resizable columns is enabled
    When a user drags the right column separator on a grouped column
    Then the user should get the resize cursor
    And and the last inner column of the group should resize
    And the overall size of the group should resize
    And none of the rest of the inner columns of the group should resize

  Scenario: Dragging the column separator on any inner column should resize that column
    Given a grid with grouped columns
    And resizable columns is enabled
    When a user drags the the column separator on an inner column
    And the separator is not the right side of the last column in the group
    Then the user should get the resize cursor
    And and the inner column of the group should resize
    And the overall size of the group should resize
    And none of the rest of the inner columns of the group should resize

[PRIORITY 3] Grouped Rows with Expandable/Collapsable Presentation

Description

To provide a facility for both the client-side management of, and visualization of/interaction with, data where rows have been grouped together into parent/child relationships. Row-grouped data is commonly used to both visually represent how complex datapoints are derived from there constituents, and also as a performance optimization to control how much data needs to be calculated and/or served up to the client.

Requirements

Include a grouped data provider to manage the on-demand loading of any partially loaded data

• Must support an arbitrary nesting depth (meaning any row could have any number of children rows, recursively down each child)
• Must support the ability to know if the children for a row have been loaded or if they must to be loaded as needed
• At any level, the data returned from the server may be chunked
  • Meaning when a request is made to load the children for a given row, the response from the server may indicate that the data has been chunked and will need to be paged in as the user scrolls down the grid
    
  • The initial/top-level set of rows may also be chunked
• Can optionally indicate the presence of a 'grand total' row
  • Meaning, at the very top level, there will be only one row
  • This row is not considered in the grouping metadata: i.e., if the groping metadata indicates 2 levels of grouping, that is exclusive of the grand total row
  • There should be a way to specify what value to render for the label in the grouping column for the grand total row

Provide UI for the expansion/contraction of grouped rows

• Must include a pluggable view/component for rendering the expansion/contraction indicator
  • Must include a default (for example, a +/- icon)
  • Must support being positioned at either the top or bottom of the row-group
    • The position must be passed to the component as it may wish to render differently depending on location
  • Must pass the expanded/contracted state to the component
• Must indicate to the user if the request data is being loaded
  • Meaning, when the user expands a group, if the children rows need to be loaded, that should be indicated to the user
  • Must include a pluggable view/component for rendering a 'loading' indicator
  • Must include a default loading component
    
• Must be able to handle an arbitrary depth
  • This may require expanding the size of the grouping column as the depth increases
  • Depth must be passed to the expansion/contraction indicator so that it can optionally include that information in its presentation

Implicitly provide a grouping column when using a grouped data provider

• Must be treated as a locked column, even when there is no locked column count provided
  • The specified locked column count should be in addition to the grouped column
• Must not be draggable even when draggable columns is enabled
• Should always be the first / left-most column
• Does not need to be included in the columns array
  • Meaning, should be implicitly created when using a grouped data provider
• Can rely on grouping metadata to be provided to the grid
  • Meaning, which properties are grouped on and in which order

Sorting for the groupings should be handled independently of the sorting for the data

• Clicking on a grouping column header should have no impact on sorting
  • The actual sorting of the data is handled by the grouped data provider, but the grid should be able to differentiate sort actions between the grouped rows and the leaf/lowest rows
• Clicking on a regular column header should change the sort order for all of the leaf/lowest level rows, but not on the groupings

Acceptance Criteria

Feature: Indicators for expanding and collapsing grouped rows
  In order to manage the parent/child relationships of large datasets
  As a user presented with a grid
  I need an intuitive an set of controls

  Scenario: Default expansion indicator with fully loaded data
    Given a grid with grouped rows
      And all childrend rows for a given row have been load
      And there is no custom indicator
      And the group is collapsed
     When the user clicks on the expansion indicator
     Then the children rows should be shown
      And no loading indicator should be shown
      And the deafult expansion indicator should transition to contraction indicator

  Scenario: Default contraction indicator with fully loaded data
    Given a grid with grouped rows
      And all childrend rows for a given row have been load
      And there is no custom indicator
      And the group is expanded
     When the user clicks on the contraction indicator
     Then the children rows should be hidden
      And no loading indicator should be shown
      And the default contraction indicator should transition to expansion indicator

  Scenario: Custom expansion indicator with fully loaded data
    Given a grid with grouped rows
      And all childrend rows for a given row have been load
      And there is a custom indicator
      And the group is collapsed
     When the user clicks on the expansion indicator
     Then the children rows should be shown
      And no loading indicator should be shown
      And the custom expansion indicator should transition to contraction indicator

  Scenario: Custom contraction indicator with fully loaded data
    Given a grid with grouped rows
      And all childrend rows for a given row have been load
      And there is a custom indicator
      And the group is expanded
     When the user clicks on the contraction indicator
     Then the children rows should be hidden
      And no loading indicator should be shown
      And the contraction indicator should transition to expansion indicator

  Scenario: Showing loading indicator with partially loaded data
    Given a grid with grouped rows
      And the children rows for a given row have not been loaded
     When the user clicks on the expansion indicator
     Then the children rows should not be shown
      And the children rows should be loaded
      And the loading indicator should be shown

  Scenario: Hiding loading indicator with partially loaded data
    Given a grid with grouped rows
      And the children rows for a given row have not been loaded
      And the user has clicked the expansion indicator
     When the children rows have finished loading
     Then the loading indicator should not be shown
      And the children rows should be shown

  Scenario: Grouping colum should always be rendered
    Given data with grouped rows
      And N columns
     When the grid is rendered
     Then N+1 columns should be rendered
      And the first column should be the `grouping column`

  Scenario: Grouping column should always be locked
    Given data with grouped rows
      And no locked columns
     When the grid is rendered
     Then then the `grouping column` should be the first column
      And and the `grouping column` should be locked

  Scenario: Grouping column should be locked in addition
    Given data with grouped rows
      And two locked columns
     When the grid is rendered
     Then then the `grouping column` should be the first column
      And and the `grouping column` should be locked
      And the next two columns should be locked

  Scenario: Grouping column should not be draggable
    Given data with grouped rows
      And the a grid that has draggable columns
     When the grid is rendered
     Then then the `grouping column` should be the first column
      And and the `grouping column` should not be draggable
      And any other column should be draggable

  Scenario:Grouping column should not be sortable
      Given data with grouped rows
        And the grid is sortable
     When the `grouping column` header is clicked
      Then the data should not be sorted
       And the `grouping column` header should not change

  Scenario:All other columns should be sortable
    Given data with grouped rows
       And the grid is sortable
    When any column header that is not the `grouping column` is clicked
     Then the child rows should be sorted
      And the grouping rows should remain in the previous order

  Scenario: Grouping column labels pull correctly from rows
     Given data with grouped rows
       And data[0].propertyOne = 'foo'
       And data[0]children[0].propertyTwo = 'bar'
       And grouping metadata indicates 2 levels of grouping
       And grouping metadata[0] is grouped on property 'propertyOne'
       And grouping metadata[1] is grouped on property 'propertyTwo'
     When the grouping column is rendered
       And the first group is expanded
     Then the label for the first grouping row is 'foo'
       And the label for the first child row of the first grouping row is 'bar'