Skip to main content
Version: main (5.0)

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.

important

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.

Class naming

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
[path/to/plugintype]/pluginname/classes/field_controller.php
<?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 TYPE constant to match the name of the plugin; and
  • the config_form_definition() function.
Element names

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.

Class naming

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
[path/to/plugintype]/pluginname/classes/data_controller.php
<?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(): string function; 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 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)

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).

See Also