This section covers how to configure the Side Bar which contains Tool Panels.
Configuring the Side Bar
The side bar is configured using the grid property
sideBar. The property takes multiple
forms to allow easy configuration or more advanced configuration. The different forms
sideBar property are as follows:
|undefined||No side bar provided.|
|boolean||Set to true to display the side bar with default configuration.|
|string||Set to 'columns' or 'filters' to display side bar with just one of Columns or Filters tool panels.|
|An object of type SideBarDef (explained below) to allow detailed configuration of the side bar. Use this to configure the provided tool panels (eg pass parameters to the columns or filters panel) or to include custom tool panels.|
The default side bar contains the Columns and Filters tool panels. To use the default side bar,
set the grid property
sideBar=true. The Columns panel will be open by default
The default configuration doesn't allow customisation of the tool panels. More detailed configurations are explained below.
In the following example note the following:
- The grid property
sideBaris set to true.
- The side bar is displayed with tool panels Columns and Filters.
- The Columns panel is displayed by default.
To display just one of the provided tool panels, set either
sideBar='filters'. This will display the desired item with default configuration.
The example below demonstrates using the string configuration. Note the following:
- The grid property
sideBaris set to 'filters'.
- The side bar is displayed showing only the Filters panel.
The previous configurations are shortcuts for the full fledged configuration using a SideBarDef object.
For full control over the configuration, you must provide a
The properties of SideBarDef are as follows:
|toolPanels||A list of all the panels to place in the side bar. The panels will be displayed in provided order from top to bottom.|
|defaultToolPanel||The panel (identified by id) to open by default. If none specified, the side bar is initially displayed closed.|
|hiddenByDefault||To hide the side bar by default enable hiddenByDefault, if left blank the side bar will be shown.|
Each panel has the following properties
|id||The unique id for this panel. Used in the API and eleswhere to refer to the panel.|
|labelKey||The key used for internationalisation for displaying the label. The label is displayed in the tab button.|
|labelDefault||The default label if labelKey is missing or does not map to a valid text through internationalisation.|
|iconKey||The key of the icon to be used as a graphical aid beside the label in the side bar.|
|The tool panel component to use as the panel. The provided panels use components "agColumnsToolPanel" and "agFiltersToolPanel". To provide your own custom panel component, you reference it by name here.|
The following snippet shows configuring the tool panel using a
The snippet above is demonstrated in the following example:
The boolean and string configurations are shortcuts for more detailed configurations.
When you use a shortcut the grid replaces it with the equivalent long form of the configuration
by building the equivalent
The following code snippet shows an example of the
boolean shortcut and the equivalent
SideBarDef long form.
The following code snippet shows and example of the
string shortcut and the equivalent
SideBarDef long form.
You can also use shortcuts inside the
toolPanel.items array for specifying the Columns and Filters items.
Side Bar Customisation
If you are using the long form (providing a
SideBarDef object) then it is possible to customise.
The example below shows changing the label and icon for the columns and filters tab.
Providing Parameters to Tool Panels
Parameters are passed to tool panels via the
For example, the following code snippet sets
suppressValues: true for the
columns tool panel.
This example configures the columns tool panel. See the columns tool panel documentation for the full list of possible parameters to this tool panel.
Side Bar API
The list below details all the API methods relevant to the tool panel.
|setSideBarVisible||It will show/hide the entire side bar, including and any displaying panel and the tab buttons.|
|isSideBarVisible||Returns true if visible.|
|openToolPanel||Opens a particular tool panel. Provide the ID of the rool panel to open.|
|closeToolPanel||Closes the currently open (if any) tool panel.|
|getOpenedToolPanel||Returns the ID of the currently shown tool panel if any, otherwise null.|
|setSideBar||Resets the side bar to the provided configuration. The parameter is the same as the sideBar grid property. The side bar is re-created from scratch with the new config.|
|getSideBar||Returns the current side bar configuration. If a short cut was used, returns the detailed long form.|
The example below demonstrates different usages of the tool panel API methods. The following can be noted:
- Initially the side is not visible as
Visibility Buttons: These toggle visibility of the tool panel. Note that when you make
visible=false, the entire tool panel is hidden including the tabs. Make sure the tool panel is left visible before testing the other API features so you can see the impact.
- Open / Close Buttons: These open and close different tool panel items.
Reset: These reset the tool panel to a new configuration. Notice that shortcuts
are provided as configuration however
getToolPanel()returns back the long form.
Now that we covered the Side bar, continue to the next section to learn about the Columns Tool Panel.