Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
- Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
- PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/customfield/classes/ -> handler.php (source)
Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]
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 return: handler param: int $itemid |
| get_handler(string $component, string $area, int $itemid = 0) X-Ref |
| Returns an instance of handler by component/area/itemid return: handler 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) |
| 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 return: string param: int $suffix |
| create_category(string $name = null) X-Ref |
| Creates a new category and inserts it to the database return: int id of the new category param: string $name name of the category, null to generate automatically |
| validate_category(category_controller $category) X-Ref |
| Validate that the given category belongs to this handler return: category_controller param: category_controller $category |
| validate_field(field_controller $field) X-Ref |
| Validate that the given field belongs to this handler return: field_controller param: field_controller $field |
| 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 return: bool param: category_controller $category |
| 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 return: bool param: field_controller $field |
| 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 return: data_controller[] array of data_controller objects indexed by fieldid. All fields are present, param: int $instanceid param: bool $returnall return data for all fields (by default only visible fields) |
| 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 return: data_controller[][] 2-dimension array, first index is instanceid, second index is fieldid. param: int[] $instanceids param: bool $returnall return data for all fields (by default only visible fields) |
| 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 return: \core_customfield\output\field_data[] param: int $instanceid param: bool $returnall |
| 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 return: stdClass param: int $instanceid param: bool $returnall |
| display_custom_fields_data(array $fieldsdata) X-Ref |
| Display visible custom fields. This is a sample implementation that can be overridden in each handler. return: string param: data_controller[] $fieldsdata |
| 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 return: bool param: field_controller $field param: int $instanceid |
| get_instance_data_for_backup(int $instanceid) X-Ref |
| Get raw data associated with all fields current user can view or edit return: array param: int $instanceid |
| 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; } return: array validation errors param: array $data param: array $files |
| 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 return: field_controller[] param: int $instanceid |
| 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 |
