5.20193.637
PivotCollectionView Wijmo API Class

PivotCollectionView Class

Extends the CollectionView class to preserve the position of subtotal rows when sorting.

Type parameters

  • T

Heirarchy

Constructors

constructor

Properties

canAddNew

canAddNew: boolean

Gets a value that indicates whether a new item can be added to the collection.

canCancelEdit

canCancelEdit: boolean

Gets a value that indicates whether the collection view can discard pending changes and restore the original values of an edited object.

canChangePage

canChangePage: boolean

Gets a value that indicates whether the pageIndex value can change.

canFilter

canFilter: boolean

Gets a value that indicates whether this view supports filtering via the filter property.

canGroup

canGroup: boolean

Gets a value that indicates whether this view supports grouping via the groupDescriptions property.

canRemove

canRemove: boolean

Gets a value that indicates whether items can be removed from the collection.

canSort

canSort: boolean

Gets a value that indicates whether this view supports sorting via the sortDescriptions property.

currentAddItem

currentAddItem: T

Gets the item that is being added during the current add transaction.

currentEditItem

currentEditItem: T

Gets the item that is being edited during the current edit transaction.

currentItem

currentItem: T

Gets or sets the current item in the view.

currentPosition

currentPosition: number

Gets the ordinal position of the current item in the view.

engine

engine: PivotEngine

Gets a reference to the PivotEngine that owns this view.

filter

filter: IPredicate

Gets or sets a callback used to determine if an item is suitable for inclusion in the view.

The callback should return true if the item passed in as a parameter should be included in the view.

NOTE: If the filter function needs a scope (i.e. a meaningful 'this' value) remember to set the filter using the 'bind' function to specify the 'this' object. For example:

  collectionView.filter = this._filter.bind(this);

filters

filters: ObservableArray<IPredicate>

Gets an array of {@link IPredicate} functions used as filters on this CollectionView.

To be included in the view, an item has to pass the predicate in the filter property as well as all predicates in the filters collection.

getError

getError: IGetError

Gets or sets a callback that determines whether a specific property of an item contains validation errors.

If provided, the callback should take two parameters containing the item and the property to validate, and should return a string describing the error (or null if there are no errors).

For example:

import { CollectionView } from '@grapecity/wijmo';
var view = new CollectionView(data, {
    getError: function (item, property) {
        switch (property) {
            case 'country':
                return countries.indexOf(item.country) &lt; 0
                    ? 'Invalid Country'
                    : null;
            case 'downloads':
            case 'sales':
            case 'expenses':
                return item[property] &lt; 0
                    ? 'Cannot be negative!'
                    : null;
            case 'active':
                return item.active && item.country.match(/US|UK/)
                    ? 'No active items allowed in the US or UK!'
                    : null;
        }
        return null;
    }
});

groupDescriptions

groupDescriptions: ObservableArray<GroupDescription>

Gets a collection of GroupDescription objects that describe how the items in the collection are grouped in the view.

groups

Gets an array of CollectionViewGroup objects that represents the top-level groups.

isAddingNew

isAddingNew: boolean

Gets a value that indicates whether an add transaction is in progress.

isEditingItem

isEditingItem: boolean

Gets a value that indicates whether an edit transaction is in progress.

isEmpty

isEmpty: boolean

Gets a value that indicates whether this view contains no items.

isPageChanging

isPageChanging: boolean

Gets a value that indicates whether the page index is changing.

isUpdating

isUpdating: boolean

Gets a value that indicates whether notifications are currently suspended (see beginUpdate and endUpdate).

itemCount

itemCount: number

Gets the total number of items in the view taking paging into account.

items

items: T[]

Gets items in the view.

itemsAdded

itemsAdded: ObservableArray

Gets an ObservableArray containing the records that were added to the collection since trackChanges was enabled.

itemsEdited

itemsEdited: ObservableArray

Gets an ObservableArray containing the records that were edited in the collection since trackChanges was enabled.

itemsRemoved

itemsRemoved: ObservableArray

Gets an ObservableArray containing the records that were removed from the collection since trackChanges was enabled.

newItemCreator

newItemCreator: IItemCreator<T>

Gets or sets a function that creates new items for the collection.

If the creator function is not supplied, the CollectionView will try to create an uninitialized item of the appropriate type.

If the creator function is supplied, it should be a function that takes no parameters and returns an initialized object of the proper type for the collection.

