Custom fields API - Revision history

Devdocsbot: Protected "Custom fields API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2023-09-15T15:14:57Z

Protected "Custom fields API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 15:14, 15 September 2023
(No difference)

Devdocsbot: Update migration status and path

2023-09-15T15:11:53Z

Update migration status and path

Show changes

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:29:10Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:29, 14 July 2021
				
Line 13:
Line 13:
Handler has protected constructor, to get a handler call create() method. Some areas may choose to return a singleton here: Handler has protected constructor, to get a handler call create() method. Some areas may choose to return a singleton here:



<code php> <syntaxhighlight lang="php">
$handler = HANDLERCLASS::create($itemid); $handler = HANDLERCLASS::create($itemid);
</syntaxhighlight> </syntaxhighlight>
Line 19:
Line 19:
Configuration page contents will be: Configuration page contents will be:



<code php> <syntaxhighlight lang="php">
$output = $PAGE->get_renderer('core_customfield'); $output = $PAGE->get_renderer('core_customfield');
$outputpage = new \core_customfield\output\management($handler); $outputpage = new \core_customfield\output\management($handler);
Line 26:
Line 26:



Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite: Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:
<code php> <syntaxhighlight lang="php">
handler::uses_categories() handler::uses_categories()
handler::generate_category_name() handler::generate_category_name()
Line 40:
Line 40:



The following callbacks should be used in form definition, definition_after_data, validation and after form submission: The following callbacks should be used in form definition, definition_after_data, validation and after form submission:
<code php> <syntaxhighlight lang="php">
$handler->instance_form_definition($mform) $handler->instance_form_definition($mform)
$handler->instance_form_before_set_data() $handler->instance_form_before_set_data()
Line 49:
Line 49:






The <code php>instance_form_save()</syntaxhighlight> method must be called after the form was saved as the <code php>$data</syntaxhighlight> parameter must have the <code php>id</syntaxhighlight>attribute. The <syntaxhighlight lang="php">instance_form_save()</syntaxhighlight> method must be called after the form was saved as the <syntaxhighlight lang="php">$data</syntaxhighlight> parameter must have the <syntaxhighlight lang="php">id</syntaxhighlight>attribute.



On deletion of an instance or on deletion of the whole item call: On deletion of an instance or on deletion of the whole item call:
<code php> <syntaxhighlight lang="php">
$handler->delete_instance() $handler->delete_instance()
$handler->delete_all() $handler->delete_all()
Line 61:
Line 61:
How custom fields are used depends entirely on the situation. The following handler methods will help you to retrieve custom fields values for the given instance(s): How custom fields are used depends entirely on the situation. The following handler methods will help you to retrieve custom fields values for the given instance(s):



<code php> <syntaxhighlight lang="php">
$handler->export_instance_data() $handler->export_instance_data()
$handler->export_instance_data_object() $handler->export_instance_data_object()
Line 68:
Line 68:



Additional methods for advanced usage: Additional methods for advanced usage:
<code php> <syntaxhighlight lang="php">
$handler->get_instance_data() $handler->get_instance_data()
$handler->get_instances_data() $handler->get_instances_data()
Line 76:
Line 76:



To retrieve the list of custom fields used in the given component/area/itemid you can use: To retrieve the list of custom fields used in the given component/area/itemid you can use:
<code php> <syntaxhighlight lang="php">
$handler->get_categories_with_fields() $handler->get_categories_with_fields()
$handler->get_fields() $handler->get_fields()
Line 85:
Line 85:



