Search moodle.org's
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.

Class: handler  - X-Ref

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)

__construct(int $itemid = 0)   X-Ref
Handler constructor.

param: int $itemid

Class: name  - X-Ref

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