Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Portfolio plugins: Difference between revisions

From MoodleDocs
Line 22: Line 22:


The formats this plugin can support.  At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.
The formats this plugin can support.  At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX.


===Class methods===
===Class methods===

Revision as of 15:39, 9 July 2008

Introduction

For the purposes of this tutorial, it will be assumed you want to create a plugin called "foo"

Create a new directory in portfolio/type/ with the name of your plugin, for example, portfolio/type/foo.

You need to create the standard version.php in here that you would normally create for most other plugin types in Moodle.

You can also provide a db/ directory with an install.xml and upgrade.php along the same lines. These are optional.

Create a lib.php inside this directory.

Now we're going to create the necessary subclass to make our plugin work. It must be called portfolio_plugin_foo and directly extend portfolio_plugin_base.

Read the phpdoc documentation for the base class, portfolio_plugin_base for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.

Methods you must override

Static functions

supported_types

The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.

The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX.

Class methods

.. none currently

Methods you can override

Static functions

sanity_check

If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.

has_admin_config

If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config.

has_user_config

If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config

has_export_config

If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form and get_export_summary

get_export_summary

If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen.

set_export_config

TODO maybe this can just stay in the parent class and not be needed

user_config_form

If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. TODO: it would be good to support also some sort of validation too.

get_allowed_config

Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.

Class methods

admin_config_form

This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config.

export_config_form

If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. TODO: it wouild be good to support some sort of validation too.

allows_multiple

By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.

steal_control

There is a point during the export process, where a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plguins that need the user go to log into a remote system and grant an application access. It could be also used at this point for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue.

get_allowed_user_config

Because of most of the setting and getting of user entered configuration data happens in the parent class, with no need to be overridden in the subclass, this method is responsible for letting the parent class know what fields are allowed.

Methods you shouldn't really override

Static functions

create_instance

Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.

Class methods

__construct

Constructor for the plugin. Subclasses don't need to override this.

set_config

Sets config options for the instance. Saves back to database. Valid values are checked, as per get_allowed_config.

get_config

Returns the config value for the given key.

get_user_config

Returns the config value for the given key and the given user.

set_user_config

Sets user config. Saves back to database. Valid values are checked, as per get_allowed_user_config.

get

Generic getter.

set

Generic setter. Does not save back to database. You must call save() at the end of setting values.

save

Saves data stored in the object back to the database and resets the dirty flag.

delete

Deletes this instance and all configuration data associated with it completely from the database


And that's it. Your new plugin will be installed next time you visit admin/index.php, and you'll be able to start configuring it.