This function will return all the custom fields for a given courseid: This function will return all the custom fields for a given courseid:
<code php> <syntaxhighlight lang="php">
function get_course_metadata($courseid) { function get_course_metadata($courseid) {
     $handler = \core_customfield\handler::get_handler('core_course', 'course');      $handler = \core_customfield\handler::get_handler('core_course', 'course');
Line 108:
Line 108:



Plugins that store user information in custom fields should link subsystem in their get_metadata: Plugins that store user information in custom fields should link subsystem in their get_metadata:
<code php> <syntaxhighlight lang="php">
$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose'); $collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');
</syntaxhighlight> </syntaxhighlight>



And they can use the following methods in the export/delete functions: And they can use the following methods in the export/delete functions:
<code php> <syntaxhighlight lang="php">
use core_customfield\privacy\provider as customfield_provider; use core_customfield\privacy\provider as customfield_provider;



Line 123:
Line 123:



In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations: In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations:
<code php> <syntaxhighlight lang="php">
customfield_provider::get_customfields_configuration_contexts() customfield_provider::get_customfields_configuration_contexts()
customfield_provider::delete_customfields_configuration() customfield_provider::delete_customfields_configuration()
Line 135:
Line 135:



Except for common [[Plugin files]] and tests the following classes must be present in customfield plugins (in respective autoloaded locations): Except for common [[Plugin files]] and tests the following classes must be present in customfield plugins (in respective autoloaded locations):
<code php> <syntaxhighlight lang="php">
namespace customfield_<PLUGINNAME>; namespace customfield_<PLUGINNAME>;
class field_controller extends \core_customfield\field_controller; class field_controller extends \core_customfield\field_controller;

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:04:22Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:04, 14 July 2021
Line 15:		Line 15:
	<code php>		<code php>
	$handler = HANDLERCLASS::create($itemid);		$handler = HANDLERCLASS::create($itemid);
	</~~code~~>		</syntaxhighlight>

	Configuration page contents will be:		Configuration page contents will be:
Line 23:		Line 23:
	$outputpage = new \core_customfield\output\management($handler);		$outputpage = new \core_customfield\output\management($handler);
	echo $output->render($outputpage);		echo $output->render($outputpage);
	</~~code~~>		</syntaxhighlight>

	Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:		Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:
Line 31:		Line 31:
	handler::config_form_definition() // For example, the course_handler adds "locked" and "visibility" settings that control who can edit or view the particular field.		handler::config_form_definition() // For example, the course_handler adds "locked" and "visibility" settings that control who can edit or view the particular field.
	handler::setup_edit_page() // Sets page context/url/breadcrumb for the customfield/edit.php page, in some cases it must be overridden.		handler::setup_edit_page() // Sets page context/url/breadcrumb for the customfield/edit.php page, in some cases it must be overridden.
	</~~code~~>		</syntaxhighlight>

	=== Add custom fields to the instance edit form ===		=== Add custom fields to the instance edit form ===
Line 46:		Line 46:
	$handler->instance_form_validation()		$handler->instance_form_validation()
	$handler->instance_form_save($data)		$handler->instance_form_save($data)
	</~~code~~>		</syntaxhighlight>


	The <code php>instance_form_save()</~~code~~> method must be called after the form was saved as the <code php>$data</~~code~~> parameter must have the <code php>id</~~code~~>attribute.		The <code php>instance_form_save()</syntaxhighlight> method must be called after the form was saved as the <code php>$data</syntaxhighlight> parameter must have the <code php>id</syntaxhighlight>attribute.

	On deletion of an instance or on deletion of the whole item call:		On deletion of an instance or on deletion of the whole item call:
Line 55:		Line 55:
	$handler->delete_instance()		$handler->delete_instance()
	$handler->delete_all()		$handler->delete_all()
	</~~code~~>		</syntaxhighlight>

	=== Retrieving instances custom fields ===		=== Retrieving instances custom fields ===
Line 65:		Line 65:
	$handler->export_instance_data_object()		$handler->export_instance_data_object()
	$handler->display_custom_fields_data()		$handler->display_custom_fields_data()
	</~~code~~>		</syntaxhighlight>

	Additional methods for advanced usage:		Additional methods for advanced usage:
Line 72:		Line 72:
	$handler->get_instances_data()		$handler->get_instances_data()
	$handler->get_instance_data_for_backup()		$handler->get_instance_data_for_backup()
	</~~code~~>		</syntaxhighlight>
	Method restore_instance_data_from_backup() exists in the handler class but not implemented		Method restore_instance_data_from_backup() exists in the handler class but not implemented

Line 79:		Line 79:
	$handler->get_categories_with_fields()		$handler->get_categories_with_fields()
	$handler->get_fields()		$handler->get_fields()
	</~~code~~>		</syntaxhighlight>
	List of fields is cached in the handler and these two functions can be called multiple times.		List of fields is cached in the handler and these two functions can be called multiple times.

Line 101:		Line 101:
	return $metadata;		return $metadata;
	}		}
	</~~code~~>		</syntaxhighlight>

	=== Privacy API ===		=== Privacy API ===
