Course Custom 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

This plugin type allows you to add course custom field types of which instances can be added to a course. For example, if you want to display radio buttons on the course edit page, then create a radio custom course field plugin, then create an instance of it.

Default Custom Fields

Moodle supports five default course custom fields field plugins:

checkbox
datetime
menu
text
textarea

Required Files

version.php
language file e.g lang/en/customfield_radio.php
classes/data_controller.php
classes/field_controller.php

The Class Files

The two required files in the classes folder must follow the autoloading and namespacing rules e.g. customfield_radio.

Field Controller

This class is to define the custom field configuration when the user is creating the field. The class must be called field_controller (for autoloading) must extend the \core_customfield\field_controller class.

The class must define a TYPE constant e.g.

/**
* Plugin type
*/
const TYPE = 'radio';

config_form_definition($mform)

The only method that must be overridden is config_form_definition() which has a Moodle form passed in as the parameter to which it must attached form elements. Not that for the element values to be saved, the element names must be in the format configdata[configname] e.g. configdata[cfgdefault].

/**
* Add fields for editing a radio field in admin.
*
* @param \MoodleQuickForm $mform
*/
public function config_form_definition(\MoodleQuickForm $mform) {
	$mform->addElement('header', 'header_oursettings', get_string('oursettings', 'customfield_radio'));
	$mform->setExpanded('header_oursettings', true);

	$mform->addElement('text', 'configdata[cfgquestion]', get_string('getquestionprompt', 'customfield_radio'));
	$mform->setType('configdata[cfgquestion]', PARAM_TEXT);
	$mform->addRule('configdata[cfgquestion]', null, 'maxlength', 150, 'client');
	$mform->addRule('configdata[cfgquestion]', null, 'required', null, 'client');

	$radioarray=array();
	$radioarray[] = $mform->createElement('radio', 'configdata[cfgdefault]', '', get_string('yes'), 1);
	$radioarray[] = $mform->createElement('radio', 'configdata[cfgdefault]', '', get_string('no'), 0);
	$mform->addGroup($radioarray, 'cfgradioar', get_string('defaultprompt', 'customfield_radio'), array(' '), false);
	$mform->setDefault('configdata[cfgdefault]', 0);
}

There is another function that is useful to be defined.

config_form_validation($formdata, $formfiles)

This function is used to validate the form values from config_form_definition(). It has the submitted form data and files passed in a parameters.

/**
* Validate the data on the field configuration form
*
* @param array $data from the add/edit profile field form
* @param array $files
* @return array associative array of error messages
*/
public function config_form_validation(array $data, $files = array()) : array {
	$errors = parent::config_form_validation($data, $files);

	if ($data['configdata']['uniquevalues']) {
		$errors['configdata[uniquevalues]'] = get_string('nouniqueallowed', 'customfield_radio');
	}

	return $errors;
}

Please see the \core_customfield\field_controller class defined in /customfield/classes/field_controller.php for other functions.

Data Controller

The data controller is the class that deals with the UI in the course edit form. It must be called data_controller (for autoloading) and must extend the \core_customfield\data_controller class. It must override the following methods:

datafield()

Should return the name of the field in the db table {customfield_data} where the data is stored and must be one of the following:

intvalue - can store integer values, this field is indexed
decvalue - can store decimal values
shortcharvalue - can store character values up to 255 characters long, this field is indexed
charvalue - can store character values up to 1333 characters long, this field is not indexed
value - can store character values of unlimited length ("text" field in the db)

/**
* Return the name of the field where the information is stored
* @return string
*/
public function datafield() : string {
	return 'intvalue';
}

instance_form_definition($mform)

Adds a field element to the instance course edit form. The form is passed into this function.

/**
* Add fields for editing a radio field.
*
* @param \MoodleQuickForm $mform
*/
public function instance_form_definition(\MoodleQuickForm $mform) {
	$field = $this->get_field();
	$config = $field->get('configdata');
	$elementname = $this->get_form_element_name();

	$radioarray=array();
	$radioarray[] = $mform->createElement('radio', $elementname, '', get_string('yes'), 1);
	$radioarray[] = $mform->createElement('radio', $elementname, '', get_string('no'), 0);
	$mform->addGroup($radioarray, 'cfgradioar', $config['cfgquestion'], array(' '), false);
	$mform->setDefault($elementname, $config['cfgdefault']);
	$mform->setType($elementname, PARAM_INT);
}

Please see the \core_customfield\data_controller class defined in /customfield/classes/data_controller.php for other functions.

Documentation