Communication Between Components - Revision history

Devdocsbot: Protected "Communication Between Components": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-05-06T07:26:57Z

Protected "Communication Between Components": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 07:26, 6 May 2022
(No difference)

Andrewnicols: Note migration to new docs

2022-04-11T03:52:06Z

Note migration to new docs

← Older revision		Revision as of 03:52, 11 April 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/general/development/policies/component-communication}}
	== Components ==		== Components ==

Goodlyvibes: /* Subsystems */

2020-10-10T14:27:30Z

Subsystems

← Older revision		Revision as of 14:27, 10 October 2020
Line 17:		Line 17:
	=== Subsystems ===		=== Subsystems ===

	Subsystems are groups of related functions and classes that are part of core, but are logically grouped together. Often they are tied to a particular feature in Moodle, and sometimes can be disabled/enabled via a single config setting - but the code is never removed. It is safe to call core subsystems from anywhere in Moodle - but the functions may return an error to indicate that a feature has been disabled. Each core subsystem has a defined location where ~~it’s~~ code is grouped together. As of Moodle 3.1 there are 66 subsystems in core and the comprehensive list can be found here:		Subsystems are groups of related functions and classes that are part of core, but are logically grouped together. Often they are tied to a particular feature in Moodle, and sometimes can be disabled/enabled via a single config setting - but the code is never removed. It is safe to call core subsystems from anywhere in Moodle - but the functions may return an error to indicate that a feature has been disabled. Each core subsystem has a defined location where its code is grouped together. As of Moodle 3.1 there are 66 subsystems in core and the comprehensive list can be found here:

	core_component::fetch_subsystems()		core_component::fetch_subsystems()


	=== Plugins ===		=== Plugins ===
Line 98:		Line 97:
	=== Javascript Modules (AMD) ===		=== Javascript Modules (AMD) ===

	It is possible through the Javascript loader to load an AMD module from any component and call ~~it’s~~ functions. This is a form of inter-component communication and must obey the strict rules for which components AMD modules can be loaded from.		It is possible through the Javascript loader to load an AMD module from any component and call its functions. This is a form of inter-component communication and must obey the strict rules for which components AMD modules can be loaded from.

	=== get_string ===		=== get_string ===
Line 178:		Line 177:
	* There is a real event occurring at the point you need to execute some additional code.		* There is a real event occurring at the point you need to execute some additional code.
	* You are not cheating the inter-component communication rules.		* You are not cheating the inter-component communication rules.
	* You do not need to modify ~~and~~ of the data related to the event.		* You do not need to modify any of the data related to the event.

	Otherwise add a new callback and execute for each plugin implementing it, using ''get_plugins_with_function()''		Otherwise add a new callback and execute for each plugin implementing it, using ''get_plugins_with_function()''

Marina.glancy: /* FAQ */

2017-05-22T01:22:39Z

FAQ

