shinyQueryBuilder (version 0.1.0)

query-operators: 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
)

Value

No return value, called for side effects.

List of operators registered within .queryBuilderConfig.

Arguments

name

Name of the operator to be mapped.

apply_to

Precise what field types (classes) should the operator be available to. When operators is not defined for queryFilter, all of the operators matching `queryFilter` type will be available in the operators dropdown. Possible values are 'character', 'factor', 'integer', 'numeric', 'POSIXct', 'Date' and 'logical'.

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.

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)
}