Skip to content

Commit 6163b92

Browse files
sarjonasarjona
authored
Merge pull request #637 from roland04/devdocs-customfields
[docs] Migrate Custom Fields API page
2 parents 4704f0a + 8384515 commit 6163b92

File tree

3 files changed

+176
-1
lines changed

3 files changed

+176
-1
lines changed

‎data/migratedPages.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,9 @@ Credits:
136136
Custom_Moodle_Apps:
137137
- filePath: "/general/app/customisation/custom-apps.md"
138138
slug: "/general/app/customisation/custom-apps"
139+
Custom_fields_API:
140+
- filePath: "/docs/apis/core/customfields/index.md"
141+
slug: "/docs/apis/core/customfields/"
139142
DDL_functions:
140143
- filePath: "/docs/apis/core/dml/ddl.md"
141144
slug: "/docs/apis/core/dml/ddl"

‎docs/apis.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,7 @@ The [https://docs.moodle.org/dev/OpenBadges_User_Documentation Badges] user docu
217217

218218
### Custom fields API (customfield)
219219

220-
The [Custom fields API](https://docs.moodle.org/dev/Custom_fields_API) allows you to configure and add custom fields for different entities
220+
The [Custom fields API](./apis/core/customfields/index.md) allows you to configure and add custom fields for different entities
221221

222222
## Activity module APIs
223223

‎docs/apis/core/customfields/index.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
title: Custom fields API
3+
tags: []
4+
---
5+
6+
import { Since } from '@site/src/components';
7+
8+
<Since versions={["3.7"]} issueNumber="MDL-57898" />
9+
10+
## Custom fields API overview
11+
12+
Custom fields API allows to configure custom fields that can be added to various contexts. Each **component** (or plugin) that wants to use custom fields can define several **areas**.
13+
14+
:::info Example
15+
The `core_course` component defines an area `course` that allows to add custom fields to the courses. The same component can define another area `coursecat` that will allow to add custom fields to the course categories.
16+
:::
17+
18+
Inside each area, the component/plugin can decide whether to use or not to use **itemid**.
19+
20+
:::info Example
21+
Course custom fields are the same throughout the system and they don't use `itemid` (it is always 0). But there could be an activity module that would want to configure different custom fields for each individual instance of module. Then this module would use the module id as the `itemid`, as in ([example](https://github.com/marinaglancy/moodle-mod_surveybuilder)). This would allow to create modules similar to `mod_data` and `mod_feedback` where each instance has its own set of fields.
22+
:::
23+
24+
New plugin type `customfield` was also added as part of the Custom fields API. Additional types of custom fields can be installed into `/customfield/field/`.
25+
26+
## How to use custom fields
27+
28+
Component/plugin that uses custom fields must define a **handler class** for each area and a **configuration page**. Handler class must be called `<PLUGINNAME>/customfield/<AREA>_handler` and be placed in autoloaded location `<PLUGINDIR>/classes/customfield/<AREA>_handler.php`. This class must extend **\core_customfield\handler** . Configuration page may be located anywhere. For course custom fields configuration the admin settings page is used [/course/customfield.php](https://github.com/moodle/moodle/blob/master/course/customfield.php). If the area uses `itemid` this page should take `itemid` as a parameter.
29+
30+
Handler has protected constructor, to get a handler call `create()` method. Some areas may choose to return a singleton here:
31+
32+
```php
33+
$handler = HANDLERCLASS::create($itemid);
34+
```
35+
36+
Configuration page contents will be:
37+
38+
```php
39+
$output = $PAGE->get_renderer('core_customfield');
40+
$outputpage = new \core_customfield\output\management($handler);
41+
echo $output->render($outputpage);
42+
```
43+
44+
Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:
45+
46+
```php
47+
handler::uses_categories()
48+
handler::generate_category_name()
49+
handler::config_form_definition() // For example, the course_handler adds "locked" and "visibility" settings that control who can edit or view the particular field.
50+
handler::setup_edit_page() // Sets page context/url/breadcrumb for the customfield/edit.php page, in some cases it must be overridden.
51+
```
52+
53+
### Add custom fields to the instance edit form
54+
55+
Custom fields are added to the **instances**. For example, course custom fields are added to the courses, so `courseid` is the `instanceid`. In the example of [mod_surveybuilder](https://github.com/marinaglancy/moodle-mod_surveybuilder) we use `$USER->id` as the `instanceid` (which means that in this example one user can fill the survey in one module only once). In each case of using custom fields there should be a clear concept of an **instance**. `Instanceid` is required to save the data but it may be empty when we render the instance edit form (for example, the course is not yet created).
56+
57+
Developer must add custom field callbacks to the instance edit form. If the instance is "made up" (like in `mod_surveybuilder`), a new form has to be created with `id` field in it that will refer to the `instanceid`.
58+
59+
The following callbacks should be used in `form definition`, `definition_after_data`, `validation` and `after form submission`:
60+
61+
```php
62+
$handler->instance_form_definition($mform)
63+
$handler->instance_form_before_set_data()
64+
$handler->instance_form_definition_after_data()
65+
$handler->instance_form_validation()
66+
$handler->instance_form_save($data)
67+
```
68+
69+
The `instance_form_save()` method must be called after the form was saved as the `$data` parameter must have the `id` attribute.
70+
71+
On deletion of an instance or on deletion of the whole item call:
72+
73+
```php
74+
$handler->delete_instance()
75+
$handler->delete_all()
76+
```
77+
78+
### Retrieving instances custom fields
79+
80+
How custom fields are used depends entirely on the situation.
81+
82+
```php title="Handler methods to retrieve custom fields values for the given instance(s)"
83+
$handler->export_instance_data()
84+
$handler->export_instance_data_object()
85+
$handler->display_custom_fields_data()
86+
```
87+
88+
Additional methods for advanced usage:
89+
90+
```php
91+
$handler->get_instance_data()
92+
$handler->get_instances_data()
93+
$handler->get_instance_data_for_backup()
94+
```
95+
96+
Method `restore_instance_data_from_backup()` exists in the handler class but is not implemented.
97+
98+
```php title="To retrieve the list of custom fields used in the given component/area/itemid"
99+
$handler->get_categories_with_fields()
100+
$handler->get_fields()
101+
```
102+
103+
:::note
104+
The list of fields is cached in the handler and these two functions can be called multiple times.
105+
:::
106+
107+
```php title="Example code for course custom fields. This function will return all the custom fields for a given courseid"
108+
function get_course_metadata($courseid) {
109+
$handler = \core_customfield\handler::get_handler('core_course', 'course');
110+
// This is equivalent to the line above.
111+
//$handler = \core_course\customfield\course_handler::create();
112+
$datas = $handler->get_instance_data($courseid);
113+
$metadata = [];
114+
foreach ($datas as $data) {
115+
if (empty($data->get_value())) {
116+
continue;
117+
}
118+
$cat = $data->get_field()->get_category()->get('name');
119+
$metadata[$data->get_field()->get('shortname')] = $cat . ': ' . $data->get_value();
120+
}
121+
return $metadata;
122+
}
123+
```
124+
125+
### Privacy API
126+
127+
Custom fields API does not export or delete any data because it does not know how custom fields are used, what data is considered user data and if it is considered private or shared data.
128+
129+
```php title="Plugins that store user information in custom fields should link subsystem in their get_metadata"
130+
$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');
131+
```
132+
133+
```php title="They can use the following methods in the export/delete functions"
134+
use core_customfield\privacy\provider as customfield_provider;
135+
136+
customfield_provider::get_customfields_data_contexts()
137+
customfield_provider::export_customfields_data()
138+
customfield_provider::delete_customfields_data()
139+
customfield_provider::delete_customfields_data_for_context()
140+
```
141+
142+
In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations:
143+
144+
```php
145+
customfield_provider::get_customfields_configuration_contexts()
146+
customfield_provider::delete_customfields_configuration()
147+
customfield_provider::delete_customfields_configuration_for_context()
148+
```
149+
150+
:::info
151+
Export of configuration was not yet implemented at the time of writing this because of difficult implementation and very unclear use case. If it is needed please feel free to contribute to Moodle.
152+
:::
153+
154+
## Custom fields plugins
155+
156+
Custom fields plugin type was added to allow implement different types of custom fields (somehow similar to user profile fields plugin type). Plugins are located in `/customfield/field/` and the full frankenstyle name of the plugins start with `customfield_`.
157+
158+
Except for common [Plugin files](../../commonfiles/index.mdx) and tests the following classes must be present in `customfield` plugins (in respective autoloaded locations):
159+
160+
```php
161+
namespace customfield_<PLUGINNAME>;
162+
class field_controller extends \core_customfield\field_controller;
163+
class data_controller extends \core_customfield\data_controller;
164+
165+
namespace customfield_<PLUGINNAME>\privacy;
166+
class provider implements \core_privacy\local\metadata\null_provider, \core_customfield\privacy\customfield_provider;
167+
```
168+
169+
## See also
170+
171+
- [MDL-64626](https://tracker.moodle.org/browse/MDL-64626) - Custom fields API (Moodle 3.7+) implementations and improvements
172+
- [MDL-57898](https://tracker.moodle.org/browse/MDL-57898) - Add custom field types plugin and course custom fields functionality

0 commit comments

Comments
 (0)