Columns class (Pivot)

Columns(oPivot)

new Columns(oPivot)

The Columns object holds a collection of Column objects (column of the control). Use the Pivot.Columns method to access the control's columns collection. The Columns object provides methods to manage the control's columns collection, such as adding, removing, sorting and getting columns. The Column property of the control retrieves a column giving its index, identifier/key/caption or reference. The Add, Remove and Clear methods of the Columns object allow adding, removing and clearing columns of the control. The Sorts property allows sorting multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A". The VisibleCount and VisibleItem methods allow managing visible-columns of the control (@since 5.1).
Parameters:
Name Type Description
oPivot Pivot Indicates an object of Pivot type that owns the collection.

Members

Count :number

The Count property returns the number of columns within the collection. The Count property is equivalent of GetCount() method. The GetVisibleCount() method returns the number of visible-columns only. The Item method gets the column giving its index, identifier/key/caption or reference. The VisibleItem() method gets the visible-column at giving position (for instance, a column with 'visible' property on false is ignored).
Type:
  • number
Example
The following statements are equivalents:

 oPivot.Columns.GetCount(), returns the number of columns within the collection
 oPivot.Columns.Count, returns the number of columns within the collection

 The following code snippet enumerates all columns:

 for (var i = 0, l = oPivot.Columns.Count; i < l; i++)
   console.log(oPivot.Columns.Item(i));

where oPivot is an object of Pivot type
Count

Sorts :string

The Sorts property sorts or groups multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A". The Sorts property is equivalent of SetSorts() method. The onsort event notifies your application once a column gets sorted or grouped by. The Sorts property specifies a string listing all columns currently sorted in the control, using the format `index:direction` for each column. Columns in the sort bar are separated by spaces, and the single-sort column (if any) is appended after a comma.

Each column to be sorted is represented in the format `index:direction`, where:

  • `index` is the zero-based column index within the control
    • `direction` is the sort direction, represented by `A` for ascending or `D` for descending
Columns displayed in the sort bar should be listed first, followed by the single-sort column, if applicable.

For instance, the string "1:A 2:D, 0:A" indicates:

"1:A", column at index 1, sorted ascending, displayed in the sort bar
"2:D", column at index 2, sorted descending, displayed in the sort bar
"0:A", column at index 0, the single-sort column of the control, sorted ascending
Sorting behavior depending on the AllowGroupBy property:
  • When the control's AllowGroupBy property is enabled, columns listed in the sort bar are treated as group-by columns and are not shown in the control's header. The single-sort column (after the comma) defines the column being sorted and is displayed in the control's header bar
  • If AllowGroupBy is disabled, all listed columns are treated as regular sort columns. In this case, Sorts property sorts multiple columns simultaneously, and each sorted column shows its index in the Sorted collection as a subscript next to the column caption

The AllowGroupBy property determines whether the control supports grouping by columns or only sorting. The SortBarVisible property controls the visibility of the sort bar in the control.

Type:
  • string
Example
The following statements are equivalents:

 oPivot.Columns.SetSorts("1:A 2:D, 0:A"), sorts multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A"
 oPivot.Columns.Sorts = "1:A 2:D, 0:A", sorts multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A"

where oPivot is an object of Pivot type

 "1:A 2:D, 0:A" {string}, sorts multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A"
 "0:D" {string}, sorts or groups the column at index 0 in descending order
Sorts

(readonly) VisibleCount :number

The VisibleCount property returns the number of visible-columns (columns with 'visible' property set to true). The VisibleCount property is equivalent of GetVisibleCount() method. The VisibleItem method gets the visible-column at giving position (for instance, a column with 'visible' property on false is ignored). The Count property returns the total number of columns within the collection, regardless of their visibility. The Visible property of Column object indicates whether the column is visible or hidden.
Type:
  • number
Since:
  • 5.1
Example
The following statements are equivalents:
 
 oPivot.Columns.GetVisibleCount(), returns the number of visible-columns
 oPivot.Columns.VisibleCount, returns the number of visible-columns
 
where oPivot is an object of Pivot type
VisibleCount

Methods

Add(oColumnOptsopt) → {Column}

The Add() method creates and adds a new column into the control. The new column is added as the last column of the collection. The Add() method accepts either a string or an object of ColumnOptions type as parameter. If a string is provided, it specifies the column's caption. If an object of ColumnOptions type is given, it specifies options to create the new column, such as caption, width, allowSizing and so on. The onaddcolumn event of the control is fired once the column is created and added to the collection, so you can use this event to set additional properties of the column, such as filter or image properties. The ExpandColumns property of the column is set to null by default, so the column is not expandable. You can set the ExpandColumns property to make the column expandable, and specify which columns are expanded when the column is expanded.
Parameters:
Name Type Attributes Description
oColumnOpts object <optional>
 Specifies the options to create the new column as an object of ColumnOptions type. If no object is provided, it specifies the column's caption.
Returns:
Returns the newly created column, as an object of Column type
Type
Column
Example
oPivot.Columns.Add(), adds a new column with no caption
oPivot.Columns.Add("&lt;b&gt;Info&lt;/b&gt; Col"), adds a new column
oPivot.Columns.Add({caption:"&lt;b&gt;Info&lt;/b&gt; Col", width: 64, allowSizing: false}), adds a new non-resizable column of specified width
oPivot.EnsureVisibleClient(oPivot.Columns.Add({caption:"&lt;b&gt;Info&lt;/b&gt; Col", width: 64, allowSizing: false})), adds a new non-resizable column of specified width, and ensures that the column fits the control's client area
Add