← Older revision		Revision as of 01:22, 22 May 2017
Line 128:		Line 128:
	== FAQ ==		== FAQ ==

	Q: So how does plugin X call a function from plugin Y if they don’t depend on each other?		'''Q: So how does plugin X call a function from plugin Y if they don’t depend on each other?'''

	A: By communicating through a core API.		A: By communicating through a core API.


	Q: What? Really?		'''Q: What? Really?'''

	A: Anytime one plugin wants to communicate to one other specific plugin - it’s better to create a core API and channel all communication through that API. For example “assignment online text” uses the “Editor API” to add a rich text field to the form. It does not directly add an instance of “Atto” to the form. This allows either plugin to be replaced by a different, (hopefully better) plugin without changing the API or the other plugin. Remember, any plugin in Moodle is optional and may be removed in the future.		A: Anytime one plugin wants to communicate to one other specific plugin - it’s better to create a core API and channel all communication through that API. For example “assignment online text” uses the “Editor API” to add a rich text field to the form. It does not directly add an instance of “Atto” to the form. This allows either plugin to be replaced by a different, (hopefully better) plugin without changing the API or the other plugin. Remember, any plugin in Moodle is optional and may be removed in the future.


	Q: How do I know if there is an API I can already use?		'''Q: How do I know if there is an API I can already use?'''

	A: ~~Major~~ core APIs are listed [[Core_APIs\|here]] ~~but the only way to know for sure is to grep the code for component_callback or plugins_with_function and hope for the best~~.		A: Existing callbacks are listed [[Callbacks\|here]], major core APIs are listed [[Core_APIs\|here]].


	Q: Can I change the data provided to a component_callback and maintain backwards compatibility.		'''Q: Can I change the data provided to a component_callback and maintain backwards compatibility.'''

	A: No it is not possible. You must implement a second callback with a new name.		A: No it is not possible. You must implement a second callback with a new name.


	Q: Can I control the order in which ~~component_callbacks~~ are executed?		'''Q: Can I control the order in which plugins callbacks are executed?'''

	A: No it is not possible.		A: No it is not possible.


	Q: Can I find all the plugins implementing a ~~component~~ callback?		'''Q: Can I find all the plugins implementing a callback?'''

	A: ~~Only with~~ grep ~~and hope for~~ the ~~best.~~		A: You can grep the code or create a test script that executes ''get_plugins_with_function()''


	Q: How can I ensure the name for my ~~component~~ callback is unique?		'''Q: How can I ensure the name for my new callback is unique?'''

	A: ~~Only with grep and hope for the best~~. Consider prefixing with the component name the callback is defined in - but existing code does not do this much.		A: Check [[Callbacks\|list of existing callbacks]]. Consider prefixing with the component name the callback is defined in - but existing code does not do this much.


	Q: Will my ~~component_callback~~ function be called even if my plugin is disabled?		'''Q: Will my callback function be called even if my plugin is disabled?'''

	A: Yes - you must manually check if your own plugin is disabled before responding to a component callback.		A: Yes - you must manually check if your own plugin is disabled before responding to a component callback.


	Q: I looked, there is no existing API I can use. How do I get a new one added to core?		'''Q: I looked, there is no existing API I can use. How do I get a new one added to core?'''

	A: Create a tracker issue, post a patch (with unit tests) and explain your use case.		A: Create a tracker issue, post a patch (with unit tests) and explain your use case.


	Q: When should I create a callback and when should I use event observers?		'''Q: When should I create a callback and when should I use event observers?'''

	A: Event observers should not be added to facilitate plugin communication. They are about notifying the system that a real event occurred. Use an event observer only if:		A: Event observers should not be added to facilitate plugin communication. They are about notifying the system that a real event occurred. Use an event observer only if:
Line 180:		Line 180:
	* You do not need to modify and of the data related to the event.		* You do not need to modify and of the data related to the event.

	Otherwise add a new ~~component_callback.~~		Otherwise add a new callback and execute for each plugin implementing it, using ''get_plugins_with_function()''


	Q: Can I use one of the broadcast functions to provide a callback to some plugin types, but not all of them?		'''Q: Can I use one of the broadcast functions to provide a callback to some plugin types, but not all of them?'''

	A: ~~No, the broadcast function (component_callback) should only ever be used~~ to ~~broadcast to all plugins of one specific type, or~~ all ~~plugins~~. Previously assumptions have been made about which plugins should be able to respond to an API and they have almost always turned out wrong.		A: It is better to allow all plugin types. Previously assumptions have been made about which plugins should be able to respond to an API and they have almost always turned out wrong.


	Q: Can create an API with ~~component_callback~~ that supports multiple stages?		'''Q: Can create an API with callbacks that supports multiple stages?'''

	A: Not easily. You must create a separate ~~component_callback~~ for each stage and hope that consumers of your API create the correct function for each stage. An alternative is to create a ~~component_callback~~ that is expected to be returned an instance of an abstract class which defines your API.		A: Not easily. You must create a separate callback for each stage and hope that consumers of your API create the correct function for each stage. An alternative is to create a callback that is expected to be returned an instance of an abstract class which defines your API.


	Q: Global functions are bad. Can I implement a ~~component_callback~~ in a class instead?		'''Q: Global functions are bad. Can I implement a callback in a class instead?'''

	A: No. Sorry.		A: No. Sorry.

Marina.glancy: /* Callback methods (component_callback, get_plugins_with_function…) */

2017-05-22T01:09:19Z

Callback methods (component_callback, get_plugins_with_function…)