Line 110:		Line 110:
	<code php>		<code php>
	$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');		$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');
	</~~code~~>		</syntaxhighlight>

	And they can use the following methods in the export/delete functions:		And they can use the following methods in the export/delete functions:
Line 120:		Line 120:
	customfield_provider::delete_customfields_data()		customfield_provider::delete_customfields_data()
	customfield_provider::delete_customfields_data_for_context()		customfield_provider::delete_customfields_data_for_context()
	</~~code~~>		</syntaxhighlight>

	In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations:		In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations:
Line 127:		Line 127:
	customfield_provider::delete_customfields_configuration()		customfield_provider::delete_customfields_configuration()
	customfield_provider::delete_customfields_configuration_for_context()		customfield_provider::delete_customfields_configuration_for_context()
	</~~code~~>		</syntaxhighlight>
	Export of configuration was not yet implemented at the time of writing this because of difficult implementation and very unclear use case. If it is needed please feel free to contribute to Moodle.		Export of configuration was not yet implemented at the time of writing this because of difficult implementation and very unclear use case. If it is needed please feel free to contribute to Moodle.

Line 142:		Line 142:
	namespace customfield_<PLUGINNAME>\privacy;		namespace customfield_<PLUGINNAME>\privacy;
	class provider implements \core_privacy\local\metadata\null_provider, \core_customfield\privacy\customfield_provider;		class provider implements \core_privacy\local\metadata\null_provider, \core_customfield\privacy\customfield_provider;
	</~~code~~>		</syntaxhighlight>

	== See also ==		== See also ==

Msharp.chi: /* Retrieving instances custom fields */

2020-05-14T08:32:47Z

Retrieving instances custom fields

@@ Line 81: / Line 81: @@
 </code>
 List of fields is cached in the handler and these two functions can be called multiple times.
 === Privacy API ===

Danielneis: /* Add custom fields to the instance edit form */

2019-10-31T15:37:31Z

Add custom fields to the instance edit form

← Older revision		Revision as of 15:37, 31 October 2019
Line 41:		Line 41:
	The following callbacks should be used in form definition, definition_after_data, validation and after form submission:		The following callbacks should be used in form definition, definition_after_data, validation and after form submission:
	<code php>		<code php>
	$handler->instance_form_definition()		$handler->instance_form_definition($mform)
	$handler->instance_form_before_set_data()		$handler->instance_form_before_set_data()
	$handler->instance_form_definition_after_data()		$handler->instance_form_definition_after_data()
	$handler->instance_form_validation()		$handler->instance_form_validation()
	$handler->instance_form_save()		$handler->instance_form_save($data)
	</code>		</code>


			The <code php>instance_form_save()</code> method must be called after the form was saved as the <code php>$data</code> parameter must have the <code php>id</code>attribute.

	On deletion of an instance or on deletion of the whole item call:		On deletion of an instance or on deletion of the whole item call:

Danielneis: fix typos

2019-10-31T13:57:38Z

fix typos

