Database fields

Important: This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date. Why not view this page on the new site and help us to migrate more content to the new site!

Introduction

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

File structure

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 five 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.
• version.php - contains version information about the field type.
• datafield_url.php - contains the language strings used in the url field type. You will need to create the same file structure as the other field types ('mod/data/field/url/lang/en/'). All of the normal field types keep their language definitions in the general language file ('mod/data/lang/en/data.php'), but I recommend keeping your language strings separate where you can.
• 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. To add an icon for your field you need to include this file in 'mod/data/pix/field/'. You will see icons for all the other fields in this directory.

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
function get_content_value($value) // Useful if the info stored in the database if different from the info that ends up being presented to the user

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.

You can also overwrite the default data_field_base::$priority field if your field type should be highly ranked in global search search results. This field is used specify which is the priority of this field type in relation to other field types.

Example

This is an example of a custom field type for phone numbers. I have tried to keep this example as simple as possible while still providing enough detail that you can create your own with minimal trouble.

• Phone number field type.