query-operators {shinyQueryBuilder} | R Documentation |
Configure available user interface operators
Description
Configure available user interface operators
Usage
mapOperator(
name,
apply_to,
optgroup = "basic",
nb_inputs = 1,
multiple = FALSE,
.queryBuilderConfig = queryBuilder::queryBuilderConfig
)
listMappedOperators(
r_class,
print = TRUE,
.queryBuilderConfig = queryBuilder::queryBuilderConfig
)
Arguments
name |
Name of the operator to be mapped. |
apply_to |
Precise what field types (classes) should the operator be available to.
When |
optgroup |
Character string ("basic" default). Operators with the same 'optgroup' will be presented within a separate group in the operators dropdown. |
nb_inputs |
Integer. The number of inputs displayed. See 'Details' for more information. |
multiple |
Logical. Inform the builder if operator can accept multiple values for associated inputs. In order to enable multiple values for specific input, set 'multiple = TRUE' when creating queryFilters. |
.queryBuilderConfig |
R6 object of class 'queryBuilderConfig' storing queryOperators. See query-operator. |
r_class |
Optional R class to list operators assigned to it. When skipped all the mapped operators will be summed up. |
print |
Should the operators summary be printed? |
Details
When configuring a single query rule, user needs to precise three values in 'queryBuilderInput' interface:
1. field - Name of the field that can be interpreted as a filtered column name. Selected with dropdown.
2. operator - Name of the operator to be applied to the field. Selected with dropdown.
3. operator value(s) - Value(s) that narrows down the operator definition. Depending on the chosen operator, such input can be take through various kind of **input controllers**.
More detailed configuration for operators linked to specific fields as long as **input controllers** for taking operator values should be set with queryFilter.
mapOperator
is responsible to establish connection between user interface operators
and queryOperator, that are responsible to convert user input to a valid R-expression.
The provided configuration allows to shape what **input controllers** should be used to allow users providing
operators' value(s).
Parameter 'multiple' precises whether queryBuilderInput should allow to provide multiple values for each input controller. When input controller accepts more than one value and user provides them, in case of 'multiple = FALSE', 'queryBuilderInput' will alert about it and won't send any values to application server.
Please remember ‘multiple = TRUE', doesn’t mean the associated input controller will automatically accept multiple values, this needs to be separately set for each queryFilter, that is responsible for input controllers configuration.
Parameter 'nb_inputs' informs how many input controllers should be rendered to take operator value(s).
A good practice is to configure your operators the following way:
nb_inputs = 0
- Operator associated function doesn't require any value, e.g. 'is_null' or 'is_empty' that only require 'field' name.nb_inputs = n, multiple = FALSE
- Operator associated function requires exactly ‘n' values, e.g. 'n=2' for ’between' that requires lower and upper bound to precise it. As a result 'n' separate input controllers will be rendered, each taking a single value.nb_inputs = 1, multiple = TRUE
- Operator associated function accepts dynamic number of values, e.g. 'in'. As a result one single input controller will be rendered, and operator will allow it to have multiple values set.
Value
No return value, called for side effects.
List of operators registered within .queryBuilderConfig
.
Examples
# Set backend operator
in_closed_range <- function(field, bounds) {
field >= bounds[1] & field <= bounds[2]
}
queryBuilder::setQueryOperators(
within = queryBuilder::queryOperator(in_closed_range)
)
queryBuilder::listQueryOperators()
# Map backend operator to the user interface one
mapOperator(
name = "within",
nb_inputs = 2, # take value with 2 input controllers
multiple = FALSE, # verify if only single value per controller is set
apply_to = c("numeric", "Date", "logical") # apply operator to selected field types
)
listMappedOperators()
filters = list(
queryFilter(
"Sepal.Length", operators = c("within", "less"),
type = "numeric", values = range(iris$Sepal.Length)
),
# no operators set, means take all for "character"
queryFilter("Species", type = "character", values = levels(iris$Species))
)
ui <- shiny::fluidPage(
title = title,
queryBuilderInput(
"qb",
filters = filters
),
shiny::verbatimTextOutput("expr")
)
server <- function(input, output, session) {
output$expr <- shiny::renderPrint({
print(queryToExpr(input$qb))
})
}
if (interactive()) {
shiny::shinyApp(ui, server)
}