← Older revision		Revision as of 13:57, 31 October 2019
Line 41:		Line 41:
	The following callbacks should be used in form definition, definition_after_data, validation and after form submission:		The following callbacks should be used in form definition, definition_after_data, validation and after form submission:
	<code php>		<code php>
	$~~hander~~->instance_form_definition()		$handler->instance_form_definition()
	$~~hander~~->instance_form_before_set_data()		$handler->instance_form_before_set_data()
	$~~hander~~->instance_form_definition_after_data()		$handler->instance_form_definition_after_data()
	$~~hander~~->instance_form_validation()		$handler->instance_form_validation()
	$~~hander~~->instance_form_save()		$handler->instance_form_save()
	</code>		</code>

	On deletion of an instance or on deletion of the whole item call:		On deletion of an instance or on deletion of the whole item call:
	<code php>		<code php>
	$~~hander~~->delete_instance()		$handler->delete_instance()
	$~~hander~~->delete_all()		$handler->delete_all()
	</code>		</code>

Libertymoodle: /* Add See also */

2019-04-03T11:44:04Z

Add See also

← Older revision		Revision as of 11:44, 3 April 2019
Line 119:		Line 119:
	class provider implements \core_privacy\local\metadata\null_provider, \core_customfield\privacy\customfield_provider;		class provider implements \core_privacy\local\metadata\null_provider, \core_customfield\privacy\customfield_provider;
	</code>		</code>

			== See also ==

			MDL-64626 - Custom fields API (Moodle 3.7+) implementations and improvements

			MDL-57898 - Add custom field types plugin and course custom fields functionality

Marina.glancy: /* How to use custom fields */

2019-01-15T13:18:38Z

How to use custom fields

← Older revision		Revision as of 13:18, 15 January 2019
Line 23:		Line 23:
	$outputpage = new \core_customfield\output\management($handler);		$outputpage = new \core_customfield\output\management($handler);
	echo $output->render($outputpage);		echo $output->render($outputpage);
			</code>

			Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:
			<code php>
			handler::uses_categories()
			handler::generate_category_name()
			handler::config_form_definition() // For example, the course_handler adds "locked" and "visibility" settings that control who can edit or view the particular field.
			handler::setup_edit_page() // Sets page context/url/breadcrumb for the customfield/edit.php page, in some cases it must be overridden.
	</code>		</code>

Marina.glancy: /* Privacy API */

2019-01-15T13:03:47Z

Privacy API

← Older revision		Revision as of 13:03, 15 January 2019
Line 78:		Line 78:
	<code php>		<code php>
	$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');		$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');
	</code		</code>

	And they can use the following methods in the export/delete functions:		And they can use the following methods in the export/delete functions:

← Older revision		Revision as of 13:29, 14 July 2021
Line 13:		Line 13:
	Handler has protected constructor, to get a handler call create() method. Some areas may choose to return a singleton here:		Handler has protected constructor, to get a handler call create() method. Some areas may choose to return a singleton here:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$handler = HANDLERCLASS::create($itemid);		$handler = HANDLERCLASS::create($itemid);
	</syntaxhighlight>		</syntaxhighlight>
Line 19:		Line 19:
	Configuration page contents will be:		Configuration page contents will be:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$output = $PAGE->get_renderer('core_customfield');		$output = $PAGE->get_renderer('core_customfield');
	$outputpage = new \core_customfield\output\management($handler);		$outputpage = new \core_customfield\output\management($handler);
Line 26:		Line 26:

	Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:		Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:
	<~~code~~ php>		<syntaxhighlight lang="php">
	handler::uses_categories()		handler::uses_categories()
	handler::generate_category_name()		handler::generate_category_name()
Line 40:		Line 40:

	The following callbacks should be used in form definition, definition_after_data, validation and after form submission:		The following callbacks should be used in form definition, definition_after_data, validation and after form submission:
	<~~code~~ php>		<syntaxhighlight lang="php">
	$handler->instance_form_definition($mform)		$handler->instance_form_definition($mform)
	$handler->instance_form_before_set_data()		$handler->instance_form_before_set_data()
