Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/customfield/classes/ -> handler.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401]
The abstract custom fields handler
| Copyright: | 2018 David Matamoros <davidmc@moodle.com> |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 789 lines (28 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
Defines 2 classes
handler:: (1 method):
__construct()
name:: (39 methods):
create()
get_handler()
get_component()
get_area()
get_itemid()
uses_categories()
generate_category_name()
create_category()
validate_category()
validate_field()
rename_category()
move_category()
delete_category()
delete_all()
delete_field_configuration()
move_field()
get_instance_data()
get_instances_data()
export_instance_data()
export_instance_data_object()
display_custom_fields_data()
get_categories_with_fields()
clear_configuration_cache()
can_backup()
get_instance_data_for_backup()
instance_form_definition_after_data()
instance_form_before_set_data()
instance_form_save()
instance_form_validation()
instance_form_definition()
get_available_field_types()
get_description_text_options()
save_field_configuration()
restore_instance_data_from_backup()
get_fields()
get_visible_fields()
get_editable_fields()
config_form_definition()
delete_instance()
Base class for custom fields handlers
This handler provides callbacks for field configuration form and also allows to add the fields to the instance editing form
Every plugin that wants to use custom fields must define a handler class:
<COMPONENT_OR_PLUGIN>\customfield\<AREA>_handler extends \core_customfield\handler
To initiate a class use an appropriate static method:
- <handlerclass>::create - to create an instance of a known handler
- \core_customfield\handler::get_handler - to create an instance of a handler for given component/area/itemid
Also handler is automatically created when the following methods are called:
- \core_customfield\api::get_field($fieldid)
- \core_customfield\api::get_category($categoryid)
This handler provides callbacks for field configuration form and also allows to add the fields to the instance editing form
Every plugin that wants to use custom fields must define a handler class:
<COMPONENT_OR_PLUGIN>\customfield\<AREA>_handler extends \core_customfield\handler
To initiate a class use an appropriate static method:
- <handlerclass>::create - to create an instance of a known handler
- \core_customfield\handler::get_handler - to create an instance of a handler for given component/area/itemid
Also handler is automatically created when the following methods are called:
- \core_customfield\api::get_field($fieldid)
- \core_customfield\api::get_category($categoryid)
| __construct(int $itemid = 0) X-Ref |
| Handler constructor. param: int $itemid |
| create(int $itemid = 0) X-Ref |
| Returns an instance of the handler Some areas may choose to use singleton/caching here param: int $itemid return: handler |
| get_handler(string $component, string $area, int $itemid = 0) X-Ref |
| Returns an instance of handler by component/area/itemid param: string $component component name of full frankenstyle plugin name param: string $area name of the area (each component/plugin may define handlers for multiple areas) param: int $itemid item id if the area uses them (usually not used) return: handler |
| get_component() X-Ref |
| Get component return: string |
| get_area() X-Ref |
| Get area return: string |
| get_itemid() X-Ref |
| Get itemid return: int|null |
| uses_categories() X-Ref |
| Uses categories return: bool |
| generate_category_name($suffix = 0) X-Ref |
| Generates a name for the new category param: int $suffix return: string |
| create_category(string $name = null) X-Ref |
| Creates a new category and inserts it to the database param: string $name name of the category, null to generate automatically return: int id of the new category |
| validate_category(category_controller $category) X-Ref |
| Validate that the given category belongs to this handler param: category_controller $category return: category_controller |
| validate_field(field_controller $field) X-Ref |
| Validate that the given field belongs to this handler param: field_controller $field return: field_controller |
| rename_category(category_controller $category, string $name) X-Ref |
| Change name for a field category param: category_controller $category param: string $name |
| move_category(category_controller $category, int $beforeid = 0) X-Ref |
| Change sort order of the categories param: category_controller $category category that needs to be moved param: int $beforeid id of the category this category needs to be moved before, 0 to move to the end |
| delete_category(category_controller $category) X-Ref |
| Permanently delete category, all fields in it and all associated data param: category_controller $category return: bool |
| delete_all() X-Ref |
| Deletes all data and all fields and categories defined in this handler |
| delete_field_configuration(field_controller $field) X-Ref |
| Permanently delete a custom field configuration and all associated data param: field_controller $field return: bool |
| move_field(field_controller $field, int $categoryid, int $beforeid = 0) X-Ref |
| Change fields sort order, move field to another category param: field_controller $field field that needs to be moved param: int $categoryid category that needs to be moved param: int $beforeid id of the category this category needs to be moved before, 0 to move to the end |
| get_instance_data(int $instanceid, bool $returnall = false) X-Ref |
| Returns the custom field values for an individual instance The caller must check access to the instance itself before invoking this method The result is an array of data_controller objects param: int $instanceid param: bool $returnall return data for all fields (by default only visible fields) return: data_controller[] array of data_controller objects indexed by fieldid. All fields are present, |
| get_instances_data(array $instanceids, bool $returnall = false) X-Ref |
| Returns the custom fields values for multiple instances The caller must check access to the instance itself before invoking this method The result is an array of data_controller objects param: int[] $instanceids param: bool $returnall return data for all fields (by default only visible fields) return: data_controller[][] 2-dimension array, first index is instanceid, second index is fieldid. |
| export_instance_data(int $instanceid, bool $returnall = false) X-Ref |
| Returns the custom field values for an individual instance ready to be displayed The caller must check access to the instance itself before invoking this method The result is an array of \core_customfield\output\field_data objects param: int $instanceid param: bool $returnall return: \core_customfield\output\field_data[] |
| export_instance_data_object(int $instanceid, bool $returnall = false) X-Ref |
| Returns the custom field values for an individual instance ready to be displayed The caller must check access to the instance itself before invoking this method The result is a class where properties are fields short names and the values their export values for this instance param: int $instanceid param: bool $returnall return: stdClass |
| display_custom_fields_data(array $fieldsdata) X-Ref |
| Display visible custom fields. This is a sample implementation that can be overridden in each handler. param: data_controller[] $fieldsdata return: string |
| get_categories_with_fields() X-Ref |
| Returns array of categories, each of them contains a list of fields definitions. return: category_controller[] |
| clear_configuration_cache() X-Ref |
| Clears a list of categories with corresponding fields definitions. |
| can_backup(field_controller $field, int $instanceid) X-Ref |
| Checks if current user can backup a given field Capability to backup the instance does not need to be checked here param: field_controller $field param: int $instanceid return: bool |
| get_instance_data_for_backup(int $instanceid) X-Ref |
| Get raw data associated with all fields current user can view or edit param: int $instanceid return: array |
| instance_form_definition_after_data(\MoodleQuickForm $mform, int $instanceid = 0) X-Ref |
| Form data definition callback. This method is called from moodleform::definition_after_data and allows to tweak mform with some data coming directly from the field plugin data controller. param: \MoodleQuickForm $mform param: int $instanceid |
| instance_form_before_set_data(stdClass $instance) X-Ref |
| Prepares the custom fields data related to the instance to pass to mform->set_data() Example: $instance = $DB->get_record(...); // .... prepare editor, filemanager, add tags, etc. $handler->instance_form_before_set_data($instance); $form->set_data($instance); param: stdClass $instance the instance that has custom fields, if 'id' attribute is present the custom |
| instance_form_save(stdClass $instance, bool $isnewinstance = false) X-Ref |
| Saves the given data for custom fields, must be called after the instance is saved and id is present Example: if ($data = $form->get_data()) { // ... save main instance, set $data->id if instance was created. $handler->instance_form_save($data); redirect(...); } param: stdClass $instance data received from a form param: bool $isnewinstance if this is call is made during instance creation |
| instance_form_validation(array $data, array $files) X-Ref |
| Validates the given data for custom fields, used in moodleform validation() function Example: public function validation($data, $files) { $errors = []; // .... check other fields. $errors = array_merge($errors, $handler->instance_form_validation($data, $files)); return $errors; } param: array $data param: array $files return: array validation errors |
| instance_form_definition(\MoodleQuickForm $mform, int $instanceid = 0,?string $headerlangidentifier = null, ?string $headerlangcomponent = null) X-Ref |
| Adds custom fields to instance editing form Example: public function definition() { // ... normal instance definition, including hidden 'id' field. $handler->instance_form_definition($this->_form, $instanceid); $this->add_action_buttons(); } param: \MoodleQuickForm $mform param: int $instanceid id of the instance, can be null when instance is being created param: string $headerlangidentifier If specified, a lang string will be used for field category headings param: string $headerlangcomponent |
| get_available_field_types() X-Ref |
| Get field types array return: array |
| get_description_text_options() X-Ref |
| Options for processing embedded files in the field description. Handlers may want to extend it to disable files support and/or specify 'noclean'=>true Context is not necessary here return: array |
| save_field_configuration(field_controller $field, stdClass $data) X-Ref |
| Save the field configuration with the data from the form param: field_controller $field param: stdClass $data data from the form |
| restore_instance_data_from_backup(\restore_task $task, array $data) X-Ref |
| Creates or updates custom field data for a instanceid from backup data. The handlers have to override it if they support backup param: \restore_task $task param: array $data |
| get_fields() X-Ref |
| Returns list of fields defined for this instance as an array (not groupped by categories) Fields are sorted in the same order they would appear on the instance edit form Note that this function returns all fields in all categories regardless of whether the current user can view or edit data associated with them return: field_controller[] |
| get_visible_fields(int $instanceid) X-Ref |
| Get visible fields param: int $instanceid return: field_controller[] |
| get_editable_fields(int $instanceid) X-Ref |
| No description |
| config_form_definition(\MoodleQuickForm $mform) X-Ref |
| No description |
| delete_instance(int $instanceid) X-Ref |
| Deletes all data related to all fields of an instance. param: int $instanceid |
