Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
core_customfield\handler Class Reference

Base class for custom fields handlers. More...

Inheritance diagram for core_customfield\handler:
core_cohort\customfield\cohort_handler core_course\customfield\course_handler core_group\customfield\group_handler core_group\customfield\grouping_handler qbank_customfields\customfield\question_handler

Public Member Functions

 backup_define_structure (int $instanceid, backup_nested_element $customfieldselement)
 Run the custom field backup callback for each controller.
 
 can_configure ()
 The current user can configure custom fields on this component.
 
 can_edit (field_controller $field, int $instanceid=0)
 The current user can edit given custom fields on the given instance.
 
 can_view (field_controller $field, int $instanceid)
 The current user can view the value of the custom field for a given custom field and instance.
 
 config_form_definition (\MoodleQuickForm $mform)
 Allows to add custom controls to the field configuration form that will be saved in configdata.
 
 create_category (string $name=null)
 Creates a new category and inserts it to the database.
 
 delete_all ()
 Deletes all data and all fields and categories defined in this handler.
 
 delete_category (category_controller $category)
 Permanently delete category, all fields in it and all associated data.
 
 delete_field_configuration (field_controller $field)
 Permanently delete a custom field configuration and all associated data.
 
 delete_instance (int $instanceid)
 Deletes all data related to all fields of an instance.
 
 display_custom_fields_data (array $fieldsdata)
 Display visible custom fields.
 
 export_instance_data (int $instanceid, bool $returnall=false)
 Returns the custom field values for an individual instance ready to be displayed.
 
 export_instance_data_object (int $instanceid, bool $returnall=false)
 Returns the custom field values for an individual instance ready to be displayed.
 
 get_area ()
 Get area.
 
 get_available_field_types ()
 Get field types array.
 
 get_categories_with_fields ()
 Returns array of categories, each of them contains a list of fields definitions.
 
 get_component ()
 Get component.
 
 get_configuration_context ()
 Context that should be used for new categories created by this handler.
 
 get_configuration_url ()
 URL for configuration of the fields on this handler.
 
 get_description_text_options ()
 Options for processing embedded files in the field description.
 
 get_editable_fields (int $instanceid)
 Get editable fields.
 
 get_fields ()
 Returns list of fields defined for this instance as an array (not groupped by categories)
 
 get_instance_context (int $instanceid=0)
 Context that should be used for data stored for the given record.
 
 get_instance_data (int $instanceid, bool $returnall=false)
 Returns the custom field values for an individual instance.
 
 get_instance_data_for_backup (int $instanceid)
 Get raw data associated with all fields current user can view or edit.
 
 get_instances_data (array $instanceids, bool $returnall=false)
 Returns the custom fields values for multiple instances.
 
 get_itemid ()
 Get itemid.
 
 instance_form_before_set_data (stdClass $instance)
 Prepares the custom fields data related to the instance to pass to mform->set_data()
 
 instance_form_definition (\MoodleQuickForm $mform, int $instanceid=0, ?string $headerlangidentifier=null, ?string $headerlangcomponent=null)
 Adds custom fields to instance editing form.
 
 instance_form_definition_after_data (\MoodleQuickForm $mform, int $instanceid=0)
 Form data definition callback.
 
 instance_form_save (stdClass $instance, bool $isnewinstance=false)
 Saves the given data for custom fields, must be called after the instance is saved and id is present.
 
 instance_form_validation (array $data, array $files)
 Validates the given data for custom fields, used in moodleform validation() function.
 
 move_category (category_controller $category, int $beforeid=0)
 Change sort order of the categories.
 
 move_field (field_controller $field, int $categoryid, int $beforeid=0)
 Change fields sort order, move field to another category.
 
 rename_category (category_controller $category, string $name)
 Change name for a field category.
 
 restore_define_structure (\restore_structure_step $step, int $newid, int $oldid)
 Run the custom field restore callback for each controller.
 
 restore_instance_data_from_backup (\restore_task $task, array $data)
 Creates or updates custom field data for a instanceid from backup data.
 
 save_field_configuration (field_controller $field, stdClass $data)
 Save the field configuration with the data from the form.
 
 uses_categories ()
 Uses categories.
 

