Revision as of 06:42, 19 April 2013

Moodle hooks/features (Specification for 2.6)

Summary

Allow plugins to substitute or extend some core code where change is not big enough to create a new plugin type but we want to allow plugins interactions. Create management UI where admin can see the list of all available hooks/features definitions and available implementations, enable/prioritise implementations.

Current workarounds

Events system. The core notifies whoever wants to listen to it about something that happens. Disadvantage: one-way communication, no feedback.

Defining functions in /plugindir/lib.php with the name <pluginname>_<hookname> and querying all plugins if somebody implements function and/or list of plugins implementing it. Disadvantage: functions must be defined in lib.php therefore they are always included (performance loss); no UI to configure if only one plugin can implement feature; difficult for developers because they don't know if they can or how they can implement a hook.

$CFG variables. Disadvantage: they should be used for settings and not for including the 3rd party code

Creating a new plugin type. Disadvantage: very long process, involves lots of documentation, creating lots of strings and UI, may be available in major releases only. Also not applicable for minor features.

Implementation

All hooks/features definitions are stored in /db/ folder (of core or plugin). It's best to implement definitions as interfaces or parent classes, this way PHP will make sure that implementations exactly match the definition.

All implementations are also stored in plugin in particular place. Maybe folder /hooks/ or /features/ or specific file(s) name(s).

The definitions and implementations are analysed during install/upgrade only. They are stored in DB, so we include files when and only when we need them.

There is an administrative management interface that allows to review all available implementations, prioritise and/or disable them. By default the implementations are disabled but admin receives a notification during install/upgrade that new implementations are available and may be enabled.

Use cases

Course search: we have quite primitive course search algorithm in core. Some other plugin may implement search with sorting by relevance, analysing tags, going through attached pdf files, etc. Hook implementation returns the list of courses and core goes back to the core/theme renderers to display this list

Global search: similar to above but result will be list of title+url+abstract

Front page: We have $CFG->customfrontpageinclude for including a file displaying frontpage contents. It could be also hook/feature

Extending mimetypes list

Extending licenses list

Logging (instead of using events functionality)

Adding fields to the standard forms. This may be a comprehensive feature that includes several functions - adding fields, validation, processing.

Hooking into backup/restore process. Example when plugin wants to add some field to the course, for example "classroom", and make sure that it is backed up/restored.

