Skip to content

Commit f949add

Browse files
paulholdenpaulholden
authored
Merge pull request #1196 from NeillM/reportbuilder
Update report builder API docs
2 parents b38b432 + ac1cb31 commit f949add

8 files changed

Lines changed: 2775 additions & 115 deletions

File tree

‎docs/apis/core/reportbuilder/filtering.md‎

Lines changed: 329 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,329 @@
1+
---
2+
title: Setting default conditions
3+
tags:
4+
- Report builder
5+
- reports
6+
---
7+
8+
When setting up a `datasource` it is possible to define the default condition values for it using the `get_default_condition_values()` method.
9+
10+
The method requires that you return an array where the keys are formed in a specific way so it will link to the correct filter and condition form field. The names and number of condition form fields varies depending on both the specific filter type and the operator used.
11+
12+
The keys used in the array all start with the name of the entity you are querying followed by a colon and the name of the filter, then an underscore followed by the form field you are defining; for example, assuming we are using default names, if you have a `course_category` entity and want to set a value for the `name` filter you would need to start the keys with `course_categotry:name`.
13+
14+
Most filter types use an `operator` for field to define which of their operators is used, they are defined as constants in each filter type, for example the text filter type has `EQUAL_TO` so you will end up with `'course_categotry:name_operator' => text::EQUAL_TO`
15+
16+
The operator you have defined will then determine which other form fields you will need to provide values for, in our example so far that would be `value` which would be defined as `'course_categotry:name_value' => 'The name of a category'` this would mean that only a category with that exact name would be returned by default.
17+
18+
[Core report builder filter types](https://github.com/moodle/moodle/tree/main/reportbuilder/classes/local/filters) you can find what a filter type needs by looking at their `get_sql_filter()` method.
19+
20+
## Text filters
21+
22+
### Operators with no additional data
23+
24+
- `ANY_VALUE`
25+
- `IS_EMPTY`
26+
- `IS_NOT_EMPTY`
27+
28+
## Filtering types with a single value
29+
30+
A string should be sent in `value` for:
31+
32+
- `CONTAINS`
33+
- `DOES_NOT_CONTAIN`
34+
- `IS_EQUAL_TO`
35+
- `IS_NOT_EQUAL_TO`
36+
- `STARTS_WITH`
37+
- `ENDS_WITH`
38+
39+
```php title="Examples of array key and value pairs for single value text filters"
40+
'my:text_operator' => text::CONTAINS,
41+
'my:text_value1' => 'Bob Dylan',
42+
'my:text2_operator' => text::IS_NOT_EQUAL_TO,
43+
'my:text2_value1' => 'This exact thing',
44+
```
45+
46+
## Number filter
47+
48+
### Operators with no additional data
49+
50+
- `ANY_VALUE`
51+
- `IS_NOT_EMPTY`
52+
- `IS_EMPTY`
53+
54+
### Operators with a single value
55+
56+
A number should be passed in `value1` for:
57+
58+
- `LESS_THAN`
59+
- `GREATER_THAN`
60+
- `EQUAL_TO`
61+
- `EQUAL_OR_LESS_THAN`
62+
- `EQUAL_OR_GREATER_THAN`
63+
64+
```php title="Examples of array key and value pairs for single value number filters"
65+
'my:number_operator' => number::LESS_THAN,
66+
'my:number_value1' => 42,
67+
'my:number2_operator' => number::EQUAL_OR_GREATER_THAN,
68+
'my:number2_value1' => 15.6,
69+
```
70+
71+
### Operators with complex data
72+
73+
#### RANGE
74+
75+
- `value1` number for the lower bound
76+
- `value2` number for the upper bound
77+
78+
```php title="Examples of array key and value pairs for range values text filters"
79+
'my:number_operator' => number::RANGE,
80+
'my:number_value1' => 60,
81+
'my:number_value2' => 600,
82+
```
83+
84+
## Date filter
85+
86+
The date filter has several constants used to define the amount of time:
87+
88+
- `DATE_UNIT_MINUTE`
89+
- `DATE_UNIT_HOUR`
90+
- `DATE_UNIT_DAY`
91+
- `DATE_UNIT_WEEK`
92+
- `DATE_UNIT_MONTH`
93+
- `DATE_UNIT_YEAR`
94+
95+
### Operators with no additional data
96+
97+
- `DATE_ANY`
98+
- `DATE_NOT_EMPTY`
99+
- `DATE_EMPTY`
100+
- `DATE_PAST`
101+
- `DATE_FUTURE`
102+
103+
### Operators with one value
104+
105+
The `unit` should be sent defining the amount of time that should be considered.
106+
107+
- `DATE_CURRENT`
108+
109+
```php title="Examples of array key and value pairs for single value date filters"
110+
'my:date_operator' => date::DATE_CURRENT,
111+
'my:date_unit' => date::DATE_UNIT_DAY,
112+
```
113+
114+
### Operators with two values
115+
116+
These operators can all accept two values:
117+
118+
1. `value` - A integer greater than 0
119+
2. `unit` - The type of time unit
120+
121+
- `DATE_LAST`
122+
- `DATE_NEXT`
123+
- `DATE_BEFORE`
124+
- `DATE_AFTER`
125+
126+
```php title="Examples of array key and value pairs for two value date filters"
127+
'my:date_operator' => date::DATE_NEXT,
128+
'my:date_value' => 5,
129+
'my:date_unit' => date::DATE_UNIT_DAY,
130+
'my:date2_operator' => date::DATE_BEFORE,
131+
'my:date2_value' => 20,
132+
'my:date2_unit' => date::DATE_UNIT_MINUTE,
133+
```
134+
135+
### Operators with complex values
136+
137+
#### DATE_RANGE
138+
139+
The date range should have a unix timestamp in one or more of the following:
140+
141+
- `from`
142+
- `to`
143+
144+
```php title="Examples of array key and value pairs for the range date filters"
145+
'my:date_operator' => date::DATE_RANGE,
146+
'my:date_from' => 1732593669,
147+
'my:date_to' => 1732893669,
148+
```
149+
150+
## Select filter
151+
152+
### Operators with no additional data
153+
154+
- `ANY_VALUE`
155+
156+
### Operators with one value
157+
158+
The value of the select should be sent in `value` to:
159+
160+
- `EQUAL_TO`
161+
- `NOT_EQUAL_TO`
162+
163+
```php title="Examples of array key and value pairs for single value select filters"
164+
'my:select_operator' => select::EQUAL_TO,
165+
'my:select_value' => 10,
166+
'my:select2_operator' => select::NOT_EQUAL_TO,
167+
'my:select2_value' => 'textkey',
168+
```
169+
170+
## Boolean select filter
171+
172+
### Operators with no additional data
173+
174+
- `ANY_VALUE`
175+
- `CHECKED`
176+
- `NOT_CHECKED`
177+
178+
## Duration filter
179+
180+
For units the filter uses the standard Moodle defines:
181+
182+
- `MINSECS`
183+
- `HOURSECS`
184+
- `DAYSECS`
185+
- `WEEKSECS`
186+
187+
It also allows the integer value 1 to represent seconds.
188+
189+
### Operators with no additional data
190+
191+
- `DURATION_ANY`
192+
193+
### Operators with two values
194+
195+
These operators can all accept two values:
196+
197+
1. `value` - A integer greater than 0, this should be the number of the units that are included.
198+
2. `unit` - The type of time unit.
199+
200+
- `DURATION_MAXIMUM`
201+
- `DURATION_MINIMUM`
202+
203+
```php title="Examples of array key and value pairs for two value duration filters"
204+
'my:duration_operator' => duration::DURATION_MAXIMUM,
205+
'my:duration_value' => 10,
206+
'my:duration_unit' => 1,
207+
'my:duration2_operator' => duration::DURATION_MINIMUM,
208+
'my:duration_value' => 42,
209+
'my:duration_unit' => DAYSECS,
210+
```
211+
212+
## Autocomplete filter
213+
214+
This filter type does not use `operator`, it requires that `values` contains an array of keys that the autocompletion element would return.
215+
216+
```php title="Examples of array key and value pairs for autocomplete filters"
217+
'my:autocomplete_values' => [1, 4, 6],
218+
'my:autocomplete2_values' => [42],
219+
```
220+
221+
## Category filter
222+
223+
### Operators with complex values
224+
225+
Both the available operators for this have two values:
226+
227+
1. `value` The database id of a `course_category` record
228+
2. `subcategories` A boolean to indicate if sub categories of the selected category should also be included.
229+
230+
- `EQUAL_TO`
231+
- `NOT_EQUAL_TO`
232+
233+
```php title="Examples of array key and value pairs for category filters"
234+
'my:category_operator' => category::EQUAL_TO,
235+
'my:category_value' => [142, 4753],
236+
'my:category_subcategories' => true,
237+
'my:category2_operator' => category::NOT_EQUAL_TO,
238+
'my:category2_value' => [1],
239+
'my:category2_subcategories' => false,
240+
```
241+
242+
## Course_select filter
243+
244+
This filter type does not use `operator`, it requires that `values` contains an array of database ids for courses.
245+
246+
```php title="Examples of array key and value pairs for course filters"
247+
'my:course_values' => [1, 4, 6],
248+
'my:course2_values' => [42],
249+
```
250+
251+
## Cohort filter
252+
253+
This filter type does not use `operator`, it requires that `values` contains an array of database ids for cohorts.
254+
255+
```php title="Examples of array key and value pairs for cohort filters"
256+
'my:cohort_values' => [1, 4, 6],
257+
'my:cohort2_values' => [42],
258+
```
259+
260+
## Filesize filter
261+
262+
The filter defines several units for filesize as constants:
263+
264+
- `SIZE_UNIT_KILOBYTE`
265+
- `SIZE_UNIT_MEGABYTE`
266+
- `SIZE_UNIT_GIGABYTE`
267+
268+
### Operators with no additional data
269+
270+
- `ANY_VALUE`
271+
272+
### Operators with two values
273+
274+
1. `value1` The size of the file in the unit
275+
2. `unit` The type of unit (as defined by the filter constants)
276+
277+
- `LESS_THAN`
278+
- `GREATER_THAN`
279+
280+
```php title="Examples of array key and value pairs for two value file size filters"
281+
'my:filesize_operator' => filesize::LESS_THAN,
282+
'my:filesize_value1' => 50,
283+
'my:filesize_unit' => filesize::SIZE_UNIT_KILOBYTE,
284+
'my:filesize2_operator' => filesize::GREATER_THAN,
285+
'my:filesize2_value1' => 1,
286+
'my:filesize2_unit' => filesize::SIZE_UNIT_GIGABYTE,
287+
```
288+
289+
## Tags filter
290+
291+
### Operators with no additional data
292+
293+
- `ANY_VALUE`
294+
- `NOT_EMPTY`
295+
- `EMPTY`
296+
297+
### Operators with one value
298+
299+
An array of tag database ids should be sent in `value` to:
300+
301+
- `EQUAL_TO`
302+
- `NOT_EQUAL_TO`
303+
304+
```php title="Examples of array key and value pairs for single value tag filters"
305+
'my:tags_operator' => tags::EQUAL_TO,
306+
'my:tags_value' => [142, 4753],
307+
'my:tags2_operator' => tags::NOT_EQUAL_TO,
308+
'my:tags2_value' => [1],
309+
```
310+
311+
## User filter
312+
313+
### Operators with no additional data
314+
315+
- `USER_ANY`
316+
- `USER_CURRENT`
317+
318+
### Operators with one value
319+
320+
An array of user database ids should be sent in `value` to:
321+
322+
- `USER_SELECT`
323+
324+
```php title="Examples of array key and value pairs for single value user filters"
325+
'my:user_operator' => user::USER_SELECT,
326+
'my:user_value' => [142, 4753],
327+
'my:user2_operator' => user::USER_SELECT,
328+
'my:user2_value' => [1],
329+
```

0 commit comments

Comments
 (0)