Static Public Member Functions

static create (int $itemid=0)
 Returns an instance of the handler.
 
static get_handler (string $component, string $area, int $itemid=0)
 Returns an instance of handler by component/area/itemid.
 

Protected Member Functions

 __construct (int $itemid=0)
 Handler constructor.
 
 can_backup (field_controller $field, int $instanceid)
 Checks if current user can backup a given field.
 
 clear_configuration_cache ()
 Clears a list of categories with corresponding fields definitions.
 
 generate_category_name ($suffix=0)
 Generates a name for the new category.
 
 get_visible_fields (int $instanceid)
 Get visible fields.
 
 validate_category (category_controller $category)
 Validate that the given category belongs to this handler.
 
 validate_field (field_controller $field)
 Validate that the given field belongs to this handler.
 

Protected Attributes

category_controller[] $categories = null
 

Detailed Description

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:

Also handler is automatically created when the following methods are called:

  • core_customfield\api\get_field($fieldid)
  • core_customfield\api\get_category($categoryid)
License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

core_customfield\handler::__construct ( int $itemid = 0)
finalprotected

Handler constructor.

Parameters
int$itemid

Member Function Documentation

◆ backup_define_structure()

core_customfield\handler::backup_define_structure ( int $instanceid,
backup_nested_element $customfieldselement )

Run the custom field backup callback for each controller.

Parameters
int$instanceidThe instance ID.
backup_nested_element$customfieldselementThe custom field element to be backed up.

◆ can_backup()

core_customfield\handler::can_backup ( field_controller $field,
int $instanceid )
protected

Checks if current user can backup a given field.

Capability to backup the instance does not need to be checked here

Parameters
field_controller$field
int$instanceid
Return values
bool

◆ can_configure()

core_customfield\handler::can_configure ( )
abstract

◆ can_edit()

core_customfield\handler::can_edit ( field_controller $field,
int $instanceid = 0 )
abstract

The current user can edit given custom fields on the given instance.

Called to filter list of fields displayed on the instance edit form

Capability to edit/create instance is checked separately

Parameters
field_controller$field
int$instanceidid of the instance or 0 if the instance is being created
Return values
bool

Reimplemented in core_cohort\customfield\cohort_handler, core_course\customfield\course_handler, core_group\customfield\group_handler, core_group\customfield\grouping_handler, and qbank_customfields\customfield\question_handler.

◆ can_view()

core_customfield\handler::can_view ( field_controller $field,
int $instanceid )
abstract

The current user can view the value of the custom field for a given custom field and instance.

Called to filter list of fields returned by methods get_instance_data(), get_instances_data(), export_instance_data(), export_instance_data_object()

Access to the instance itself is checked by handler before calling these methods

Parameters
field_controller$field
int$instanceid
Return values
bool

Reimplemented in core_cohort\customfield\cohort_handler, core_course\customfield\course_handler, core_group\customfield\group_handler, core_group\customfield\grouping_handler, and qbank_customfields\customfield\question_handler.

◆ config_form_definition()

core_customfield\handler::config_form_definition ( \MoodleQuickForm $mform)

Allows to add custom controls to the field configuration form that will be saved in configdata.

Parameters
MoodleQuickForm$mform

Reimplemented in core_course\customfield\course_handler, and qbank_customfields\customfield\question_handler.

◆ create()

static core_customfield\handler::create ( int $itemid = 0)
static

Returns an instance of the handler.

Some areas may choose to use singleton/caching here

Parameters
int$itemid
Return values
handler

Reimplemented in core_cohort\customfield\cohort_handler, core_course\customfield\course_handler, core_group\customfield\group_handler, core_group\customfield\grouping_handler, and qbank_customfields\customfield\question_handler.

◆ create_category()

core_customfield\handler::create_category ( string $name = null)

Creates a new category and inserts it to the database.

Parameters
string$namename of the category, null to generate automatically
Return values
intid of the new category

◆ delete_category()

core_customfield\handler::delete_category ( category_controller $category)

Permanently delete category, all fields in it and all associated data.

