Development:Database fields

Moodle's Database module has some predefined field types (text, date, URL, picture, etc), but you can customise this to create new field types. For example, you might like to create:

Discipline-specific field types

e.g. "Protein PDB code" - people can enter the PDB code for a protein, and then the display could (for example) include a 3D viewer for the protein structure, or link out to molecular databases.

Institution-specific field types

e.g. "library reference number" - people can enter a number into the field, and this is automatically turned into a direct link to your library webpages

Module-specific field types

e.g. "wiki page" - people see a drop-down list containing the names of pages in your wiki, and can choose which page this particular entry refers to

Basic concepts

To create a new field type in Moodle we need to create a new folder in /moodle/mod/data/field. Inside this folder will be PHP code telling Moodle:

1. What HTML to output when people are looking at a record in the database
2. What form fields to output when people are adding/editing a record in the database
3. What to do (what info to store) when someone submits the record-add/edit form
4. What form fields to output when the teacher is adding/editing an instance of the field
5. What to do (what info to store) when the teacher submits the field-add/edit form

The files

The best way to get an understanding of the plugin architecture is to look at an existing field type - I recommend you look at the URL field type, stored in /moodle/mod/data/field/url. There are three files:

• field.class.php - the most important file, this defines a PHP class which defines the majority of the data field's behaviour. See below for more detail on this.
• mod.html - contains a HTML "fragment" defining how the form fields will appear when the teacher is adding/editing an instance of the field.
• icon.gif - the icon to be displayed along with the field, as a visual cue to the teacher about what sort of data is stored in this field.

The PHP class

If you look at the file "field.class.php" for the URL field type you'll see that the class is named "data_field_url" and it is a subclass of "data_field_base". This is very important - the class "data_field_base" (defined in /moodle/mod/data/lib.php, by the way) defines some of the core behaviours without which your field will not work.

Your class's name should match the subfolder you have created. For example, if we're creating a new data type called "Tastiness", we want to create our plugin in a folder "tastiness" and the PHP class should be data_field_tastiness. The class should also define a class variable $type, which again should use the same name - in our example, we'd give it the value 'tastiness'. So the top of our field.class.php would look like this:

<?php 
class data_field_tastiness extends data_field_base {
   var $type = 'tastiness';

If you want to take an existing field type, duplicate it, and rename it to a new type (which you can modify later), this is all you need to do. You might like to try this (again, the URL field is a good one to start with) and see how it works.

The base class defines some simple behaviours which you can override in your subclass, to make the plugin do exactly what you want. For example:

function display_add_field($recordid=0) // Return some HTML for use when a user is adding/editing a record
function display_browse_field($recordid, $template) // Return some HTML for displaying a record
function update_content($recordid, $value, $name=) // Used when a user stores data for a record
function get_sort_sql($fieldname) // Specify SQL for how this field should be sorted

If you don't bother to specify these functions inside your new class, then the default behaviours specified by data_field_base will be used. Simply add these functions to your new class to make something different happen.

To be continued...