pageCount

pageCount: number

Gets the total number of pages.

pageIndex

pageIndex: number

Gets the zero-based index of the current page.

pageSize

pageSize: number

Gets or sets the number of items to display on each page.

refreshOnEdit

refreshOnEdit: boolean

Gets or sets a value that determines whether the CollectionView should automatically refresh its results (by applying the sort, filter, and grouping operations) after items are edited.

This property is set to true by default, which ensures the collection is always sorted, filtered, and grouped correctly after any edit operations.

Set it to false if you want updates to be deferred when items are edited. In this case, the collection will not be refreshed until the sorting, filtering, and grouping criteria change or until the refresh method is called (Excel behavior).

sortComparer

sortComparer: IComparer<T>

Gets or sets a function used to compare values when sorting.

If provided, the sort comparer function should take as parameters two values of any type, and should return -1, 0, or +1 to indicate whether the first value is smaller than, equal to, or greater than the second. If the sort comparer returns null, the standard built-in comparer is used.

This sortComparer property allows you to use custom comparison algorithms that in some cases result in sorting sequences that are more consistent with user's expectations than plain string comparisons.

For example, see Dave Koele's Alphanum algorithm. It breaks up strings into chunks composed of strings or numbers, then sorts number chunks in value order and string chunks in ASCII order. Dave calls the result a "natural sorting order".

The example below shows a typical use for the sortComparer property:

// create a CollectionView with a custom sort comparer
var dataCustomSort = new wijmo.collections.CollectionView(data, {
  sortComparer: function (a, b) {
    return wijmo.isString(a) && wijmo.isString(b)
      ? alphanum(a, b) // use custom comparer for strings
      : null; // use default comparer for everything else
  }
});

The example below shows how you can use an Intl.Collator to control the sort order:

// create a CollectionView that uses an Intl.Collator to sort
var collator = window.Intl ? new Intl.Collator() : null;
var dataCollator = new wijmo.collections.CollectionView(data, {
  sortComparer: function (a, b) {
    return wijmo.isString(a) && wijmo.isString(b) && collator
      ? collator.compare(a, b) // use collator for strings
      : null; // use default comparer for everything else
  }
});

sortConverter

sortConverter: ISortConverter

Gets or sets a function used to convert values when sorting.

If provided, the function should take as parameters a SortDescription, a data item, and a value to convert, and should return the converted value.

This property provides a way to customize sorting. For example, the FlexGrid control uses it to sort mapped columns by display value instead of by raw value.

For example, the code below causes a CollectionView to sort the 'country' property, which contains country code integers, using the corresponding country names:

var countries = 'US,Germany,UK,Japan,Italy,Greece'.split(',');
collectionView.sortConverter = function (sd, item, value) {
  if (sd.property == 'countryMapped') {
    value = countries[value]; // convert country id into name
  }
  return value;
}

sortDescriptions

sortDescriptions: ObservableArray

Gets an array of SortDescription objects that describe how the items in the collection are sorted in the view.

sortNullsFirst

sortNullsFirst: boolean

Gets or sets a value that determines whether null values should appear first or last when the collection is sorted (regardless of sort direction).

This property is set to false by default, which causes null values to appear last on the sorted collection. This is also the default behavior in Excel.

sourceCollection

sourceCollection: any

Gets or sets the underlying (unfiltered and unsorted) collection.

totalItemCount

totalItemCount: number

Gets the total number of items in the view before paging is applied.

trackChanges

trackChanges: boolean

Gets or sets a value that determines whether the control should track changes to the data.

If trackChanges is set to true, the CollectionView keeps track of changes to the data and exposes them through the itemsAdded, itemsRemoved, and itemsEdited collections.

Tracking changes is useful in situations where you need to update the server after the user has confirmed that the modifications are valid.

After committing or cancelling changes, use the clearChanges method to clear the itemsAdded, itemsRemoved, and itemsEdited collections.

The CollectionView only tracks changes made when the proper CollectionView methods are used (editItem/commitEdit, addNew/commitNew, and remove). Changes made directly to the data are not tracked.

useStableSort

useStableSort: boolean

Gets or sets whether to use a stable sort algorithm.

Stable sorting algorithms maintain the relative order of records with equal keys. For example, consider a collection of objects with an "Amount" field. If you sort the collection by "Amount", a stable sort will keep the original order of records with the same Amount value.