Parameters
category_controller$category
Return values
bool

◆ delete_field_configuration()

core_customfield\handler::delete_field_configuration ( field_controller $field)

Permanently delete a custom field configuration and all associated data.

Parameters
field_controller$field
Return values
bool

◆ delete_instance()

core_customfield\handler::delete_instance ( int $instanceid)

Deletes all data related to all fields of an instance.

Parameters
int$instanceid

◆ display_custom_fields_data()

core_customfield\handler::display_custom_fields_data ( array $fieldsdata)

Display visible custom fields.

This is a sample implementation that can be overridden in each handler.

Parameters
data_controller[]$fieldsdata
Return values
string

◆ export_instance_data()

core_customfield\handler::export_instance_data ( int $instanceid,
bool $returnall = false )

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

Parameters
int$instanceid
bool$returnall
Return values
core_customfield\output\field_data[]

◆ export_instance_data_object()

core_customfield\handler::export_instance_data_object ( int $instanceid,
bool $returnall = false )

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

Parameters
int$instanceid
bool$returnall
Return values
stdClass

◆ generate_category_name()

core_customfield\handler::generate_category_name ( $suffix = 0)
protected

Generates a name for the new category.

Parameters
int$suffix
Return values
string

◆ get_area()

core_customfield\handler::get_area ( )

Get area.

Return values
string

◆ get_available_field_types()

core_customfield\handler::get_available_field_types ( )

Get field types array.

Return values
array

◆ get_categories_with_fields()

core_customfield\handler::get_categories_with_fields ( )

Returns array of categories, each of them contains a list of fields definitions.

Return values
category_controller[]

◆ get_component()

core_customfield\handler::get_component ( )

Get component.

Return values
string

◆ get_configuration_context()

core_customfield\handler::get_configuration_context ( )
abstract

◆ get_configuration_url()

core_customfield\handler::get_configuration_url ( )
abstract

◆ get_description_text_options()

core_customfield\handler::get_description_text_options ( )

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 values
array

◆ get_editable_fields()

core_customfield\handler::get_editable_fields ( int $instanceid)

Get editable fields.

Parameters
int$instanceid
Return values
field_controller[]

◆ get_fields()

core_customfield\handler::get_fields ( )

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 values
field_controller[]

◆ get_handler()

static core_customfield\handler::get_handler ( string $component,
string $area,
int $itemid = 0 )
static

Returns an instance of handler by component/area/itemid.

Parameters
string$componentcomponent name of full frankenstyle plugin name
string$areaname of the area (each component/plugin may define handlers for multiple areas)
int$itemiditem id if the area uses them (usually not used)
Return values
handler

◆ get_instance_context()

core_customfield\handler::get_instance_context ( int $instanceid = 0)
abstract

Context that should be used for data stored for the given record.

Parameters
int$instanceidid of the instance or 0 if the instance is being created
Return values
context

Reimplemented in core_cohort\customfield\cohort_handler, core_course\customfield\course_handler, core_group\customfield\group_handler, core_group\customfield\grouping_handler, and qbank_customfields\customfield\question_handler.

◆ get_instance_data()

core_customfield\handler::get_instance_data ( int $instanceid,
bool $returnall = false )

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

Parameters
int$instanceid
bool$returnallreturn data for all fields (by default only visible fields)
Return values
data_controller[]array of data_controller objects indexed by fieldid. All fields are present, some data_controller objects may have 'id', some not In the last case data_controller\get_value() and export_value() functions will return default values.

◆ get_instance_data_for_backup()

core_customfield\handler::get_instance_data_for_backup ( int $instanceid)

Get raw data associated with all fields current user can view or edit.

Parameters
int$instanceid
Return values
array

Reimplemented in core_group\customfield\group_handler, and core_group\customfield\grouping_handler.

◆ get_instances_data()

core_customfield\handler::get_instances_data ( array $instanceids,
bool $returnall = false )

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

Parameters
int[]$instanceids
bool$returnallreturn data for all fields (by default only visible fields)
Return values
data_controller[][]2-dimension array, first index is instanceid, second index is fieldid. All instanceids and all fieldids are present, some data_controller objects may have 'id', some not. In the last case data_controller\get_value() and export_value() functions will return default values.