@@ Line 1: / Line 1: @@
-<pre>
+= Moodle hooks/features (Specification for 2.6) =
-(15:23:58) Marina: I have some suggestion for 2.6 that actually can work well with logging. At the moment we have events system which is one-way - the core notifies whoever wants to listen to it about something that happens and it is proposed to be used for logging. But how about we implement also "feature" or "hook" system where some code in core may be substituted or extended with other plugins.
-(15:24:15) Marina: It is sort of mini-plugin system for all those small actions that don't need a separate plugin type. Examples where I can also see it useful - course search, global search, frontpage contents/redirection, etc.
+== Summary ==
-(15:24:38) Marina: Every time we need such sort of thing we introduce new $CFG variable and it's confusing and unmanageable
-(15:24:58) Marina: There will be just a certain flexible interface and management page. Basically not so much from the core but plugins can go nuts.
+Allow plugins to substitute or extend some core code where change is not big enough to create a new plugin type but we want to allow plugins interactions. Create management UI where admin can see the list of all available hooks/features definitions and available implementations, enable/prioritise implementations.
-(15:25:47) Martin Dougiamas: like wordpress and drupal?
-(15:25:52) Marina: yes
+== Current workarounds ==
-(15:26:22) Martin Dougiamas: it would be good, but I don't quit understand what "extend" code from core means
-(15:26:28) Marina: I don't know about wordpress but in drupal it's not very manageable
+* Events system. The core notifies whoever wants to listen to it about something that happens. Disadvantage: one-way communication, no feedback.
-(15:26:36) Marina: i.e. extend a form
-(15:26:43) Marina: or contents of some page
+* Defining functions in /plugindir/lib.php with the name <pluginname>_<hookname> and querying all plugins if somebody implements function and/or list of plugins implementing it. Disadvantage: functions must be defined in lib.php therefore they are always included (performance loss); no UI to configure if only one plugin can implement feature; difficult for developers because they don't know if they can or how they can implement a hook.
-(15:27:20) Martin Dougiamas: flexibility often is a tradeoff with usability
-(15:27:28) Martin Dougiamas: need some more fleshed out use cases with examples
+* $CFG variables. Disadvantage: they should be used for settings and not for including the 3rd party code
-(15:28:00) Martin Dougiamas: I don't understand your examples above
-(15:28:49) Marina: we have quite primitive course search algorithm in core. Some other plugin may implement search with relevance, analysing tags, going through attached pdf files, etc
+* Creating a new plugin type. Disadvantage: very long process, involves lots of documentation, creating lots of strings and UI, may be available in major releases only. Also not applicable for minor features.
-(15:29:06) Marina: the same with global search
-(15:30:11) Marina: 3. We have $CFG->customfrontpageinclude for frontpage. It could be also hook/feature
+== Implementation ==
-(15:30:31) Marina: - these are all examples of features where only one alternative implementation can be chosen
-(15:30:59) Martin Dougiamas: Usually we just make new plugin types
+* All hooks/features definitions are stored in /db/ folder (of core or plugin). It's best to implement definitions as interfaces or parent classes, this way PHP will make sure that implementations exactly match the definition.
-(15:31:40) Marina: yes, or $CFG variables
-(15:32:08) Marina: ok, I'll try to find more examples and write here
+* All implementations are also stored in plugin in particular place. Maybe folder /hooks/ or /features/ or specific file(s) name(s).
-(15:32:15) Martin Dougiamas: With your model, would it basically just replace X lines of code (producing HTML) with a given function which produces it's own Y lines of HTML connecting to it's own code?
-(15:32:38) Marina: it's one of the use cases
+* The definitions and implementations are analysed during install/upgrade only. They are stored in DB, so we include files when and only when we need them.
-(15:32:45) Marina: but it does not have to be UI only
-(15:33:17) Marina: in case of search - we ask plugin to give us list of courses and we go back to usual renderers to display them
+* There is an administrative management interface that allows to review all available implementations, prioritise and/or disable them. By default the implementations are disabled but admin receives a notification during install/upgrade that new implementations are available and may be enabled.
-(15:34:01) Martin Dougiamas: I like the idea if it doesn't complicate normal code too much, and the hooks across Moodle are sort of consistently managed
-(15:34:29) Marina: yes, that's the main idea - to have the centralised management
+== Use cases ==
-(15:34:52) Marina: so admin can see the list of all available hooks and for each enable/disable available implementations
-(15:35:22) Marina: we just query each plugin or core on definitions and implementations it has during upgrade/install only
+* Course search: we have quite primitive course search algorithm in core. Some other plugin may implement search with sorting by relevance, analysing tags, going through attached pdf files, etc. Hook implementation returns the list of courses and core goes back to the core/theme renderers to display this list
-(15:35:34) Marina: and store the list in DB
-(15:35:53) Marina: so each time the hook needs to be called we include only necessary file
+* Global search: similar to above but result will be list of title+url+abstract
-(15:36:34) Marina: I can write some pre-spec in more details if there is an interest
-</pre>
+* Front page: We have $CFG->customfrontpageinclude for including a file displaying frontpage contents. It could be also hook/feature
+* Extending mimetypes list
+* Extending licenses list
+* Logging (instead of using events functionality)
+* Adding fields to the standard forms. This may be a comprehensive feature that includes several functions - adding fields, validation, processing.
+* Hooking into backup/restore process. Example when plugin wants to add some field to the course, for example "classroom", and make sure that it is backed up/restored.

Documentation

Hooks spec: Difference between revisions