Custom fields
Custom fields allow you to create field types to be used for custom fields. Instances of these field types can be added to the respective areas that implement Custom fields API. Currently in Moodle core only courses implement this API, however custom fields are also used in addon plugins for other areas. For example, if you want to display radio buttons on the course edit page, then you can add an instance of a radio custom field plugin to the Course custom fields configuration.
File structure
Custom field plugins are located in the /customfield/field directory. A plugin should not include any custom files outside of it's own plugin folder.
Each plugin is in a separate subdirectory and consists of a number of mandatory files and any other files the developer is going to use.
Some of the important files are described below. See the common plugin files documentation for details of other files which may be useful in your plugin.
View an example directory layout for the customfield_checkbox plugin.
customfield/field/checkbox
├── classes
│ ├── data_controller.php
│ ├── field_controller.php
│ └── privacy
│ └── provider.php
├── lang
│ └── en
│ └── customfield_checkbox.php
└── version.php
A custom field plugin requires two controller classes:
- a field controller, which describes the field itself; and
- a data controller, which describes with interface within the context of the instance (i.e. course).
Field Controller
The field controller defines the available configuration options that an administrator can select within the user interface to configure the field.
Examples might include the prompt to show alongside the custom field element, and whether the element is required.
The class must be named field_controller within your plugin's namespace (for example customfield_myfield) and must extend the \core_customfield\field_controller class.
Field configuration controller
File path: /classes/field_controller.php
View example
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Field configuration for the plugintype_pluginname plugin.
*
* @package plugintype_pluginname
* @copyright Year, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace customfield_myfield;
class field_controller extends \core_customfield\field_controller {
/** @var string Plugin type */
const TYPE = 'radio';
/**
* Add fields for editing a checkbox field.
*
* @param \MoodleQuickForm $mform
*/
public function config_form_definition(\MoodleQuickForm $mform) {
$mform->addElement(
'header',
'header_specificsettings',
get_string('specificsettings', 'customfield_checkbox')
);
$mform->setExpanded('header_specificsettings', true);
$mform->addElement(
'selectyesno',
'configdata[checkbydefault]',
get_string('checkedbydefault', 'customfield_checkbox')
);
$mform->setType('configdata[checkbydefault]', PARAM_BOOL);
}
}
The \core_customfield\field_controller class is an abstract class and defines a number of functions which you can choose to override. At a minimum, the following two items are required:
- the
TYPEconstant to match the name of the plugin; and - the
config_form_definition()function.
All element names must be in the format $configdata[configname] for values to be saved, for example configdata[cfgdefault].
In addition to these requried a functions a number of other functions exist and can be overridden, with the following being particularly useful:
config_form_validation($formdata, $formfiles)- control the form validation
Details of all available functions can be found in the \core_customfield\field_controller class defined in /customfield/classes/field_controller.php.
Data Controller
The data controller defines the user interface that teachers use within the course edit form.
The class must be named data_controller within your plugin's namespace (for example customfield_myfield) and must extend the \core_customfield\data_controller class.
Field usage controller
File path: /classes/data_controller.php
View example
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Field usage controller for the plugintype_pluginname plugin.
*
* @package plugintype_pluginname
* @copyright Year, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace customfield_checkbox;
class data_controller extends \core_customfield\data_controller {
/**
* Return the name of the field where the information is stored
* @return string
*/
public function datafield(): string {
return 'intvalue';
}
/**
* Add fields for editing a checkbox 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();
// If checkbox is required (i.e. "agree to terms") then use 'checkbox' form element.
// The advcheckbox element cannot be used for required fields because advcheckbox elements always provide a value.
$isrequired = $field->get_configdata_property('required');
$mform->addElement($isrequired ? 'checkbox' : 'advcheckbox', $elementname, $this->get_field()->get_formatted_name());
$mform->setDefault($elementname, $config['checkbydefault']);
$mform->setType($elementname, PARAM_BOOL);
if ($isrequired) {
$mform->addRule($elementname, null, 'required', null, 'client');
}
}
/**
* Returns the default value as it would be stored in the database (not in human-readable format).
*
* @return mixed
*/
public function get_default_value() {
return $this->get_field()->get_configdata_property('checkbydefault') ? 1 : 0;
}
/**
* Returns value in a human-readable format
*
* @return mixed|null value or null if empty
*/
public function export_value() {
$value = $this->get_value();
return $value ? get_string('yes') : get_string('no');
}
}
The \core_customfield\data_controller class is an abstract class and defines a number of functions which you can choose to override. At a minimum, the following two items are required:
- the
datafield(): stringfunction; and - the
instance_form_definition()function.
datafield()
The datafield() function returns an enumerated string and describes which database field the data for the custom field is stored in. The possible options are:
intvalue- can store integer values, this field is indexeddecvalue- can store decimal valuesshortcharvalue- can store character values up to 255 characters long, this field is indexedcharvalue- can store character values up to 1333 characters long, this field is not indexedvalue- can store character values of unlimited length ("text" field in the db)
instance_form_definition()
The instance_form_definition() function adds any required field elements that are displayed on the instance editing page (i.e. on the course settings page).