Class LABKEY.QueryWebPart
The LABKEY.QueryWebPart simplifies the task of dynamically adding a query web part to your page. Please use this class for adding query web parts to a page instead of LABKEY.WebPart, which can be used for other types of web parts.
Additional Documentation:
- Web Part Configuration Properties
- How To Find schemaName, queryName & viewName
- LabKey JavaScript API Tutorial
- LabKey SQL Reference
Defined in: DataRegion.js.
Constructor Attributes | Constructor Name and Description |
---|---|
LABKEY.QueryWebPart(config)
Constructs a LABKEY.QueryWebPart class instance
|
Config Attributes | Config Name and Description |
---|---|
An array of aggregate definitions.
|
|
If the button bar is showing, whether or not it should be include a button
to let the user choose a different query.
|
|
If the button bar is showing, whether or not it should be include a button
to let the user choose a different view.
|
|
A CSS style class that will be added to the enclosing element for the web part.
|
|
Button bar configuration.
|
|
DEPRECATED--see config.buttonBar.position
|
|
Comma-separated list of column names to be shown in the grid, overriding
whatever might be set in a custom view.
|
|
One of the values of LABKEY.Query.containerFilter that sets the scope of this query.
|
|
The container path in which the schema and query name are defined.
|
|
The name to be used for the data region.
|
|
Specify or override the default delete URL for the table with one of the form
"/controller/action.view" or "org.labkey.package.MyController$ActionAction.class".
|
|
Specify or override the default details URL for the table with one of the form
"/controller/action.view?id=${RowId}" or "org.labkey.package.MyController$ActionAction.class?id=${RowId}"
|
|
A parameter to specify how query parse errors are returned.
|
|
A function to call if the request to retrieve the content fails.
|
|
A base set of filters to apply.
|
|
The frame style to use for the web part.
|
|
Specify or override the default bulk import URL for the table with one of the form
"/controller/importAction.view" or "org.labkey.package.MyController$ImportActionAction.class"
|
|
Specify or override the default insert URL for the table with one of the form
"/controller/insertAction.view" or "org.labkey.package.MyController$InsertActionAction.class"
|
|
The name of a browser window/tab in which to open URLs rendered in the
QueryWebPart.
|
|
The maximum number of rows to return from the server (defaults to 100).
|
|
Metadata that can be applied to the properties of the table fields.
|
|
The index of the first row to return from the server (defaults to 0).
|
|
Map of name (string)/value pairs for the values of parameters if the SQL
references underlying queries that are parameterized.
|
|
The name of the query within the schema the web part will select and display.
|
|
A set of filters to apply.
|
|
An additional sort order to use.
|
|
The element id, DOM element, or Ext element inside of which the part should be rendered.
|
|
the report id of a saved report you wish to display for the given schema and query name.
|
|
The name of the schema the web part will query.
|
|
An object to use as the callback function's scope.
|
|
Shade every other row with a light gray background color (default true).
|
|
Render the table with borders (default true).
|
|
Show a "Delete" button in the button bar (default true).
|
|
If the underlying table has a details URL, show a column that renders a [details] link (default true).
|
|
Show the export button menu in the button bar (default true).
|
|
Include filter and parameter values in the grid header, if present (default true).
|
|
If the underlying table has an import URL, show an "Import Bulk Data" button in the button bar (default true).
|
|
If the underlying table has an insert URL, show an "Insert New" button in the button bar (default true).
|
|
Show the pagination links and count (default true).
|
|
Show the total count of rows in the pagination information text (default true).
|
|
Render the select checkbox column (default undefined, meaning they will be shown if the query is updatable by the current user).
|
|
If true, show reports on the Views menu (default true).
|
|
Either 'paginated' (the default) 'selected', 'unselected', 'all', or 'none'.
|
|
Show the export to RStudio button menu in the button bar.
|
|
Render the table with a surrounding border (default true).
|
|
If the underlying table has an update URL, show a column that renders an [edit] link (default true).
|
|
Open the customize view panel after rendering.
|
|
A base sort order to use.
|
|
A SQL query that can be used instead of an existing schema name/query name combination.
|
|
A function to call after the part has been rendered.
|
|
If true, no alert will appear if there is a problem rendering the QueryWebpart.
|
|
A timeout for the AJAX call, in milliseconds.
|
|
A title for the web part.
|
|
If supplied, the title will be rendered as a hyperlink with this value as the href attribute.
|
|
Specify or override the default updateURL for the table with one of the form
"/controller/action.view?id=${RowId}" or "org.labkey.package.MyController$ActionAction.class?id=${RowId}"
|
|
the name of a saved view you wish to display for the given schema and query name.
|
Field Attributes | Field Name and Description |
---|---|
A read-only object that exposes properties representing standard buttons shown in LabKey data grids.
|
Method Attributes | Method Name and Description |
---|---|
render(renderTo)
Requests the query web part content and renders it within the element identified by the renderTo parameter.
|
Class Detail
LABKEY.QueryWebPart(config)
Constructs a LABKEY.QueryWebPart class instance
<div id='queryTestDiv1'/> <script type="text/javascript"> var qwp1 = new LABKEY.QueryWebPart({ renderTo: 'queryTestDiv1', title: 'My Query Web Part', schemaName: 'lists', queryName: 'People', buttonBarPosition: 'none', aggregates: [ {column: 'First', type: LABKEY.AggregateTypes.COUNT, label: 'Total People'}, {column: 'Age', type: LABKEY.AggregateTypes.MEAN} ], filters: [ LABKEY.Filter.create('Last', 'Flintstone') ], sort: '-Last' }); //note that you may also register for the 'render' event //instead of using the success config property. //registering for events is done using Ext event registration. //Example: qwp1.on("render", onRender); function onRender() { //...do something after the part has rendered... } /////////////////////////////////////// // Custom Button Bar Example var qwp1 = new LABKEY.QueryWebPart({ renderTo: 'queryTestDiv1', title: 'My Query Web Part', schemaName: 'lists', queryName: 'People', buttonBar: { includeStandardButtons: true, items:[ LABKEY.QueryWebPart.standardButtons.views, {text: 'Test', url: LABKEY.ActionURL.buildURL('project', 'begin')}, {text: 'Test Script', onClick: "alert('Hello World!'); return false;"}, {text: 'Test Handler', handler: onTestHandler}, {text: 'Test Menu', items: [ {text: 'Item 1', handler: onItem1Handler}, {text: 'Fly Out', items: [ {text: 'Sub Item 1', handler: onItem1Handler} ]}, '-', //separator {text: 'Item 2', handler: onItem2Handler} ]}, LABKEY.QueryWebPart.standardButtons.exportRows ]} }); function onTestHandler(dataRegion) { alert("onTestHandler called!"); return false; } function onItem1Handler(dataRegion) { alert("onItem1Handler called!"); } function onItem2Handler(dataRegion) { alert("onItem2Handler called!"); } </script>
- Parameters:
- {Object} config
- A configuration object with the following possible properties:
Config Detail
{Array}
config.aggregates
An array of aggregate definitions. The objects in this array should have the properties:
- column: The name of the column to be aggregated.
- type: The aggregate type (see LABKEY.AggregateTypes)
- label: Optional label used when rendering the aggregate row.
{boolean}
config.allowChooseQuery
If the button bar is showing, whether or not it should be include a button
to let the user choose a different query.
{boolean}
config.allowChooseView
If the button bar is showing, whether or not it should be include a button
to let the user choose a different view.
{String}
config.bodyClass
A CSS style class that will be added to the enclosing element for the web part.
Note, this may not be applied when used in conjunction with some "frame" types (e.g. 'none').
{Object}
config.buttonBar
Button bar configuration. This object may contain any of the following properties:
- position: Configures where the button bar will appear with respect to the data grid: legal values are 'top', or 'none'. Default is 'top'.
- includeStandardButtons: If true, all standard buttons not specifically mentioned in the items array will be included at the end of the button bar. Default is false.
- items: An array of button bar items. Each item may be either a reference to a standard button, or a new button configuration.
to reference standard buttons, use one of the properties on #standardButtons, or simply include a string
that matches the button's caption. To include a new button configuration, create an object with the following properties:
- text: The text you want displayed on the button (aka the caption).
- url: The URL to navigate to when the button is clicked. You may use LABKEY.ActionURL to build URLs to controller actions. Specify this or a handler function, but not both.
- handler: A reference to the JavaScript function you want called when the button is clicked.
- permission: Optional. Permission that the current user must possess to see the button. Valid options are 'READ', 'INSERT', 'UPDATE', 'DELETE', and 'ADMIN'. Default is 'READ' if permissionClass is not specified.
- permissionClass: Optional. If permission (see above) is not specified, the fully qualified Java class name of the permission that the user must possess to view the button.
- requiresSelection: A boolean value (true/false) indicating whether the button should only be enabled when data rows are checked/selected.
- items: To create a drop-down menu button, set this to an array of menu item configurations.
Each menu item configuration can specify any of the following properties:
- text: The text of the menu item.
- handler: A reference to the JavaScript function you want called when the menu item is clicked.
- icon: A url to an image to use as the menu item's icon.
- items: An array of sub-menu item configurations. Used for fly-out menus.
{String}
config.buttonBarPosition
DEPRECATED--see config.buttonBar.position
{String}
config.columns
Comma-separated list of column names to be shown in the grid, overriding
whatever might be set in a custom view.
{String}
config.containerFilter
One of the values of LABKEY.Query.containerFilter that sets the scope of this query. If not supplied, the current folder will be used.
{String}
config.containerPath
The container path in which the schema and query name are defined. If not supplied, the current container path will be used.
{String}
config.dataRegionName
The name to be used for the data region. This should be unique within
the set of query views on the page. If not supplied, a unique name is generated for you.
{String}
config.deleteURL
Specify or override the default delete URL for the table with one of the form
"/controller/action.view" or "org.labkey.package.MyController$ActionAction.class". The keys for the selected rows
will be included in the POST.
{String}
config.detailsURL
Specify or override the default details URL for the table with one of the form
"/controller/action.view?id=${RowId}" or "org.labkey.package.MyController$ActionAction.class?id=${RowId}"
{String}
config.errorType
A parameter to specify how query parse errors are returned. (default 'html'). Valid
values are either 'html' or 'json'. If 'html' is specified the error will be rendered to an HTML view, if 'json' is specified
the errors will be returned to the callback handlers as an array of objects named 'parseErrors' with the following properties:
- msg: The error message.
- line: The line number the error occurred at (optional).
- col: The column number the error occurred at (optional).
- errorStr: The line from the source query that caused the error (optional).
{Function}
config.failure
A function to call if the request to retrieve the content fails. It will be passed three arguments:
- json: JSON object containing the exception.
- response: The XMLHttpRequest object containing the response data.
- options: The parameter to the request call.
{Array}
config.filters
A base set of filters to apply. This should be an array of LABKEY.Filter objects
each of which is created using the LABKEY.Filter.create method. These filters cannot be removed by the user
interacting with the UI.
For compatibility with the LABKEY.Query object, you may also specify base filters using config.filterArray.
{String}
config.frame
The frame style to use for the web part. This may be one of the following:
'div', 'portal', 'none', 'dialog', 'title', 'left-nav'.
{String}
config.importURL
Specify or override the default bulk import URL for the table with one of the form
"/controller/importAction.view" or "org.labkey.package.MyController$ImportActionAction.class"
{String}
config.insertURL
Specify or override the default insert URL for the table with one of the form
"/controller/insertAction.view" or "org.labkey.package.MyController$InsertActionAction.class"
{String}
config.linkTarget
The name of a browser window/tab in which to open URLs rendered in the
QueryWebPart. If not supplied, links will generally be opened in the same browser window/tab where the QueryWebPart.
{Integer}
config.maxRows
The maximum number of rows to return from the server (defaults to 100).
If you want to return all possible rows, set this config property to -1.
{Object}
config.metadata
Metadata that can be applied to the properties of the table fields. Currently, this option is only
available if the query has been specified through the config.sql option. For full documentation on
available properties, see LabKey XML Schema Reference.
This object may contain the following properties:
- type: The type of metadata being specified. Currently, only 'xml' is supported.
- value: The metadata XML value as a string. For example:
'<tables xmlns="http://labkey.org/data/xml"><table tableName="Announcement" tableDbType="NOT_IN_DB"><columns><column columnName="Title"><columnTitle>Custom Title</columnTitle></column></columns></table></tables>'
{Integer}
config.offset
The index of the first row to return from the server (defaults to 0).
Use this along with the maxRows config property to request pages of data.
{Object}
config.parameters
Map of name (string)/value pairs for the values of parameters if the SQL
references underlying queries that are parameterized. For example, the following passes two parameters to the query: {'Gender': 'M', 'CD4': '400'}.
The parameters are written to the request URL as follows: query.param.Gender=M&query.param.CD4=400. For details on parameterized SQL queries, see
Parameterized SQL Queries.
{String}
config.queryName
The name of the query within the schema the web part will select and display.
{Array}
config.removeableFilters
A set of filters to apply. This should be an array of LABKEY.Filter objects
each of which is created using the LABKEY.Filter.create method. These filters can be modified or removed by the user
interacting with the UI.
{String}
config.removeableSort
An additional sort order to use. This is a comma-separated list of column names, each of
which may have a - prefix to indicate a descending sort. It will be treated as the first sort, before any that the user
has defined in a custom view or through interacting with the grid column headers.
{Mixed}
config.renderTo
The element id, DOM element, or Ext element inside of which the part should be rendered. This is typically a <div>.
If not supplied in the configuration, you must call the render() method to render the part into the page.
{String}
config.reportId
the report id of a saved report you wish to display for the given schema and query name.
{String}
config.schemaName
The name of the schema the web part will query.
{Object}
config.scope
An object to use as the callback function's scope. Defaults to this.
{boolean}
config.shadeAlternatingRows
Shade every other row with a light gray background color (default true).
{boolean}
config.showBorders
Render the table with borders (default true).
{boolean}
config.showDeleteButton
Show a "Delete" button in the button bar (default true).
{boolean}
config.showDetailsColumn
If the underlying table has a details URL, show a column that renders a [details] link (default true). If true, the record selectors will be included regardless of the 'showRecordSelectors' config option.
{boolean}
config.showExportButtons
Show the export button menu in the button bar (default true).
{boolean}
config.showFilterDescription
Include filter and parameter values in the grid header, if present (default true).
{boolean}
config.showImportDataButton
If the underlying table has an import URL, show an "Import Bulk Data" button in the button bar (default true).
{boolean}
config.showInsertNewButton
If the underlying table has an insert URL, show an "Insert New" button in the button bar (default true).
{boolean}
config.showPagination
Show the pagination links and count (default true).
{boolean}
config.showPaginationCount
Show the total count of rows in the pagination information text (default true).
{boolean}
config.showRecordSelectors
Render the select checkbox column (default undefined, meaning they will be shown if the query is updatable by the current user).
If 'showDeleteButton' is true, the checkboxes will be included regardless of the 'showRecordSelectors' config option.
{boolean}
config.showReports
If true, show reports on the Views menu (default true).
{String}
config.showRows
Either 'paginated' (the default) 'selected', 'unselected', 'all', or 'none'.
When 'paginated', the maxRows and offset parameters can be used to page through the query's result set rows.
When 'selected' or 'unselected' the set of rows selected or unselected by the user in the grid view will be returned.
You can programmatically get and set the selection using the LABKEY.DataRegion.setSelected APIs.
Setting
config.maxRows
to -1 is the same as 'all'
and setting config.maxRows
to 0 is the same as 'none'.
{boolean}
config.showRStudioButton
Show the export to RStudio button menu in the button bar. Requires export button to work. (default false).
{boolean}
config.showSurroundingBorder
Render the table with a surrounding border (default true).
{boolean}
config.showUpdateColumn
If the underlying table has an update URL, show a column that renders an [edit] link (default true).
{String}
config.showViewPanel
Open the customize view panel after rendering. The value of this option can be "true" or one of "ColumnsTab", "FilterTab", or "SortTab".
{String}
config.sort
A base sort order to use. This is a comma-separated list of column names, each of
which may have a - prefix to indicate a descending sort. It will be treated as the final sort, after any that the user
has defined in a custom view or through interacting with the grid column headers.
{String}
config.sql
A SQL query that can be used instead of an existing schema name/query name combination.
{Function}
config.success
A function to call after the part has been rendered. It will be passed two arguments:
- dataRegion: the LABKEY.DataRegion object representing the rendered QueryWebPart
- request: the XMLHTTPRequest that was issued to the server
{boolean}
config.suppressRenderErrors
If true, no alert will appear if there is a problem rendering the QueryWebpart. This is most often encountered if page configuration changes between the time when a request was made and the content loads. Defaults to false.
{int}
config.timeout
A timeout for the AJAX call, in milliseconds. Default is 30000 (30 seconds).
{String}
config.title
A title for the web part. If not supplied, the query name will be used as the title.
{String}
config.titleHref
If supplied, the title will be rendered as a hyperlink with this value as the href attribute.
{String}
config.updateURL
Specify or override the default updateURL for the table with one of the form
"/controller/action.view?id=${RowId}" or "org.labkey.package.MyController$ActionAction.class?id=${RowId}"
{String}
config.viewName
the name of a saved view you wish to display for the given schema and query name.
Field Detail
{LABKEY.DataRegion}
getDataRegion
standardButtons
A read-only object that exposes properties representing standard buttons shown in LabKey data grids.
These are used in conjunction with the buttonBar configuration. The following buttons are currently defined:
- LABKEY.QueryWebPart.standardButtons.query
- LABKEY.QueryWebPart.standardButtons.views
- LABKEY.QueryWebPart.standardButtons.charts
- LABKEY.QueryWebPart.standardButtons.insertNew
- LABKEY.QueryWebPart.standardButtons.deleteRows
- LABKEY.QueryWebPart.standardButtons.exportRows
- LABKEY.QueryWebPart.standardButtons.print
Method Detail
render(renderTo)
Requests the query web part content and renders it within the element identified by the renderTo parameter.
Note that you do not need to call this method explicitly if you specify a renderTo property on the config object
handed to the class constructor. If you do not specify renderTo in the config, then you must call this method
passing the id of the element in which you want the part rendered
- Parameters:
- renderTo
- The id of the element in which you want the part rendered.