This property is set to false by default, which causes the CollectionView to use JavaScript's built-in sort method, which is fast but not garanteed to be stable.

Setting the useStableSort property to true ensures stable sorts on all browsers, but increases sort times by 30% to 50%.

Note: Chrome provides stable sorting since version 70, and Firefox since version 3. As of ES2019, sort is required to be stable. In ECMAScript 1st edition through ES2018, it was allowed to be unstable.

Methods

addNew

  • addNew(): T
  • Creates a new item and adds it to the collection.

    This method takes no parameters. It creates a new item, adds it to the collection, and defers refresh operations until the new item is committed using the commitNew method or canceled using the cancelNew method.

    The code below shows how the addNew method is typically used:

    // create the new item, add it to the collection
    var newItem = view.addNew();
    // initialize the new item
    newItem.id = getFreshId();
    newItem.name = 'New Customer';
    // commit the new item so the view can be refreshed
    view.commitNew();
    

    You can also add new items by pushing them into the sourceCollection and then calling the refresh method. The main advantage of addNew is in user-interactive scenarios (like adding new items in a data grid), because it gives users the ability to cancel the add operation. It also prevents the new item from being sorted or filtered out of view until the add operation is committed.

    Returns T

    The item that was added to the collection.

beginUpdate

  • beginUpdate(): void

cancelEdit

  • cancelEdit(): void

cancelNew

  • cancelNew(): void

clearChanges

  • clearChanges(): void

commitEdit

  • commitEdit(): void

commitNew

  • commitNew(): void

contains

  • contains(item: T): boolean

deferUpdate

  • deferUpdate(fn: Function): void

editItem

  • editItem(item: T): void
  • Begins an edit transaction of the specified item.

    Parameters

    • item: T

      Item to be edited.

    Returns void

endUpdate

  • endUpdate(): void

getAggregate

  • getAggregate(aggType: Aggregate, binding: string, currentPage?: boolean): any
  • Calculates an aggregate value for the items in this collection.

    Parameters

    • aggType: Aggregate

      Type of aggregate to calculate.

    • binding: string

      Property to aggregate on.

    • Optional currentPage: boolean

      Whether to include only items on the current page.

    Returns any

    The aggregate value.

implementsInterface

  • implementsInterface(interfaceName: string): boolean

moveCurrentTo

  • moveCurrentTo(item: T): boolean

moveCurrentToFirst

  • moveCurrentToFirst(): boolean

moveCurrentToLast

  • moveCurrentToLast(): boolean

moveCurrentToNext

  • moveCurrentToNext(): boolean

moveCurrentToPosition

  • moveCurrentToPosition(index: number): boolean

moveCurrentToPrevious

  • moveCurrentToPrevious(): boolean

moveToFirstPage

  • moveToFirstPage(): boolean

moveToLastPage

  • moveToLastPage(): boolean

moveToNextPage

  • moveToNextPage(): boolean

moveToPage

  • moveToPage(index: number): boolean

moveToPreviousPage

  • moveToPreviousPage(): boolean

onCollectionChanged

onCurrentChanged

onCurrentChanging

onPageChanged

onPageChanging

onSourceCollectionChanged

  • onSourceCollectionChanged(e?: EventArgs): void

onSourceCollectionChanging

refresh

  • refresh(): void

remove

  • remove(item: T): void
  • Removes the specified item from the collection.

    Parameters

    • item: T

      Item to be removed from the collection.

    Returns void

removeAt

  • removeAt(index: number): void
  • Removes the item at the specified index from the collection.

    Parameters

    • index: number

      Index of the item to be removed from the collection. The index is relative to the view, not to the source collection.

    Returns void

Events

collectionChanged

Occurs when the collection changes.

currentChanged

currentChanged: Event<CollectionView<any>, EventArgs>

Occurs after the current item changes.

currentChanging

currentChanging: Event<CollectionView<any>, CancelEventArgs>

Occurs before the current item changes.

pageChanged

pageChanged: Event<CollectionView<any>, EventArgs>

Occurs after the page index changes.

pageChanging

Occurs before the page index changes.

sourceCollectionChanged

sourceCollectionChanged: Event<CollectionView<any>, EventArgs>

Occurs after the value of the sourceCollection property changes.

sourceCollectionChanging

sourceCollectionChanging: Event<CollectionView<any>, CancelEventArgs>

Occurs before the value of the sourceCollection property changes.