◆ get_itemid()

core_customfield\handler::get_itemid ( )

Get itemid.

Return values
int|null

◆ get_visible_fields()

core_customfield\handler::get_visible_fields ( int $instanceid)
protected

Get visible fields.

Parameters
int$instanceid
Return values
field_controller[]

◆ instance_form_before_set_data()

core_customfield\handler::instance_form_before_set_data ( stdClass $instance)

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);

Parameters
stdClass$instancethe instance that has custom fields, if 'id' attribute is present the custom fields for this instance will be added, otherwise the default values will be added.

◆ instance_form_definition()

core_customfield\handler::instance_form_definition ( \MoodleQuickForm $mform,
int $instanceid = 0,
?string $headerlangidentifier = null,
?string $headerlangcomponent = null )

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(); }

Parameters
MoodleQuickForm$mform
int$instanceidid of the instance, can be null when instance is being created
string$headerlangidentifierIf specified, a lang string will be used for field category headings
string$headerlangcomponent

◆ instance_form_definition_after_data()

core_customfield\handler::instance_form_definition_after_data ( \MoodleQuickForm $mform,
int $instanceid = 0 )

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.

Parameters
MoodleQuickForm$mform
int$instanceid

◆ instance_form_save()

core_customfield\handler::instance_form_save ( stdClass $instance,
bool $isnewinstance = false )

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(...); }

Parameters
stdClass$instancedata received from a form
bool$isnewinstanceif this is call is made during instance creation

◆ instance_form_validation()

core_customfield\handler::instance_form_validation ( array $data,
array $files )

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; }

Parameters
array$data
array$files
Return values
arrayvalidation errors

◆ move_category()

core_customfield\handler::move_category ( category_controller $category,
int $beforeid = 0 )

Change sort order of the categories.

Parameters
category_controller$categorycategory that needs to be moved
int$beforeidid of the category this category needs to be moved before, 0 to move to the end

◆ move_field()

core_customfield\handler::move_field ( field_controller $field,
int $categoryid,
int $beforeid = 0 )

Change fields sort order, move field to another category.

Parameters
field_controller$fieldfield that needs to be moved
int$categoryidcategory that needs to be moved
int$beforeidid of the category this category needs to be moved before, 0 to move to the end

◆ rename_category()

core_customfield\handler::rename_category ( category_controller $category,
string $name )

Change name for a field category.

Parameters
category_controller$category
string$name

◆ restore_define_structure()

core_customfield\handler::restore_define_structure ( \restore_structure_step $step,
int $newid,
int $oldid )

Run the custom field restore callback for each controller.

Parameters
restore_structure_step$stepThe restore step instance.
int$newidThe new ID for the custom field data after restore.
int$oldidThe original ID of the custom field data before backup.

◆ restore_instance_data_from_backup()

core_customfield\handler::restore_instance_data_from_backup ( \restore_task $task,
array $data )

Creates or updates custom field data for a instanceid from backup data.

The handlers have to override it if they support backup.

Parameters
restore_task$task
array$data
Return values
int|voidImplementations should conditionally return the ID of the created or updated record.

Reimplemented in core_course\customfield\course_handler, and qbank_customfields\customfield\question_handler.

◆ save_field_configuration()

core_customfield\handler::save_field_configuration ( field_controller $field,
stdClass $data )

Save the field configuration with the data from the form.

Parameters
field_controller$field
stdClass$datadata from the form

◆ uses_categories()

core_customfield\handler::uses_categories ( )

Uses categories.

Return values
bool

◆ validate_category()

core_customfield\handler::validate_category ( category_controller $category)
protected

Validate that the given category belongs to this handler.

Parameters
category_controller$category
Return values
category_controller
Exceptions
moodle_exception

◆ validate_field()

core_customfield\handler::validate_field ( field_controller $field)
protected

Validate that the given field belongs to this handler.

Parameters
field_controller$field
Return values
field_controller
Exceptions
moodle_exception

The documentation for this class was generated from the following file: