-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
188 lines (146 loc) · 5.83 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
---
output: github_document
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
eval = TRUE,
echo = TRUE,
message = TRUE,
warning = TRUE,
fig.width = 8,
fig.height = 6,
dpi = 200,
fig.align = "center",
fig.path = "man/figures/README-"
)
knitr::opts_chunk$set()
library(magrittr)
library(shinyQueryBuilder)
set.seed(123)
options(tibble.width = Inf)
mtcars <- tibble::as.tibble(mtcars)
options("tibble.print_max" = 5)
options("tibble.print_min" = 5)
pkg_version <- read.dcf("DESCRIPTION", fields = "Version")[1, 1]
```
# shinyQueryBuilder
[`&color=ff69b4)](https://r-world-devs.github.io/shinyQueryBuilder/)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
## Overview
`shinyQueryBuilder` provides an input widget that allows to construct complex filtering queries in Shiny.
It's a wrapper for JS library [jQuery-QueryBuilder](https://querybuilder.js.org/).
**Note:** The component assumes usage of Bootstrap >= 5.0.
For this goal we recommend to use it with  built dashboards.
### Usage
#### Filters
Filters are responsible for defining available options for providing field-rules in the interface.
With filters you may decide what operators should be available for the field,
what possible operator-values can be chosen or even customize what kind of input controllers
should be used for that goal.
Filter configuration is performed with `queryFilter()` function:
```{r eval = FALSE}
filters <- list(
queryFilter(
id = "Species", # filter id
field = "Species", # variable name
label = "Species", # filter label
type = "character", # type/class of variable
input = "select", # input widget type
values = c("versicolor", "virginica", "setosa"), # possible filter values
operators = c("equal", "not_equal") # attached filter operators
),
queryFilter(
id = "Sepal.Length",
field = "Sepal.Length",
label = "Sepal.Length",
type = "numeric",
input = "number",
operators = c("less", "less_or_equal", "greater", "greater_or_equal")
)
)
```
In order to render the widget, pass the defined filters to `queryBuilderInput()` and place the output to the Shiny's UI object:
```{r eval = FALSE}
library(shiny)
library(bslib)
library(shinyQueryBuilder)
ui <- page_fluid(
queryBuilderInput(
"qb",
filters = filters
),
shiny::verbatimTextOutput("expr")
)
server <- function(input, output, session) {
output$expr <- renderPrint({
print(queryBuilder::queryToExpr(input$qb))
})
}
shinyApp(ui, server, options = list(launch.browser = TRUE))
```
The returned `input` object is a nested list that defines the provided query.
It can be easily converted to valid R filtering query using [queryBuilder](https://github.com/r-world-devs/queryBuilder) (`queryBuilder::queryToExpr`) - non-shiny package supporting construction of complex filtering queries.
If you want to apply the filtering expression to your data, provide it to `dplyr::filter` with `!!` operator, e.g.:
```{r eval = FALSE}
renderTable({
dplyr::filter(iris, !!queryBuilder::queryToExpr(input$qb))
})
```
### Initialize `queryBuilderInput` state with `queryRule`(s)
As shown above, the returned widgets value is interpreted by [queryBuilder](https://github.com/r-world-devs/queryBuilder) package.
The package itself allows to construct filtering query with the usage of **rules** and **groups** - definitions for single field filtering operation and the way for combining them into a single filtering query.
The following state:
is configured by `queryBuilder` with:
```{r}
library(queryBuilder)
query_def <- queryGroup(
condition = "OR",
queryGroup(
condition = "AND",
queryRule("Species", "not_equal", "versicolor"),
queryRule("Sepal.Length", "less", 10)
),
queryRule("Species", "equal", "setosa")
)
queryToExpr(query_def)
```
In order to initialize `queryBuilderInput` with the above state, simply pass such query to `rules` argument:
```{r eval = FALSE}
library(shiny)
library(bslib)
library(shinyQueryBuilder)
ui <- page_fluid(
queryBuilderInput(
"qb",
filters = filters,
rules = query_def
),
shiny::verbatimTextOutput("expr")
)
server <- function(input, output, session) {
output$expr <- renderPrint({
print(queryBuilder::queryToExpr(input$qb))
})
}
shinyApp(ui, server, options = list(launch.browser = TRUE))
```
The initiated state can be then customized by user when needed.
See more examples at [examples](https://github.com/r-world-devs/shinyQueryBuilder/tree/master/examples).
## Installation
```{r, eval = FALSE}
# CRAN version
install.packages("shinyQueryBuilder")
# Latest development version
remotes::install_github("https://github.com/r-world-devs/shinyQueryBuilder")
```
## Acknowledgement
Special thanks to [Kamil Wais](mailto:[email protected]), [Adam Foryś](mailto:[email protected]), [Maciej Banaś](mailto:[email protected]),[Karolina Marcinkowska](mailto:[email protected]) and [Kamil Koziej](mailto:[email protected]) for the support in the package development and thorough testing of its functionality.
## Getting help
In a case you found any bugs, have feature request or general question please file an issue at the package [Github](https://github.com/r-world-devs/shinyQueryBuilder/issues).
You may also contact the package author directly via email at [[email protected]](mailto:[email protected]).