|
|
| (6 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| {{Moodle 3.7}} | | {{Template:Migrated|newDocId=/docs/apis/core/customfields/}} |
| | |
| == Custom fields API overview ==
| |
| | |
| Custom fields API was added in Moodle 3.7. It 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'''. For example, '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. Inside each area the component/plugin can decide whether to use or not to use '''itemid'''. For example, 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 ([https://github.com/marinaglancy/moodle-mod_surveybuilder example]). This would allow to create modules similar to mod_data and mod_feedback where each instance has it's own set of fields.
| |
| | |
| 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/ .
| |
| | |
| == How to use custom fields ==
| |
| | |
| 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 [https://github.com/moodle/moodle/blob/master/course/customfield.php /course/customfield.php]. If the area uses itemid this page should take itemid as a parameter.
| |
| | |
| Handler has protected constructor, to get a handler call create() method. Some areas may choose to return a singleton here:
| |
| | |
| <code php>
| |
| $handler = HANDLERCLASS::create($itemid);
| |
| </code>
| |
| | |
| Configuration page contents will be:
| |
| | |
| <code php>
| |
| $output = $PAGE->get_renderer('core_customfield');
| |
| $outputpage = new \core_customfield\output\management($handler);
| |
| echo $output->render($outputpage);
| |
| </code>
| |
| | |
| Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:
| |
| <code php>
| |
| handler::uses_categories()
| |
| handler::generate_category_name()
| |
| handler::config_form_definition() // For example, the course_handler adds "locked" and "visibility" settings that control who can edit or view the particular field.
| |
| handler::setup_edit_page() // Sets page context/url/breadcrumb for the customfield/edit.php page, in some cases it must be overridden.
| |
| </code>
| |
| | |
| === Add custom fields to the instance edit form ===
| |
| | |
| 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 [https://github.com/marinaglancy/moodle-mod_surveybuilder 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).
| |
| | |
| Developer must add custom fields 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.
| |
| | |
| The following callbacks should be used in form definition, definition_after_data, validation and after form submission:
| |
| <code php>
| |
| $hander->instance_form_definition()
| |
| $hander->instance_form_before_set_data()
| |
| $hander->instance_form_definition_after_data()
| |
| $hander->instance_form_validation()
| |
| $hander->instance_form_save()
| |
| </code>
| |
| | |
| On deletion of an instance or on deletion of the whole item call:
| |
| <code php>
| |
| $hander->delete_instance()
| |
| $hander->delete_all()
| |
| </code>
| |
| | |
| === Retrieving instances custom fields ===
| |
| | |
| How custom fields are used depends entirely on the situation. The following handler methods will help you to retrieve custom fields values for the given instance(s):
| |
| | |
| <code php>
| |
| $handler->export_instance_data()
| |
| $handler->export_instance_data_object()
| |
| $handler->display_custom_fields_data()
| |
| </code>
| |
| | |
| Additional methods for advanced usage:
| |
| <code php>
| |
| $handler->get_instance_data()
| |
| $handler->get_instances_data()
| |
| $handler->get_instance_data_for_backup()
| |
| </code>
| |
| Method restore_instance_data_from_backup() exists in the handler class but not implemented
| |
| | |
| To retrieve the list of custom fields used in the given component/area/itemid you can use:
| |
| <code php>
| |
| $handler->get_categories_with_fields()
| |
| $handler->get_fields()
| |
| </code>
| |
| List of fields is cached in the handler and these two functions can be called multiple times.
| |
| | |
| === Privacy API ===
| |
| | |
| 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.
| |
| | |
| Plugins that store user information in custom fields should link subsystem in their get_metadata:
| |
| <code php>
| |
| $collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');
| |
| </code>
| |
| | |
| And they can use the following methods in the export/delete functions:
| |
| <code php>
| |
| use core_customfield\privacy\provider as customfield_provider;
| |
| | |
| customfield_provider::get_customfields_data_contexts()
| |
| customfield_provider::export_customfields_data()
| |
| customfield_provider::delete_customfields_data()
| |
| customfield_provider::delete_customfields_data_for_context()
| |
| </code>
| |
| | |
| 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:
| |
| <code php>
| |
| customfield_provider::get_customfields_configuration_contexts()
| |
| customfield_provider::delete_customfields_configuration()
| |
| customfield_provider::delete_customfields_configuration_for_context()
| |
| </code>
| |
| 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.
| |
| | |
| == Custom fields plugins ==
| |
| | |
| 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_'''
| |
| | |
| Except for common [[Plugin files]] and tests the following classes must be present in customfield plugins (in respective autoloaded locations):
| |
| <code php>
| |
| namespace customfield_<PLUGINNAME>;
| |
| class field_controller extends \core_customfield\field_controller;
| |
| class data_controller extends \core_customfield\data_controller;
| |
| | |
| namespace customfield_<PLUGINNAME>\privacy;
| |
| class provider implements \core_privacy\local\metadata\null_provider, \core_customfield\privacy\customfield_provider;
| |
| </code>
| |
| | |
| == See also ==
| |
| | |
| MDL-64626 - Custom fields API (Moodle 3.7+) implementations and improvements
| |
| | |
| MDL-57898 - Add custom field types plugin and course custom fields functionality
| |