Line 49:		Line 49:


	The <~~code~~ php>instance_form_save()</syntaxhighlight> method must be called after the form was saved as the <~~code~~ php>$data</syntaxhighlight> parameter must have the <~~code~~ php>id</syntaxhighlight>attribute.		The <syntaxhighlight lang="php">instance_form_save()</syntaxhighlight> method must be called after the form was saved as the <syntaxhighlight lang="php">$data</syntaxhighlight> parameter must have the <syntaxhighlight lang="php">id</syntaxhighlight>attribute.

	On deletion of an instance or on deletion of the whole item call:		On deletion of an instance or on deletion of the whole item call:
	<~~code~~ php>		<syntaxhighlight lang="php">
	$handler->delete_instance()		$handler->delete_instance()
	$handler->delete_all()		$handler->delete_all()
Line 61:		Line 61:
	How custom fields are used depends entirely on the situation. The following handler methods will help you to retrieve custom fields values for the given instance(s):		How custom fields are used depends entirely on the situation. The following handler methods will help you to retrieve custom fields values for the given instance(s):

	<~~code~~ php>		<syntaxhighlight lang="php">
	$handler->export_instance_data()		$handler->export_instance_data()
	$handler->export_instance_data_object()		$handler->export_instance_data_object()
Line 68:		Line 68:

	Additional methods for advanced usage:		Additional methods for advanced usage:
	<~~code~~ php>		<syntaxhighlight lang="php">
	$handler->get_instance_data()		$handler->get_instance_data()
	$handler->get_instances_data()		$handler->get_instances_data()
Line 76:		Line 76:

	To retrieve the list of custom fields used in the given component/area/itemid you can use:		To retrieve the list of custom fields used in the given component/area/itemid you can use:
	<~~code~~ php>		<syntaxhighlight lang="php">
	$handler->get_categories_with_fields()		$handler->get_categories_with_fields()
	$handler->get_fields()		$handler->get_fields()
Line 85:		Line 85:

	This function will return all the custom fields for a given courseid:		This function will return all the custom fields for a given courseid:
	<~~code~~ php>		<syntaxhighlight lang="php">
	function get_course_metadata($courseid) {		function get_course_metadata($courseid) {
	$handler = \core_customfield\handler::get_handler('core_course', 'course');		$handler = \core_customfield\handler::get_handler('core_course', 'course');
Line 108:		Line 108:

	Plugins that store user information in custom fields should link subsystem in their get_metadata:		Plugins that store user information in custom fields should link subsystem in their get_metadata:
	<~~code~~ php>		<syntaxhighlight lang="php">
	$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');		$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');
	</syntaxhighlight>		</syntaxhighlight>

	And they can use the following methods in the export/delete functions:		And they can use the following methods in the export/delete functions:
	<~~code~~ php>		<syntaxhighlight lang="php">
	use core_customfield\privacy\provider as customfield_provider;		use core_customfield\privacy\provider as customfield_provider;

Line 123:		Line 123:

	In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations:		In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations:
	<~~code~~ php>		<syntaxhighlight lang="php">
	customfield_provider::get_customfields_configuration_contexts()		customfield_provider::get_customfields_configuration_contexts()
	customfield_provider::delete_customfields_configuration()		customfield_provider::delete_customfields_configuration()
Line 135:		Line 135:

	Except for common [[Plugin files]] and tests the following classes must be present in customfield plugins (in respective autoloaded locations):		Except for common [[Plugin files]] and tests the following classes must be present in customfield plugins (in respective autoloaded locations):
	<~~code~~ php>		<syntaxhighlight lang="php">
	namespace customfield_<PLUGINNAME>;		namespace customfield_<PLUGINNAME>;
	class field_controller extends \core_customfield\field_controller;		class field_controller extends \core_customfield\field_controller;