Skip to content

Commit a08a3e3

Browse files
mportugamportuga
authored
Merge pull request #5612 from StrangelyTyped/gridconstants-docs
docs(core): documented core uiGridConstants entries
2 parents 7c11c95 + d9f1c31 commit a08a3e3

File tree

4 files changed

+139
-17
lines changed

4 files changed

+139
-17
lines changed

‎src/js/core/constants.js

+112-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
(function () {
22
'use strict';
3+
4+
/**
5+
* @ngdoc object
6+
* @name ui.grid.service:uiGridConstants
7+
* @description Constants for use across many grid features
8+
*
9+
*/
10+
11+
312
angular.module('ui.grid').constant('uiGridConstants', {
413
LOG_DEBUG_MESSAGES: true,
514
LOG_WARN_MESSAGES: true,
@@ -62,8 +71,52 @@
6271
F11: 122,
6372
F12: 123
6473
},
74+
/**
75+
* @ngdoc object
76+
* @name ASC
77+
* @propertyOf ui.grid.service:uiGridConstants
78+
* @description Used in {@link ui.grid.class:GridOptions.columnDef#properties_sort columnDef.sort} and
79+
* {@link ui.grid.class:GridOptions.columnDef#properties_sortDirectionCycle columnDef.sortDirectionCycle}
80+
* to configure the sorting direction of the column
81+
*/
6582
ASC: 'asc',
83+
/**
84+
* @ngdoc object
85+
* @name DESC
86+
* @propertyOf ui.grid.service:uiGridConstants
87+
* @description Used in {@link ui.grid.class:GridOptions.columnDef#properties_sort columnDef.sort} and
88+
* {@link ui.grid.class:GridOptions.columnDef#properties_sortDirectionCycle columnDef.sortDirectionCycle}
89+
* to configure the sorting direction of the column
90+
*/
6691
DESC: 'desc',
92+
93+
94+
/**
95+
* @ngdoc object
96+
* @name filter
97+
* @propertyOf ui.grid.service:uiGridConstants
98+
* @description Used in {@link ui.grid.class:GridOptions.columnDef#properties_filter columnDef.filter}
99+
* to configure filtering on the column
100+
*
101+
* `SELECT` and `INPUT` are used with the `type` property of the filter, the rest are used to specify
102+
* one of the built-in conditions.
103+
*
104+
* Available `condition` options are:
105+
* - `uiGridConstants.filter.STARTS_WITH`
106+
* - `uiGridConstants.filter.ENDS_WITH`
107+
* - `uiGridConstants.filter.CONTAINS`
108+
* - `uiGridConstants.filter.GREATER_THAN`
109+
* - `uiGridConstants.filter.GREATER_THAN_OR_EQUAL`
110+
* - `uiGridConstants.filter.LESS_THAN`
111+
* - `uiGridConstants.filter.LESS_THAN_OR_EQUAL`
112+
* - `uiGridConstants.filter.NOT_EQUAL`
113+
* - `uiGridConstants.filter.STARTS_WITH`
114+
*
115+
*
116+
* Available `type` options are:
117+
* - `uiGridConstants.filter.SELECT` - use a dropdown box for the cell header filter field
118+
* - `uiGridConstants.filter.INPUT` - use a text box for the cell header filter field
119+
*/
67120
filter: {
68121
STARTS_WITH: 2,
69122
ENDS_WITH: 4,
@@ -78,6 +131,20 @@
78131
INPUT: 'input'
79132
},
80133

134+
/**
135+
* @ngdoc object
136+
* @name aggregationTypes
137+
* @propertyOf ui.grid.service:uiGridConstants
138+
* @description Used in {@link ui.grid.class:GridOptions.columnDef#properties_aggregationType columnDef.aggregationType}
139+
* to specify the type of built-in aggregation the column should use.
140+
*
141+
* Available options are:
142+
* - `uiGridConstants.aggregationTypes.sum` - add the values in this column to produce the aggregated value
143+
* - `uiGridConstants.aggregationTypes.count` - count the number of rows to produce the aggregated value
144+
* - `uiGridConstants.aggregationTypes.avg` - average the values in this column to produce the aggregated value
145+
* - `uiGridConstants.aggregationTypes.min` - use the minimum value in this column as the aggregated value
146+
* - `uiGridConstants.aggregationTypes.max` - use the maximum value in this column as the aggregated value
147+
*/
81148
aggregationTypes: {
82149
sum: 2,
83150
count: 4,
@@ -89,6 +156,20 @@
89156
// TODO(c0bra): Create full list of these somehow. NOTE: do any allow a space before or after them?
90157
CURRENCY_SYMBOLS: ['ƒ', '$', '£', '$', '¤', '¥', '៛', '₩', '₱', '฿', '₫'],
91158

159+
/**
160+
* @ngdoc object
161+
* @name scrollDirection
162+
* @propertyOf ui.grid.service:uiGridConstants
163+
* @description Set on {@link ui.grid.class:Grid#properties_scrollDirection Grid.scrollDirection},
164+
* to indicate the direction the grid is currently scrolling in
165+
*
166+
* Available options are:
167+
* - `uiGridConstants.scrollDirection.UP` - set when the grid is scrolling up
168+
* - `uiGridConstants.scrollDirection.DOWN` - set when the grid is scrolling down
169+
* - `uiGridConstants.scrollDirection.LEFT` - set when the grid is scrolling left
170+
* - `uiGridConstants.scrollDirection.RIGHT` - set when the grid is scrolling right
171+
* - `uiGridConstants.scrollDirection.NONE` - set when the grid is not scrolling, this is the default
172+
*/
92173
scrollDirection: {
93174
UP: 'up',
94175
DOWN: 'down',
@@ -98,18 +179,48 @@
98179

99180
},
100181

182+
/**
183+
* @ngdoc object
184+
* @name dataChange
185+
* @propertyOf ui.grid.service:uiGridConstants
186+
* @description Used with {@link ui.grid.core.api:PublicApi#methods_notifyDataChange PublicApi.notifyDataChange},
187+
* {@link ui.grid.class:Grid#methods_callDataChangeCallbacks Grid.callDataChangeCallbacks},
188+
* and {@link ui.grid.class:Grid#methods_registerDataChangeCallback Grid.registerDataChangeCallback}
189+
* to specify the type of the event(s).
190+
*
191+
* Available options are:
192+
* - `uiGridConstants.dataChange.ALL` - listeners fired on any of these events, fires listeners on all events.
193+
* - `uiGridConstants.dataChange.EDIT` - fired when the data in a cell is edited
194+
* - `uiGridConstants.dataChange.ROW` - fired when a row is added or removed
195+
* - `uiGridConstants.dataChange.COLUMN` - fired when the column definitions are modified
196+
* - `uiGridConstants.dataChange.OPTIONS` - fired when the grid options are modified
197+
*/
101198
dataChange: {
102199
ALL: 'all',
103200
EDIT: 'edit',
104201
ROW: 'row',
105202
COLUMN: 'column',
106203
OPTIONS: 'options'
107204
},
205+
206+
/**
207+
* @ngdoc object
208+
* @name scrollbars
209+
* @propertyOf ui.grid.service:uiGridConstants
210+
* @description Used with {@link ui.grid.class:GridOptions#properties_enableHorizontalScrollbar GridOptions.enableHorizontalScrollbar}
211+
* and {@link ui.grid.class:GridOptions#properties_enableVerticalScrollbar GridOptions.enableVerticalScrollbar}
212+
* to specify the scrollbar policy for that direction.
213+
*
214+
* Available options are:
215+
* - `uiGridConstants.scrollbars.NEVER` - never show scrollbars in this direction
216+
* - `uiGridConstants.scrollbars.ALWAYS` - always show scrollbars in this direction
217+
*/
218+
108219
scrollbars: {
109220
NEVER: 0,
110221
ALWAYS: 1
111222
//WHEN_NEEDED: 2
112223
}
113224
});
114225

115-
})();
226+
})();

