A builder for category filter controls.
A category filter is a picker to choose one or more between a set of defined values. Given a column of type string, this control will filter out the rows that don't match any of the picked values.
Here is an example that creates a table chart a binds a category filter to it. This allows the user to filter the data the table displays.
function doGet() {
var app = UiApp.createApplication();
var sampleData = Charts.newDataTable()
.addColumn(Charts.ColumnType.STRING, "Month")
.addColumn(Charts.ColumnType.NUMBER, "Dining")
.addColumn(Charts.ColumnType.NUMBER, "Total")
.addRow(["Jan", 60, 520])
.addRow(["Feb", 50, 430])
.addRow(["Mar", 53, 440])
.addRow(["Apr", 70, 410])
.addRow(["May", 80, 390])
.addRow(["Jun", 60, 500])
.addRow(["Jul", 100, 450])
.addRow(["Aug", 140, 431])
.addRow(["Sep", 75, 488])
.addRow(["Oct", 70, 521])
.addRow(["Nov", 58, 388])
.addRow(["Dec", 63, 400])
.build();
var chart = Charts.newTableChart()
.setDimensions(600, 500)
.build();
var categoryFilter = Charts.newCategoryFilter()
.setFilterColumnLabel("Month")
.setAllowMultiple(true)
.setSortValues(true)
.setLabelStacking(Charts.Orientation.VERTICAL)
.setCaption('Choose categories...')
.setSortValues(true)
.build();
var panel = app.createVerticalPanel().setSpacing(10);
panel.add(categoryFilter).add(chart);
var dashboard = Charts.newDashboardPanel()
.setDataTable(sampleData)
.bind(categoryFilter, chart)
.build();
dashboard.add(panel);
app.add(dashboard);
return app;
}
For more details, see the Gviz
documentation
Methods
| Method | Return type | Brief description |
|---|---|---|
build() | Control | Builds a control. |
setAllowMultiple(allowMultiple) | CategoryFilterBuilder | Sets whether multiple values can be selected, rather than just one. |
setAllowNone(allowNone) | CategoryFilterBuilder | Sets whether the user is allowed not to choose any value. |
setAllowTyping(allowTyping) | CategoryFilterBuilder | Sets whether the user is allowed to type in a text field to narrow down the list of possible choices (via an autocompleter), or not. |
setCaption(caption) | CategoryFilterBuilder | Sets the caption to display inside the value picker widget when no item is selected. |
setDataTable(tableBuilder) | CategoryFilterBuilder | Sets the data table to use for the control using a DataTableBuilder. |
setDataTable(table) | CategoryFilterBuilder | Sets the control data table, which will be the control's underlying data model. |
setFilterColumnIndex(columnIndex) | CategoryFilterBuilder | Sets the index of the data table column to filter on. |
setFilterColumnLabel(columnLabel) | CategoryFilterBuilder | Sets the label of the data table column to filter on. |
setLabel(label) | CategoryFilterBuilder | Sets the label to display next to the slider. |
setLabelSeparator(labelSeparator) | CategoryFilterBuilder | Sets a separator string appended to the label, to visually separate the label from the category picker. |
setLabelStacking(orientation) | CategoryFilterBuilder | Sets whether the label should display above (vertical stacking) or beside (horizontal stacking) the input field. |
setSelectedValuesLayout(layout) | CategoryFilterBuilder | Sets how to display selected values, when multiple selection is allowed. |
setSortValues(sortValues) | CategoryFilterBuilder | Sets whether the values to choose from should be sorted. |
setValues(values) | CategoryFilterBuilder | Sets the list of values (categories) the user can choose from. |
Detailed documentation
setAllowMultiple(allowMultiple)
Sets whether multiple values can be selected, rather than just one. The default value of this option is true (allowing multiple selection).
// Creates a category filter and disallows multiple value selection.
var builder = Charts.newCategoryFilter().setAllowMultiple(false);
Parameters
| Name | Type | Description |
|---|---|---|
allowMultiple | Boolean | if false, the user will not be able to select multiple values |
Return
CategoryFilterBuilder — this builder, useful for chaining
setAllowNone(allowNone)
Sets whether the user is allowed not to choose any value. If false the user must choose at least one value from the available ones. The default value of this option is true.
// Creates a category filter and force the user to choose at least one value.
var builder = Charts.newCategoryFilter().setAllowNone(false);
Parameters
| Name | Type | Description |
|---|---|---|
allowNone | Boolean | if false, the user must choose at least one value |
Return
CategoryFilterBuilder — this builder, useful for chaining
setAllowTyping(allowTyping)
Sets whether the user is allowed to type in a text field to narrow down the list of possible choices (via an autocompleter), or not. The default value of this option is true (allowing the user to type in values in the picker).
// Creates a category filter and disallows the user from typing in text to filter the values,
// so the user must use the drop down to pick values.
var builder = Charts.newCategoryFilter().setAllowTyping(false);
Parameters
| Name | Type | Description |
|---|---|---|
allowTyping | Boolean | if false, the user will not be allowed to type in a text field to narrow down the list of possible choices |
Return
CategoryFilterBuilder — this builder, useful for chaining
setCaption(caption)
Sets the caption to display inside the value picker widget when no item is selected.
// Creates a category filter with a caption.
var builder = Charts.newCategoryFilter().setCaption('select a value');
Parameters
| Name | Type | Description |
|---|---|---|
caption | String | the caption to display inside the value picker widget when no item is selected |
Return
CategoryFilterBuilder — this builder, useful for chaining
setDataTable(tableBuilder)
Sets the data table to use for the control using a DataTableBuilder.
This is a convenience method for setting the data table without needing to call
build().
Parameters
| Name | Type | Description |
|---|---|---|
tableBuilder | DataTableBuilder | a data table builder. A new data table will be created instantly as part of this call, so any further updates to the builder won't be reflected in the control. |
Return
CategoryFilterBuilder — this builder, useful for chaining
setDataTable(table)
Sets the control data table, which will be the control's underlying data model.
Parameters
| Name | Type | Description |
|---|---|---|
table | DataTableSource | the data table to use for the control |
Return
CategoryFilterBuilder — this builder, useful for chaining
setFilterColumnIndex(columnIndex)
Sets the index of the data table column to filter on.
The values of that column will determine whether or not each row should be filtered.
It is mandatory to set either this or the column label using
setFilterColumnLabel(columnLabel).
Parameters
| Name | Type | Description |
|---|---|---|
columnIndex | Integer | the index of the data table column the filter should operate upon |
Return
CategoryFilterBuilder — this builder, useful for chaining
setFilterColumnLabel(columnLabel)
Sets the label of the data table column to filter on.
The values of that column will determine whether or not each row should be filtered.
It is mandatory to set either this or a column index using setFilterColumnIndex(columnIndex).
Parameters
| Name | Type | Description |
|---|---|---|
columnLabel | String | the label of the column to filter on |
Return
CategoryFilterBuilder — this builder, useful for chaining
setLabel(label)
Sets the label to display next to the slider. If unspecified, the label of the column the control operates on will be used.
Parameters
| Name | Type | Description |
|---|---|---|
label | String | the label to display next to the slider |
Return
CategoryFilterBuilder — this builder, useful for chaining
setLabelSeparator(labelSeparator)
Sets a separator string appended to the label, to visually separate the label from the category picker.
Parameters
| Name | Type | Description |
|---|---|---|
labelSeparator | String | the string to use to separate the label from the category picker |
Return
CategoryFilterBuilder — this builder, useful for chaining
setLabelStacking(orientation)
Sets whether the label should display above (vertical stacking) or beside (horizontal stacking) the input field.
Parameters
| Name | Type | Description |
|---|---|---|
orientation | Orientation | the orientation of the stacking |
Return
CategoryFilterBuilder — this builder, useful for chaining
setSelectedValuesLayout(layout)
Sets how to display selected values, when multiple selection is allowed.
// Creates a category filter and sets it to display selected values below the picker.
var builder = Charts.newCategoryFilter()
.setSelectedValuesLayout(Charts.PickerValuesLayout.BELOW);
Parameters
| Name | Type | Description |
|---|---|---|
layout | PickerValuesLayout | the layout in which to display the selected values |
Return
CategoryFilterBuilder — this builder, useful for chaining
See also
setSortValues(sortValues)
Sets whether the values to choose from should be sorted.
// Creates a category filter that sorts the values.
var builder = Charts.newCategoryFilter().setSortValues(true);
Parameters
| Name | Type | Description |
|---|---|---|
sortValues | Boolean | if true, sorts the values displayed in the widget alphabetically |
Return
CategoryFilterBuilder — this builder, useful for chaining
setValues(values)
Sets the list of values (categories) the user can choose from.
// Creates a category filter with two choices.
var builder = Charts.newCategoryFilter().setValues(['choice 1','choice 2']);
Parameters
| Name | Type | Description |
|---|---|---|
values | String[] | list of values the user can choose from |
Return
CategoryFilterBuilder — this builder, useful for chaining