Class LABKEY.DataRegion
LABKEY.DataRegion
The DataRegion class allows you to interact with LabKey grids, including querying and modifying selection state, filters, and more.
Defined in: DataRegion.js.
Constructor Attributes | Constructor Name and Description |
---|---|
LABKEY.DataRegion(config)
The DataRegion constructor is private - to get a LABKEY.DataRegion object, use LABKEY.DataRegions['dataregionname'].
|
Method Attributes | Method Name and Description |
---|---|
addAnalyticsProviderForCustomView(viewName, colFieldKey, providerName)
Add the enabled analytics provider to the custom view definition based on the column fieldKey and provider name.
|
|
addFilter(filter)
Add a filter to this Data Region.
|
|
addMessage(config, part)
Show a message in the header of this DataRegion.
|
|
changeSort(fieldKey, sortDir)
Replaces the sort on the given column, if present, or sets a brand new sort
|
|
changeView(view, urlParameters)
Change the currently selected view to the named view
|
|
Removes all filters from the DataRegion
|
|
Removes all parameters from the DataRegion
|
|
clearFilter(fieldKey)
Removes all the filters for a particular field
|
|
Clear the message box contents.
|
|
clearSelected(config)
Clear all selected items for the current DataRegion.
|
|
<static> |
LABKEY.DataRegion.clearSelected(config)
Static method to clear all selected items for a given #selectionKey.
|
clearSort(fieldKey)
Removes the sort on a specified column
|
|
Returns an Array of LABKEY.Filter instances applied when creating this DataRegion.
|
|
Get selected items on the current page of the DataRegion.
|
|
getColumn(columnIdentifier)
Looks for a column based on fieldKey, name, displayField, or caption (in that order)
|
|
getColumnAnalyticsProviders(viewName, colFieldKey, callback, callbackScope)
Get the array of selected ColumnAnalyticsProviders for the given column FieldKey in a view.
|
|
Returns the LABKEY.Query.containerFilter currently applied to the DataRegion.
|
|
getMessage(part)
|
|
getParameter(paramName)
Returns the specified parameter from the URL.
|
|
getParameters(toLowercase)
Get the parameterized query values for this query.
|
|
Returns a query config object suitable for passing into LABKEY.Query.selectRows() or other LABKEY.Query APIs.
|
|
<static> |
LABKEY.DataRegion.getSelected(config)
Static method to get all selected items for a given #selectionKey.
|
getSelected(config)
Get all selected items for this DataRegion.
|
|
Returns the number of selected rows on the current page of the DataRegion.
|
|
Returns the user LABKEY.Query.containerFilter parameter from the URL.
|
|
Returns the user filter from the URL.
|
|
Returns an Array of LABKEY.Filter instances constructed from the URL.
|
|
Returns the user sort from the URL.
|
|
hasMessage(part)
|
|
Returns true if any row is checked on the current page of the DataRegion.
|
|
Hide the ribbon panel.
|
|
Hides the customize view interface if it is visible.
|
|
hideMessage(keepContent)
If a message is currently showing, hide it and clear out its contents
|
|
Returns true if a message is currently being shown for this DataRegion.
|
|
Returns true if all rows are checked on the current page of the DataRegion and at least one row is present.
|
|
refresh()
Refreshes the grid, via AJAX region is in async mode (loaded through a QueryWebPart),
and via a page reload otherwise.
|
|
Removes all messages from this Data Region.
|
|
removeAnalyticsProviderForCustomView(viewName, colFieldKey, providerName)
Remove an enabled analytics provider from the custom view definition based on the column fieldKey and provider name.
|
|
removeColumn(viewName, colFieldKey)
Remove a column from the given DataRegion query view.
|
|
removeFilter(filter)
Remove a filter on this DataRegion.
|
|
removeMessage(part)
If a message is currently showing, remove the specified part
|
|
render(renderTo)
Allows for asynchronous rendering of the Data Region.
|
|
replaceFilter(filter, filterToReplace)
Replace a filter on this Data Region.
|
|
selectPage(checked)
Set the selection state for all checkboxes on the current page of the DataRegion.
|
|
setColumnSummaryStatistics(viewName, colFieldKey, summaryStatProviderNames)
Set the summary statistic ColumnAnalyticsProviders for the given column FieldKey in the view.
|
|
setMaxRows(newmax)
Changes the maximum number of rows that the grid will display at one time
|
|
setPageOffset(rowOffset)
Changes the current row offset for paged content
|
|
setParameters(params)
Set the parameterized query values for this query.
|
|
setSelected(config)
Add or remove items from the selection associated with the this DataRegion.
|
|
<static> |
LABKEY.DataRegion.setSelected(config)
Static method to add or remove items from the selection for a given #selectionKey.
|
showAll()
|
|
Forces the grid to show all rows, without any paging
|
|
showCustomizeView(activeTab)
Show the customize view interface.
|
|
showErrorMessage(html)
Show an error message in the header of this DataRegion.
|
|
Displays the first page of the grid
|
|
showLoadingMessage(html)
Show a message in the header of this DataRegion with a loading indicator.
|
|
showMessage(msg)
Show a message in the header of this DataRegion.
|
|
Forces the grid to do paging based on the current maximum number of rows
|
|
Forces the grid to show only rows that have been selected
|
|
showSuccessMessage(html)
Show a success message in the header of this DataRegion.
|
|
Forces the grid to show only rows that have not been selected
|
|
toggleButtonPanelHandler(panelButton)
Show a ribbon panel.
|
|
toggleSummaryStatForCustomView(viewName, colFieldKey, summaryStatName)
Add or remove a summary statistic for a given column in the DataRegion query view.
|
Event Attributes | Event Name and Description |
---|---|
Fires after hiding a visible 'Customize Grid' panel.
|
|
Fires after showing 'Customize Grid' panel.
|
|
Fires before changing grid/view/report.
|
|
Fires before clearing sort applied to grid.
|
|
Fires before change page size.
|
|
Fires before change page number.
|
|
Fires before refresh grid.
|
|
Fires before setting the parameterized query values for this query.
|
|
Fires before change sorting on the grid.
|
|
Fires when data region selection changes.
|
|
success()
Fires when data region loads successfully.
|
Class Detail
LABKEY.DataRegion(config)
The DataRegion constructor is private - to get a LABKEY.DataRegion object, use LABKEY.DataRegions['dataregionname'].
- Parameters:
- config
Method Detail
addAnalyticsProviderForCustomView(viewName, colFieldKey, providerName)
Add the enabled analytics provider to the custom view definition based on the column fieldKey and provider name.
In addition, disable the column menu item if the column is visible in the grid.
- Parameters:
- viewName
- colFieldKey
- providerName
addFilter(filter)
Add a filter to this Data Region.
- Parameters:
- {LABKEY.Filter} filter
- See:
- LABKEY.DataRegion.addFilter static method.
addMessage(config, part)
Show a message in the header of this DataRegion.
- Parameters:
- {String / Object} config
- the HTML source of the message to be shown or a config object with the following properties:
- html: {String} the HTML source of the message to be shown.
- part: {String} The part of the message area to render the message to.
- duration: {Integer} The amount of time (in milliseconds) the message will stay visible.
- hideButtonPanel: {Boolean} If true the button panel (customize view, export, etc.) will be hidden if visible.
- append: {Boolean} If true the msg is appended to any existing content for the given part.
- part
- The part of the message area to render the message to. Used to scope messages so they can be added and removed without clearing other messages.
changeSort(fieldKey, sortDir)
Replaces the sort on the given column, if present, or sets a brand new sort
- Parameters:
- {string or LABKEY.FieldKey} fieldKey
- name of the column to be sorted
- {string} sortDir Optional, Default: +
- Set to '+' for ascending or '-' for descending
changeView(view, urlParameters)
Change the currently selected view to the named view
- Parameters:
- {Object} view
- An object which contains the following properties.
- {String} view.type Optional
- the type of view, either a 'view' or a 'report'.
- {String} view.viewName Optional
- If the type is 'view', then the name of the view.
- {String} view.reportId Optional
- If the type is 'report', then the report id.
- {Object} urlParameters
- NOTE: Experimental parameter; may change without warning. A set of filter and sorts to apply as URL parameters when changing the view.
clearAllFilters()
Removes all filters from the DataRegion
clearAllParameters()
Removes all parameters from the DataRegion
clearFilter(fieldKey)
Removes all the filters for a particular field
- Parameters:
- {string|FieldKey} fieldKey
- the name of the field from which all filters should be removed
clearMessage()
Clear the message box contents.
clearSelected(config)
Clear all selected items for the current DataRegion.
- Parameters:
- config
- A configuration object with the following properties:
- {Function} config.success
- The function to be called upon success of the request.
The callback will be passed the following parameters:
- data: an object with the property 'count' of 0 to indicate an empty selection.
- response: The XMLHttpResponse object
- {Function} config.failure Optional
- The function to call upon error of the request.
The callback will be passed the following parameters:
- errorInfo: an object containing detailed error information (may be null)
- response: The XMLHttpResponse object
- {Object} config.scope Optional
- An optional scoping object for the success and error callback functions (default to this).
- {string} config.containerPath Optional
- An alternate container path. If not specified, the current container path will be used.
- See:
- LABKEY.DataRegion#selectPage
- LABKEY.DataRegion.clearSelected static method.
<static>
LABKEY.DataRegion.clearSelected(config)
Static method to clear all selected items for a given #selectionKey.
- Parameters:
- config
- A configuration object with the following properties:
- {String} config.selectionKey
- See #selectionKey.
- {Function} config.success
- The function to be called upon success of the request.
The callback will be passed the following parameters:
- data: an object with the property 'count' of 0 to indicate an empty selection.
- response: The XMLHttpResponse object
- {Function} config.failure Optional
- The function to call upon error of the request.
The callback will be passed the following parameters:
- errorInfo: an object containing detailed error information (may be null)
- response: The XMLHttpResponse object
- {Object} config.scope Optional
- An optional scoping object for the success and error callback functions (default to this).
- {string} config.containerPath Optional
- An alternate container path. If not specified, the current container path will be used.
clearSort(fieldKey)
Removes the sort on a specified column
- Parameters:
- {string or LABKEY.FieldKey} fieldKey
- name of the column
{Array}
getBaseFilters()
Returns an Array of LABKEY.Filter instances applied when creating this DataRegion. These cannot be removed through the UI.
- Returns:
- {Array} Array of LABKEY.Filter objects that represent currently applied base filters.
getChecked()
Get selected items on the current page of the DataRegion.
Note, if the region is paginated, selected items may exist on other pages.
{*}
getColumn(columnIdentifier)
Looks for a column based on fieldKey, name, displayField, or caption (in that order)
- Parameters:
- columnIdentifier
- Returns:
- {*}
getColumnAnalyticsProviders(viewName, colFieldKey, callback, callbackScope)
Get the array of selected ColumnAnalyticsProviders for the given column FieldKey in a view.
- Parameters:
- viewName
- colFieldKey
- callback
- callbackScope
{String}
getContainerFilter()
Returns the LABKEY.Query.containerFilter currently applied to the DataRegion. Defaults to LABKEY.Query.containerFilter.current.
- Returns:
- {String} The container filter currently applied to this DataRegion. Defaults to 'undefined' if a container filter is not specified by the configuration.
- See:
- LABKEY.DataRegion#getUserContainerFilter to get the containerFilter value from the URL.
{String}
getMessage(part)
- Parameters:
- part
- The part of the message area to render the message to. Used to scope messages so they can be added and removed without clearing other messages.
- Returns:
- {String} The message for 'part'. Could be undefined.
{*}
getParameter(paramName)
Returns the specified parameter from the URL. Note, this is not related specifically
to parameterized query values (e.g. setParameters()/getParameters())
- Parameters:
- {String} paramName
- Returns:
- {*}
getParameters(toLowercase)
Get the parameterized query values for this query. These parameters
are named by the query itself.
- Parameters:
- {boolean} toLowercase
- If true, all parameter names will be converted to lowercase returns params An Object of key/val pairs.
{Object}
getQueryConfig()
Returns a query config object suitable for passing into LABKEY.Query.selectRows() or other LABKEY.Query APIs.
- Returns:
- {Object} Object representing the query configuration that generated this grid.
<static>
LABKEY.DataRegion.getSelected(config)
Static method to get all selected items for a given #selectionKey.
- Parameters:
- config
- A configuration object with the following properties:
- {String} config.selectionKey
- See #selectionKey.
- {Function} config.success
- The function to be called upon success of the request.
The callback will be passed the following parameters:
- data: an object with the property 'selected' that is an array of the primary keys for the selected rows.
- response: The XMLHttpResponse object
- {Function} config.failure Optional
- The function to call upon error of the request.
The callback will be passed the following parameters:
- errorInfo: an object containing detailed error information (may be null)
- response: The XMLHttpResponse object
- {Object} config.scope Optional
- An optional scoping object for the success and error callback functions (default to this).
- {string} config.containerPath Optional
- An alternate container path. If not specified, the current container path will be used.
getSelected(config)
Get all selected items for this DataRegion.
- Parameters:
- config
- A configuration object with the following properties:
- {Function} config.success
- The function to be called upon success of the request.
The callback will be passed the following parameters:
- data: an object with the property 'selected' that is an array of the primary keys for the selected rows.
- response: The XMLHttpResponse object
- {Function} config.failure Optional
- The function to call upon error of the request.
The callback will be passed the following parameters:
- errorInfo: an object containing detailed error information (may be null)
- response: The XMLHttpResponse object
- {Object} config.scope Optional
- An optional scoping object for the success and error callback functions (default to this).
- {string} config.containerPath Optional
- An alternate container path. If not specified, the current container path will be used.
- See:
- LABKEY.DataRegion.getSelected static method.
{Integer}
getSelectionCount()
Returns the number of selected rows on the current page of the DataRegion. Selected items may exist on other pages.
- Returns:
- {Integer} the number of selected rows on the current page of the DataRegion.
- See:
- LABKEY.DataRegion#getSelected to get all selected rows.
{LABKEY.Query.containerFilter}
getUserContainerFilter()
Returns the user LABKEY.Query.containerFilter parameter from the URL.
- Returns:
- {LABKEY.Query.containerFilter} The user container filter.
{Object}
getUserFilter()
Returns the user filter from the URL. The filter is represented as an Array of objects of the form:
- fieldKey: {String} The field key of the filter.
- op: {String} The filter operator (eg. "eq" or "in")
- value: {String} Optional value to filter by.
- Deprecated:
- 12.2 Use getUserFilterArray instead
- Returns:
- {Object} Object representing the user filter.
{Array}
getUserFilterArray()
Returns an Array of LABKEY.Filter instances constructed from the URL.
- Returns:
- {Array} Array of LABKEY.Filter objects that represent currently applied filters.
{Object}
getUserSort()
Returns the user sort from the URL. The sort is represented as an Array of objects of the form:
- fieldKey: {String} The field key of the sort.
- dir: {String} The sort direction, either "+" or "-".
- Returns:
- {Object} Object representing the user sort.
{Boolean}
hasMessage(part)
- Parameters:
- part
- The part of the message area to render the message to. Used to scope messages so they can be added and removed without clearing other messages.
- Returns:
- {Boolean} true iff there is a message area for this region and it has the message keyed by 'part'.
{Boolean}
hasSelected()
Returns true if any row is checked on the current page of the DataRegion. Selected items may exist on other pages.
- Returns:
- {Boolean} true if any row is checked on the current page of the DataRegion.
- See:
- LABKEY.DataRegion#getSelected to get all selected rows.
hideButtonPanel()
Hide the ribbon panel. If visible the ribbon panel will be hidden.
hideCustomizeView()
Hides the customize view interface if it is visible.
hideMessage(keepContent)
If a message is currently showing, hide it and clear out its contents
- Parameters:
- keepContent
- If true don't remove the message area content
{Boolean}
isMessageShowing()
Returns true if a message is currently being shown for this DataRegion. Messages are shown as a header.
- Returns:
- {Boolean} true if a message is showing.
{Boolean}
isPageSelected()
Returns true if all rows are checked on the current page of the DataRegion and at least one row is present.
- Returns:
- {Boolean} true if all rows are checked on the current page of the DataRegion and at least one row is present.
- See:
- LABKEY.DataRegion#getSelected to get all selected rows.
pageFirst()
- Deprecated:
- use showFirstPage instead
refresh()
Refreshes the grid, via AJAX region is in async mode (loaded through a QueryWebPart),
and via a page reload otherwise. Can be prevented with a listener
on the 'beforerefresh'
event.
removeAllMessages()
Removes all messages from this Data Region.
removeAnalyticsProviderForCustomView(viewName, colFieldKey, providerName)
Remove an enabled analytics provider from the custom view definition based on the column fieldKey and provider name.
In addition, enable the column menu item if the column is visible in the grid.
- Parameters:
- viewName
- colFieldKey
- providerName
removeColumn(viewName, colFieldKey)
Remove a column from the given DataRegion query view.
- Parameters:
- viewName
- colFieldKey
removeFilter(filter)
Remove a filter on this DataRegion.
- Parameters:
- {LABKEY.Filter} filter
removeMessage(part)
If a message is currently showing, remove the specified part
- Parameters:
- part
render(renderTo)
Allows for asynchronous rendering of the Data Region. This region must be in "async" mode for
this to do anything.
- Parameters:
- {String} renderTo Optional
- - The element ID where to render the data region. If not given it will default to the current renderTo target is.
replaceFilter(filter, filterToReplace)
Replace a filter on this Data Region. Optionally, supply another filter to replace for cases when the filter
columns don't match exactly.
- Parameters:
- {LABKEY.Filter} filter
- {LABKEY.Filter} filterToReplace Optional
selectNone()
- Deprecated:
- use clearSelected instead
{Array}
selectPage(checked)
Set the selection state for all checkboxes on the current page of the DataRegion.
- Parameters:
- checked
- whether all of the rows on the current page should be selected or unselected
- Returns:
- {Array} Array of ids that were selected or unselected.
- See:
- LABKEY.DataRegion#setSelected to set selected items on the current page of the DataRegion.
- LABKEY.DataRegion#clearSelected to clear all selected.
setColumnSummaryStatistics(viewName, colFieldKey, summaryStatProviderNames)
Set the summary statistic ColumnAnalyticsProviders for the given column FieldKey in the view.
- Parameters:
- viewName
- colFieldKey
- summaryStatProviderNames
setMaxRows(newmax)
Changes the maximum number of rows that the grid will display at one time
- Parameters:
- newmax
- the maximum number of rows to be shown
setOffset()
- Deprecated:
- use setPageOffset instead
setPageOffset(rowOffset)
Changes the current row offset for paged content
- Parameters:
- rowOffset
- row index that should be at the top of the grid
setParameters(params)
Set the parameterized query values for this query. These parameters
are named by the query itself.
- Parameters:
- {Mixed} params
- An Object or Array of Array key/val pairs.
setSelected(config)
Add or remove items from the selection associated with the this DataRegion.
- Parameters:
- config
- A configuration object with the following properties:
- {Array} config.ids
- Array of primary key ids for each row to select/unselect.
- {Boolean} config.checked
- If true, the ids will be selected, otherwise unselected.
- {Function} config.success Optional
- The function to be called upon success of the request.
The callback will be passed the following parameters:
- data: an object with the property 'count' to indicate the updated selection count.
- response: The XMLHttpResponse object
- {Function} config.failure Optional
- The function to call upon error of the request.
The callback will be passed the following parameters:
- errorInfo: an object containing detailed error information (may be null)
- response: The XMLHttpResponse object
- {Object} config.scope Optional
- An optional scoping object for the success and error callback functions (default to this).
- {string} config.containerPath Optional
- An alternate container path. If not specified, the current container path will be used.
- See:
- LABKEY.DataRegion#getSelected to get the selected items for this DataRegion.
- LABKEY.DataRegion#clearSelected to clear all selected items for this DataRegion.
<static>
LABKEY.DataRegion.setSelected(config)
Static method to add or remove items from the selection for a given #selectionKey.
- Parameters:
- config
- A configuration object with the following properties:
- {String} config.selectionKey
- See #selectionKey.
- {Array} config.ids
- Array of primary key ids for each row to select/unselect.
- {Boolean} config.checked
- If true, the ids will be selected, otherwise unselected.
- {Function} config.success
- The function to be called upon success of the request.
The callback will be passed the following parameters:
- data: an object with the property 'count' to indicate the updated selection count.
- response: The XMLHttpResponse object
- {Function} config.failure Optional
- The function to call upon error of the request.
The callback will be passed the following parameters:
- errorInfo: an object containing detailed error information (may be null)
- response: The XMLHttpResponse object
- {Object} config.scope Optional
- An optional scoping object for the success and error callback functions (default to this).
- {string} config.containerPath Optional
- An alternate container path. If not specified, the current container path will be used.
showAll()
- Deprecated:
- use showAllRows instead
showAllRows()
Forces the grid to show all rows, without any paging
showCustomizeView(activeTab)
Show the customize view interface.
- Parameters:
- activeTab
- {[String]} Optional. One of "ColumnsTab", "FilterTab", or "SortTab". If no value is specified (or undefined), the ColumnsTab will be shown.
showErrorMessage(html)
Show an error message in the header of this DataRegion.
- Parameters:
- html
- the HTML source of the message to be shown
showFirstPage()
Displays the first page of the grid
showLoadingMessage(html)
Show a message in the header of this DataRegion with a loading indicator.
- Parameters:
- html
- the HTML source of the message to be shown
showMessage(msg)
Show a message in the header of this DataRegion.
- Parameters:
- msg
- the HTML source of the message to be shown
- Deprecated:
- use addMessage(msg, part) instead.
showPaged()
Forces the grid to do paging based on the current maximum number of rows
showSelected()
- Deprecated:
- use showSelectedRows instead
showSelectedRows()
Forces the grid to show only rows that have been selected
showSuccessMessage(html)
Show a success message in the header of this DataRegion.
- Parameters:
- html
- the HTML source of the message to be shown
showUnselected()
- Deprecated:
- use showUnselectedRows instead
showUnselectedRows()
Forces the grid to show only rows that have not been selected
toggleButtonPanelHandler(panelButton)
Show a ribbon panel.
first arg can be button on the button bar or target panel id/configuration
- Parameters:
- panelButton
toggleSummaryStatForCustomView(viewName, colFieldKey, summaryStatName)
Add or remove a summary statistic for a given column in the DataRegion query view.
- Parameters:
- viewName
- colFieldKey
- summaryStatName
Event Detail
afterpanelhide()
Fires after hiding a visible 'Customize Grid' panel.
afterpanelshow()
Fires after showing 'Customize Grid' panel.
beforechangeview()
Fires before changing grid/view/report.
beforeclearsort()
Fires before clearing sort applied to grid.
beforemaxrowschange()
Fires before change page size.
beforeoffsetchange()
Fires before change page number.
beforerefresh()
Fires before refresh grid.
beforesetparameters()
Fires before setting the parameterized query values for this query.
beforesortchange()
Fires before change sorting on the grid.
selectchange()
Fires when data region selection changes.
success()
Fires when data region loads successfully.