Clear()

The Clear() method removes all columns of the control and inits the control's scroll-bars. The Clear() method removes all columns and items of the control. The Remove() method removes a column from the collection. The RemoveRange() method removes multiple-columns at once. The Visible property of Column object can be used to hide/show a column without removing it from the collection. The Pivot.Clear() method clears the control's data (columns, items and filter). The ClearFilter() method is called within the Clear() method to remove the control's filter as well. The Items.Clear method is used to clear all the items of the control.
Example
The following statement removes all columns of the control:

 oPivot.Columns.Clear(), removes all columns of the control

where oPivot is an object of Pivot type
Clear

Item(id) → {null|Column}

The Item() method gets the column giving its index, identifier/key/caption or reference. Use the Column(id) method to get the column based on its index or identifier/key. The feC and feCU methods (short for forEachColumn, forEachColumnUntil) enumerates the columns of the control.
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the column to request (supports negative indices as well, where -1 returns the most recently added column, -2 returns the column added just before it, and so on @since 5.1)
  • id {string}, specifies a string expression that defines the identifier/key/caption/plain-caption of the column to request
  • id {Column}, specifies the object reference to the column to request for
Returns:
Returns null(the column is not found), or an object of Column type, if the columns collection contains the giving id.
Type
null | Column
Example
The following code snippet enumerates all columns:

 for (var i = 0, l = oPivot.Columns.Count; i &lt; l; i++)
   console.log(oPivot.Columns.Item(i));

where oPivot is an object of Pivot type
Item

Items(range) → {object}

The Items() method gets a collection of columns giving its index, identifier/key/caption separated by comma character. The range parameter of the Items() method accepts either a string with identifiers/keys/captions separated by comma character, or an array of indices, identifiers/keys/captions or references. The Item() method gets a single column giving its index, identifier/key/caption or reference.
Parameters:
Name Type Description
range any The range parameter could be any of the following:
  • range {number}, indicates a numeric value that defines the index of the column to request
  • range {string}, specifies a list of index/identifier/key/caption/plain-caption, separated by comma character
  • range {Column}, specifies the object reference to the column to request for
Returns:
Returns an object of exontrol.Arr([Column]) type.
Type
object
Example
oPivot.Columns.Items("Info Col, 2, 4"), gets multiple-columns with identifier/key/caption/plain-caption "Info Col", and columns at index 2 and 4
Items

Remove(id)

The Remove() method removes a column from the collection. You can use the Clear() method to removes all columns of the control. The RemoveRange() method removes multiple-columns at once. The Remove() method calls the RemoveRange() method internally. The Visible property of Column object can be used to hide/show a column without removing it from the collection. The onremovecolumn event of the control is fired once the column is removed from the collection, so you can use this event to perform additional actions. The id parameter of the Remove() method accepts the same values as the Item() method, so you can specify which column to remove by its index, identifier/key/caption or reference.
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the column to request
  • id {string}, specifies a string expression that defines the identifier/key/caption/plain-caption of the column to request
  • id {Column}, specifies the object reference to the column to request for
Example
The following statements are equivalents:

 oPivot.Columns.Remove("Info Col"), removes the column with identifier/key/caption/plain-caption "Info Col"
 oPivot.Columns.Remove( oPivot.Columns.Item("Info Col") ), removes the column with identifier/key/caption/plain-caption "Info Col"
 oPivot.Columns.Remove(2), removes the column at index 2
 oPivot.Columns(0).Remove(), removes the first column of the control

where oPivot is an object of Pivot type
Remove

RemoveRange(range)

The RemoveRange() method removes multiple-columns at once. The Remove() method calls the RemoveRange() method internally. The Visible property of Column object can be used to hide/show a column without removing it from the collection. The Clear() method removes all columns of the control.
Parameters:
Name Type Description
range any Indicates a column, an array [{Column}], or exontrol.Arr.
Example
oPivot.Columns.RemoveRange( [ oPivot.Columns.Item("Info Col"), oPivot.Columns.Item(2), oPivot.Columns.Item(4) ] ), removes multiple-columns with identifier/key/caption/plain-caption "Info Col", and columns at index 2 and 4
RemoveRange

VisibleItem(position) → {Column}

The VisibleItem() method gets the visible-column at giving position (for instance, a column with 'visible' property on false is ignored). The Item(index) method gets the column by its index within the collection, regardless of its visibility. The Visible property of Column object indicates whether the column is visible or hidden.
Parameters:
Name Type Description
position number Specifies the position of the visible-column to request (0-based index). It supports negative indices as well, where -1 returns the last visible-column, -2 returns the visible-column just before it, and so on.
Since:
  • 5.1
Returns:
Returns an object of Column type that represents the visible-column at the specified position
Type
Column
Example
oPivot.Columns.VisibleItem(0) {Column}, gets the first visible-column
 oPivot.Columns.VisibleItem(-1) {Column}, gets the last visible-column

The following code snippet enumerates all visible-columns:

 for (var i = 0, l = oPivot.Columns.VisibleCount; i &lt; l; i++)
   console.log(oPivot.Columns.VisibleItem(i));
 
where oPivot is an object of Pivot type
VisibleItem