‎src/js/core/factories/Grid.js

+10-8
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,9 @@ angular.module('ui.grid')
121121
* @ngdoc property
122122
* @name scrollDirection
123123
* @propertyOf ui.grid.class:Grid
124-
* @description set one of the uiGridConstants.scrollDirection values (UP, DOWN, LEFT, RIGHT, NONE), which tells
125-
* us which direction we are scrolling. Set to NONE via debounced method
124+
* @description set one of the {@link ui.grid.service:uiGridConstants#properties_scrollDirection uiGridConstants.scrollDirection}
125+
* values (UP, DOWN, LEFT, RIGHT, NONE), which tells us which direction we are scrolling.
126+
* Set to NONE via debounced method
126127
*/
127128
self.scrollDirection = uiGridConstants.scrollDirection.NONE;
128129

@@ -423,8 +424,8 @@ angular.module('ui.grid')
423424
* and you'd like cell classes to be re-evaluated, or changed config within
424425
* the columnDef and you'd like headerCellClasses to be re-evaluated.
425426
* @param {string} type one of the
426-
* uiGridConstants.dataChange values (ALL, ROW, EDIT, COLUMN), which tells
427-
* us which refreshes to fire.
427+
* {@link ui.grid.service:uiGridConstants#properties_dataChange uiGridConstants.dataChange}
428+
* values (ALL, ROW, EDIT, COLUMN), which tells us which refreshes to fire.
428429
*
429430
*/
430431
self.api.registerMethod( 'core', 'notifyDataChange', this.notifyDataChange );
@@ -556,8 +557,8 @@ angular.module('ui.grid')
556557
*
557558
* @param {function(grid)} callback function to be called
558559
* @param {array} types the types of data change you want to be informed of. Values from
559-
* the uiGridConstants.dataChange values ( ALL, EDIT, ROW, COLUMN, OPTIONS ). Optional and defaults to
560-
* ALL
560+
* the {@link ui.grid.service:uiGridConstants#properties_dataChange uiGridConstants.dataChange}
561+
* values ( ALL, EDIT, ROW, COLUMN, OPTIONS ). Optional and defaults to ALL
561562
* @returns {function} deregister function - a function that can be called to deregister this callback
562563
*/
563564
Grid.prototype.registerDataChangeCallback = function registerDataChangeCallback(callback, types, _this) {
@@ -584,8 +585,9 @@ angular.module('ui.grid')
584585
* @description Calls the callbacks based on the type of data change that
585586
* has occurred. Always calls the ALL callbacks, calls the ROW, EDIT, COLUMN and OPTIONS callbacks if the
586587
* event type is matching, or if the type is ALL.
587-
* @param {number} type the type of event that occurred - one of the
588-
* uiGridConstants.dataChange values (ALL, ROW, EDIT, COLUMN, OPTIONS)
588+
* @param {string} type the type of event that occurred - one of the
589+
* {@link ui.grid.service:uiGridConstants#properties_dataChange uiGridConstants.dataChange}
590+
* values (ALL, ROW, EDIT, COLUMN, OPTIONS)
589591
*/
590592
Grid.prototype.callDataChangeCallbacks = function callDataChangeCallbacks(type, options) {
591593
angular.forEach( this.dataChangeCallbacks, function( callback, uid ){

‎src/js/core/factories/GridColumn.js

+13-6
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,8 @@ angular.module('ui.grid')
7575
* @name filter
7676
* @propertyOf ui.grid.class:GridColumn
7777
* @description Filter on this column.
78+
*
79+
* Available built-in conditions and types are listed under {@link jui.grid.service:uiGridConstants#properties_filter uiGridOptions.filter}
7880
* @example
7981
* <pre>{ term: 'text', condition: uiGridConstants.filter.STARTS_WITH, placeholder: 'type to filter...', ariaLabel: 'Filter for text', flags: { caseSensitive: false }, type: uiGridConstants.filter.SELECT, [ { value: 1, label: 'male' }, { value: 2, label: 'female' } ] }</pre>
8082
*
@@ -110,7 +112,9 @@ angular.module('ui.grid')
110112
* @name aggregationType
111113
* @propertyOf ui.grid.class:GridOptions.columnDef
112114
* @description The aggregation that you'd like to show in the columnFooter for this
113-
* column. Valid values are in uiGridConstants, and currently include `uiGridConstants.aggregationTypes.count`,
115+
* column. Valid values are in
116+
* {@link ui.grid.service:uiGridConstants#properties_aggregationTypes uiGridConstants.aggregationTypes},
117+
* and currently include `uiGridConstants.aggregationTypes.count`,
114118
* `uiGridConstants.aggregationTypes.sum`, `uiGridConstants.aggregationTypes.avg`, `uiGridConstants.aggregationTypes.min`,
115119
* `uiGridConstants.aggregationTypes.max`.
116120
*
@@ -278,7 +282,8 @@ angular.module('ui.grid')
278282
* @propertyOf ui.grid.class:GridOptions.columnDef
279283
* @description An object of sort information, attributes are:
280284
*
281-
* - direction: values are uiGridConstants.ASC or uiGridConstants.DESC
285+
* - direction: values are {@link ui.grid.service:uiGridConstants#properties_ASC uiGridConstants.ASC}
286+
* or {@link ui.grid.service:uiGridConstants#properties_DESC uiGridConstants.DESC}
282287
* - ignoreSort: if set to true this sort is ignored (used by tree to manipulate the sort functionality)
283288
* - priority: says what order to sort the columns in (lower priority gets sorted first).
284289
* @example
@@ -647,8 +652,8 @@ angular.module('ui.grid')
647652
* @ngdoc property
648653
* @name sortDirectionCycle
649654
* @propertyOf ui.grid.class:GridOptions.columnDef
650-
* @description (optional) An array of sort directions, specifying the order that they
651-
* should cycle through as the user repeatedly clicks on the column heading.
655+
* @description (optional) An array of {@link ui.grid.service:uiGridConstants#properties_ASC sort directions},
656+
* specifying the order that they should cycle through as the user repeatedly clicks on the column heading.
652657
* The default is `[null, uiGridConstants.ASC, uiGridConstants.DESC]`. Null
653658
* refers to the unsorted state. This does not affect the initial sort
654659
* direction; use the {@link ui.grid.class:GridOptions.columnDef#sort sort}
@@ -726,7 +731,8 @@ angular.module('ui.grid')
726731
* A filter consists of a condition, a term, and a placeholder:
727732
*
728733
* - condition defines how rows are chosen as matching the filter term. This can be set to
729-
* one of the constants in uiGridConstants.filter, or you can supply a custom filter function
734+
* one of the constants in {@link ui.grid.service:uiGridConstants#properties_filter uiGridConstants.filter},
735+
* or you can supply a custom filter function
730736
* that gets passed the following arguments: [searchTerm, cellValue, row, column].
731737
* - term: If set, the filter field will be pre-populated
732738
* with this value.
@@ -736,7 +742,8 @@ angular.module('ui.grid')
736742
* your custom function doesn't require a term (so it can run even when the term is null)
737743
* - flags: only flag currently available is `caseSensitive`, set to false if you don't want
738744
* case sensitive matching
739-
* - type: defaults to uiGridConstants.filter.INPUT, which gives a text box. If set to uiGridConstants.filter.SELECT
745+
* - type: defaults to {@link ui.grid.service:uiGridConstants#properties_filter uiGridConstants.filter.INPUT},
746+
* which gives a text box. If set to {@link ui.grid.service:uiGridConstants#properties_filter uiGridConstants.filter.SELECT}
740747
* then a select box will be shown with options selectOptions
741748
* - selectOptions: options in the format `[ { value: 1, label: 'male' }]`. No i18n filter is provided, you need
742749
* to perform the i18n on the values before you provide them

‎src/js/core/factories/GridOptions.js

+4-2
Original file line numberDiff line numberDiff line change
@@ -383,7 +383,8 @@ angular.module('ui.grid')
383383
* @ngdoc boolean
384384
* @name enableVerticalScrollbar
385385
* @propertyOf ui.grid.class:GridOptions
386-
* @description uiGridConstants.scrollbars.ALWAYS by default. This settings controls the vertical scrollbar for the grid.
386+
* @description {@link ui.grid.service:uiGridConstants#properties_scrollbars uiGridConstants.scrollbars.ALWAYS} by default.
387+
* This settings controls the vertical scrollbar for the grid.
387388
* Supported values: uiGridConstants.scrollbars.ALWAYS, uiGridConstants.scrollbars.NEVER
388389
*/
389390
baseOptions.enableVerticalScrollbar = typeof(baseOptions.enableVerticalScrollbar) !== "undefined" ? baseOptions.enableVerticalScrollbar : uiGridConstants.scrollbars.ALWAYS;
@@ -392,7 +393,8 @@ angular.module('ui.grid')
392393
* @ngdoc boolean
393394
* @name enableHorizontalScrollbar
394395
* @propertyOf ui.grid.class:GridOptions
395-
* @description uiGridConstants.scrollbars.ALWAYS by default. This settings controls the horizontal scrollbar for the grid.
396+
* @description {@link ui.grid.service:uiGridConstants#properties_scrollbars uiGridConstants.scrollbars.ALWAYS} by default.
397+
* This settings controls the horizontal scrollbar for the grid.
396398
* Supported values: uiGridConstants.scrollbars.ALWAYS, uiGridConstants.scrollbars.NEVER
397399
*/
398400
baseOptions.enableHorizontalScrollbar = typeof(baseOptions.enableHorizontalScrollbar) !== "undefined" ? baseOptions.enableHorizontalScrollbar : uiGridConstants.scrollbars.ALWAYS;

0 commit comments

Comments
 (0)