← Older revision		Revision as of 01:09, 22 May 2017
Line 124:		Line 124:
	The most common way (but not the only way) to implement a callback is using the “component_callback()” function. This function works by looping over the installed plugins and calling a function from each plugin based on appending the component name to the supplied function name. It then expects the function to be defined either in the plugins lib.php file, or in an autoloaded location (but not in a class!).		The most common way (but not the only way) to implement a callback is using the “component_callback()” function. This function works by looping over the installed plugins and calling a function from each plugin based on appending the component name to the supplied function name. It then expects the function to be defined either in the plugins lib.php file, or in an autoloaded location (but not in a class!).

	[[Callbacks\|List of callbacks in Moodle]		[[Callbacks\|List of callbacks in Moodle]]

	== FAQ ==		== FAQ ==

Marina.glancy: /* Callback methods (component_callback, get_plugins_with_function…) */

2017-05-22T01:09:08Z

Callback methods (component_callback, get_plugins_with_function…)

← Older revision		Revision as of 01:09, 22 May 2017
Line 123:		Line 123:

	The most common way (but not the only way) to implement a callback is using the “component_callback()” function. This function works by looping over the installed plugins and calling a function from each plugin based on appending the component name to the supplied function name. It then expects the function to be defined either in the plugins lib.php file, or in an autoloaded location (but not in a class!).		The most common way (but not the only way) to implement a callback is using the “component_callback()” function. This function works by looping over the installed plugins and calling a function from each plugin based on appending the component name to the supplied function name. It then expects the function to be defined either in the plugins lib.php file, or in an autoloaded location (but not in a class!).

			[[Callbacks\|List of callbacks in Moodle]

	== FAQ ==		== FAQ ==

Damyon: /* General rules for inter-component communications */

2017-01-31T01:21:41Z

General rules for inter-component communications

← Older revision		Revision as of 01:21, 31 January 2017
Line 67:		Line 67:
	* Any component is allowed to communicate with itself.		* Any component is allowed to communicate with itself.
	* It is allowed to communicate with another component if the calling component “depends” on the other component (see description of dependencies above).		* It is allowed to communicate with another component if the calling component “depends” on the other component (see description of dependencies above).
			* Not shown in the diagram - but the same rules apply to sub-plugins. They can communicate with their parent and any plugin that they explicitly (version.php) depend on.
	* All other inter-component communications are forbidden.		* All other inter-component communications are forbidden.

Damyon: /* FAQ */

2017-01-19T08:17:12Z

FAQ

← Older revision		Revision as of 08:17, 19 January 2017
Line 137:		Line 137:
	Q: How do I know if there is an API I can already use?		Q: How do I know if there is an API I can already use?

	A: Major core APIs are listed here but the only way to know for sure is to grep the code for component_callback or plugins_with_function and hope for the best.		A: Major core APIs are listed [[Core_APIs\|here]] but the only way to know for sure is to grep the code for component_callback or plugins_with_function and hope for the best.

Damyon: /* Webservice API */

2017-01-19T02:12:41Z

Webservice API

← Older revision		Revision as of 02:12, 19 January 2017
Line 218:		Line 218:
	This is not really an API, it is just a listing of all the functions in the external API in our plugins db/services.php file. This allows all these functions to be called from AJAX or webservices clients like the Mobile App.		This is not really an API, it is just a listing of all the functions in the external API in our plugins db/services.php file. This allows all these functions to be called from AJAX or webservices clients like the Mobile App.

	~~{{Note\|~~This page was created from a google doc. To edit the images in this page - re-export them from the original document here: https://docs.google.com/document/d/1Z-vRWztT05bsb9b5KbBpLRP26oa3KTx3thB52_BW5VY/edit#heading=h.ardt51j6brj1}}		== Editing images in this doc page ==
			This page was created from a google doc. To edit the images in this page - re-export them from the original document here: https://docs.google.com/document/d/1Z-vRWztT05bsb9b5KbBpLRP26oa3KTx3thB52_BW5VY/edit#heading=h.ardt51j6brj1

Damyon: /* FAQ */

2017-01-19T02:11:46Z

FAQ

← Older revision		Revision as of 02:11, 19 January 2017
Line 128:		Line 128:

	A: By communicating through a core API.		A: By communicating through a core API.


	Q: What? Really?		Q: What? Really?

	A: Anytime one plugin wants to communicate to one other specific plugin - it’s better to create a core API and channel all communication through that API. For example “assignment online text” uses the “Editor API” to add a rich text field to the form. It does not directly add an instance of “Atto” to the form. This allows either plugin to be replaced by a different, (hopefully better) plugin without changing the API or the other plugin. Remember, any plugin in Moodle is optional and may be removed in the future.		A: Anytime one plugin wants to communicate to one other specific plugin - it’s better to create a core API and channel all communication through that API. For example “assignment online text” uses the “Editor API” to add a rich text field to the form. It does not directly add an instance of “Atto” to the form. This allows either plugin to be replaced by a different, (hopefully better) plugin without changing the API or the other plugin. Remember, any plugin in Moodle is optional and may be removed in the future.


	Q: How do I know if there is an API I can already use?		Q: How do I know if there is an API I can already use?

	A: Major core APIs are listed here but the only way to know for sure is to grep the code for component_callback or plugins_with_function and hope for the best.		A: Major core APIs are listed here but the only way to know for sure is to grep the code for component_callback or plugins_with_function and hope for the best.


	Q: Can I change the data provided to a component_callback and maintain backwards compatibility.		Q: Can I change the data provided to a component_callback and maintain backwards compatibility.

	A: No it is not possible. You must implement a second callback with a new name.		A: No it is not possible. You must implement a second callback with a new name.


	Q: Can I control the order in which component_callbacks are executed?		Q: Can I control the order in which component_callbacks are executed?

	A: No it is not possible.		A: No it is not possible.


	Q: Can I find all the plugins implementing a component callback?		Q: Can I find all the plugins implementing a component callback?

	A: Only with grep and hope for the best.		A: Only with grep and hope for the best.


	Q: How can I ensure the name for my component callback is unique?		Q: How can I ensure the name for my component callback is unique?

	A: Only with grep and hope for the best. Consider prefixing with the component name the callback is defined in - but existing code does not do this much.		A: Only with grep and hope for the best. Consider prefixing with the component name the callback is defined in - but existing code does not do this much.


	Q: Will my component_callback function be called even if my plugin is disabled?		Q: Will my component_callback function be called even if my plugin is disabled?

	A: Yes - you must manually check if your own plugin is disabled before responding to a component callback.		A: Yes - you must manually check if your own plugin is disabled before responding to a component callback.


	Q: I looked, there is no existing API I can use. How do I get a new one added to core?		Q: I looked, there is no existing API I can use. How do I get a new one added to core?

	A: Create a tracker issue, post a patch (with unit tests) and explain your use case.		A: Create a tracker issue, post a patch (with unit tests) and explain your use case.


	Q: When should I create a callback and when should I use event observers?		Q: When should I create a callback and when should I use event observers?
Line 169:		Line 178:

	Otherwise add a new component_callback.		Otherwise add a new component_callback.


	Q: Can I use one of the broadcast functions to provide a callback to some plugin types, but not all of them?		Q: Can I use one of the broadcast functions to provide a callback to some plugin types, but not all of them?

	A: No, the broadcast function (component_callback) should only ever be used to broadcast to all plugins of one specific type, or all plugins. Previously assumptions have been made about which plugins should be able to respond to an API and they have almost always turned out wrong.		A: No, the broadcast function (component_callback) should only ever be used to broadcast to all plugins of one specific type, or all plugins. Previously assumptions have been made about which plugins should be able to respond to an API and they have almost always turned out wrong.


	Q: Can create an API with component_callback that supports multiple stages?		Q: Can create an API with component_callback that supports multiple stages?

	A: Not easily. You must create a separate component_callback for each stage and hope that consumers of your API create the correct function for each stage. An alternative is to create a component_callback that is expected to be returned an instance of an abstract class which defines your API.		A: Not easily. You must create a separate component_callback for each stage and hope that consumers of your API create the correct function for each stage. An alternative is to create a component_callback that is expected to be returned an instance of an abstract class which defines your API.


	Q: Global functions are bad. Can I implement a component_callback in a class instead?		Q: Global functions are bad. Can I implement a component_callback in a class instead?