Base class for custom fields handlers. More...

Inheritance diagram for core_customfield\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:

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

Copyright: 2018 David Matamoros david.nosp@m.mc@m.nosp@m.oodle.nosp@m..com

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	$instanceid	The instance ID.
backup_nested_element	$customfieldselement	The 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

The current user can configure custom fields on this component.

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_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	$instanceid	id 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 $name name of the category, null to generate automatically

Return values

int	id 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

Context that should be used for new categories created by this handler.

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_configuration_url()

core_customfield\handler::get_configuration_url ( )

abstract

URL for configuration of the fields on this handler.

Return values

moodle_url

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_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	$component	component name of full frankenstyle plugin name
string	$area	name of the area (each component/plugin may define handlers for multiple areas)
int	$itemid	item 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 $instanceid id 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	$returnall	return 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	$returnall	return 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 $instance the 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	$instanceid	id of the instance, can be null when instance is being created
string	$headerlangidentifier	If 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	$instance	data received from a form
bool	$isnewinstance	if 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

array validation errors

◆ move_category()

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

Change sort order of the categories.

Parameters

category_controller	$category	category that needs to be moved
int	$beforeid	id 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	$field	field that needs to be moved
int	$categoryid	category that needs to be moved
int	$beforeid	id 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	$step	The restore step instance.
int	$newid	The new ID for the custom field data after restore.
int	$oldid	The 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|void Implementations 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	$data	data 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:

customfield/classes/handler.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ backup_define_structure()

◆ can_backup()

◆ can_configure()

◆ can_edit()

◆ can_view()

◆ config_form_definition()

◆ create()

◆ create_category()

◆ delete_category()

◆ delete_field_configuration()

◆ delete_instance()

◆ display_custom_fields_data()

◆ export_instance_data()

◆ export_instance_data_object()

◆ generate_category_name()

◆ get_area()

◆ get_available_field_types()

◆ get_categories_with_fields()

◆ get_component()

◆ get_configuration_context()

◆ get_configuration_url()

◆ get_description_text_options()

◆ get_editable_fields()

◆ get_fields()

◆ get_handler()

◆ get_instance_context()

◆ get_instance_data()

◆ get_instance_data_for_backup()

◆ get_instances_data()

◆ get_itemid()

◆ get_visible_fields()

◆ instance_form_before_set_data()

◆ instance_form_definition()

◆ instance_form_definition_after_data()

◆ instance_form_save()

◆ instance_form_validation()

◆ move_category()

◆ move_field()

◆ rename_category()

◆ restore_define_structure()

◆ restore_instance_data_from_backup()

◆ save_field_configuration()

◆ uses_categories()

◆ validate_category()

◆ validate_field()