User profile fields: Difference between revisions
No edit summary |
(→define_validate_specific(): Added full stop.) |
||
(11 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
==Introduction== | ==Introduction== | ||
This plugin | This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it. | ||
==History== | ==History== | ||
User profile fields | User profile fields exist from Moodle 1.9 and support five default user profile field plugins: | ||
# | # checkbox | ||
# datetime | # datetime | ||
# menu | # menu | ||
# text | # text | ||
# textarea | # textarea | ||
== | |||
==File Structure== | |||
# Create a folder for your plugin in ''/user/profile/field/customprofilefieldplugin''. The folder name should contain only letters and numbers. | |||
# Create the following files and add them to customprofilefieldplugin: | |||
## ''lang/en/profilefield_customprofilefieldplugin.php'' - Language file, containing strings for user profile field. | |||
## ''define.class.php'' - Definition of the user profile field type will be added in this file. | |||
## ''field.class.php'' - Controls user profile field display, while editing or showing as user profile field. | |||
## ''version.php'' - Contains version information for customprofilefieldplugin. | |||
==Naming convention== | |||
# '''profilefield_''' is prefixed to the name of the user profile field plugin, for identifying the name of the plugin. | |||
# ''define.class.php'' should contain a class with a name that has '''profile_define_''' prefixed to the custom user profile field plugin name. | |||
# ''field.class.php'' should contain a class with a name that has '''profile_field_''' prefixed to the custom user profile field plugin name. | |||
# The language file should define a '''pluginname''' string as the name of the plugin. | |||
==Interface API== | |||
===define.class.php=== | |||
====define_form_specific()==== | |||
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type. | |||
<pre> | |||
function define_form_specific(&$form) { | |||
// select whether or not this should be checked by default | |||
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield')); | |||
$form->setDefault('defaultdata', 0); // defaults to 'no' | |||
$form->setType('defaultdata', PARAM_BOOL); | |||
} | |||
</pre> | |||
====define_validate_specific()==== | |||
Validate the data from the add/edit profile field form that is specific to the current data type. | |||
<pre> | |||
function define_validate_specific($data) { | |||
$errors = array(); | |||
// Make sure defaultdata is not false | |||
if ($data->defaultdata == false) { | |||
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield'); | |||
} | |||
return $errors; | |||
} | |||
</pre> | |||
====define_after_data==== | |||
Alter form based on submitted or existing data | |||
<pre> | |||
function define_after_data(&$form) { | |||
if (empty($data->defaultdata)) { | |||
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield')); | |||
} | |||
} | |||
</pre> | |||
====define_save_preprocess==== | |||
Pre-process data from the profile field form before it is saved. | |||
<pre> | |||
function define_save_preprocess($data) { | |||
if (empty($data->defaultdata)) { | |||
$data->defaultdata = NULL; | |||
} | |||
return $data; | |||
} | |||
</pre> | |||
===field.class.php=== | |||
====edit_field_add()==== | |||
Adds the profile field to the moodle form | |||
<pre> | |||
function edit_field_add(&$mform) { | |||
// Create form field | |||
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name)); | |||
if ($this->data == '1') { | |||
$checkbox->setChecked(true); | |||
} | |||
$mform->setType($this->inputname, PARAM_BOOL); | |||
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) { | |||
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client'); | |||
} | |||
} | |||
</pre> | |||
====display_data()==== | |||
Display the data for this field | |||
<pre> | |||
function display_data() { | |||
$options = new stdClass(); | |||
$options->para = false; | |||
$checked = intval($this->data) === 1 ? 'checked="checked"' : ''; | |||
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />'; | |||
} | |||
</pre> | |||
====edit_field_set_default()==== | |||
Sets the default data for the field in the form object | |||
<pre> | |||
function edit_field_set_default(&$mform) { | |||
if (!empty($default)) { | |||
$mform->setDefault($this->inputname, $this->field->defaultdata); | |||
} | |||
} | |||
</pre> | |||
====edit_validate_field()==== | |||
Validate the form field from profile page | |||
<pre> | |||
function edit_validate_field($usernew) { | |||
$errors = array(); | |||
if (isset($usernew->{$this->inputname})) { | |||
if ($usernew->{$this->inputname}['text'] === '') { | |||
$errors[$this->inputname] = 'error'; | |||
} | |||
} | |||
return $errors; | |||
} | |||
</pre> | |||
====edit_save_data_preprocess()==== | |||
Process the data before it gets saved in database | |||
<pre> | |||
function edit_save_data_preprocess($data, &$datarecord) { | |||
if (is_array($data)) { | |||
$datarecord->dataformat = $data['format']; | |||
$data = $data['text']; | |||
} | |||
return $data; | |||
} | |||
</pre> | |||
====edit_field_set_locked()==== | |||
HardFreeze the field if locked. | |||
<pre> | |||
function edit_field_set_locked(&$mform) { | |||
if (!$mform->elementExists($this->inputname)) { | |||
return; | |||
} | |||
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) { | |||
$mform->hardFreeze($this->inputname); | |||
$mform->setConstant($this->inputname, $this->data); | |||
} | |||
} | |||
</pre> | |||
===Common functions=== | |||
The following will need to be added to any files accessing the profile_ functions: | |||
<pre> | |||
require_once("$CFG->dirroot/user/profile/lib.php"); | |||
</pre> | |||
====profile_user_record($userid)==== | |||
Returns an object with the custom profile fields set for the given user | |||
====profile_save_data($usernew)==== | |||
Saves custom profile field data | |||
====profile_validation($usernew, $files)==== | |||
Validates custom user profile field | |||
==Template== | ==Template== | ||
[https://github.com/rajeshtaneja/userprofilefield user profile field template] | |||
==Database tables== | ==Database tables== | ||
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields: | |||
# user_info_field - Information for custom field added to user profile page. | |||
# user_info_data - Data added by user for the custom profile field | |||
==FAQ== | ==FAQ== | ||
===How to add custom user profile field=== | ===How to add custom user profile field=== | ||
Line 19: | Line 164: | ||
===Which form elements does moodle support=== | ===Which form elements does moodle support=== | ||
Refer [[Form_API]] for list of elements supported by moodle | Refer [[Form_API]] for list of elements supported by moodle | ||
[[Category:Plugins]] |
Latest revision as of 09:44, 26 March 2021
Introduction
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
History
User profile fields exist from Moodle 1.9 and support five default user profile field plugins:
- checkbox
- datetime
- menu
- text
- textarea
File Structure
- Create a folder for your plugin in /user/profile/field/customprofilefieldplugin. The folder name should contain only letters and numbers.
- Create the following files and add them to customprofilefieldplugin:
- lang/en/profilefield_customprofilefieldplugin.php - Language file, containing strings for user profile field.
- define.class.php - Definition of the user profile field type will be added in this file.
- field.class.php - Controls user profile field display, while editing or showing as user profile field.
- version.php - Contains version information for customprofilefieldplugin.
Naming convention
- profilefield_ is prefixed to the name of the user profile field plugin, for identifying the name of the plugin.
- define.class.php should contain a class with a name that has profile_define_ prefixed to the custom user profile field plugin name.
- field.class.php should contain a class with a name that has profile_field_ prefixed to the custom user profile field plugin name.
- The language file should define a pluginname string as the name of the plugin.
Interface API
define.class.php
define_form_specific()
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type.
function define_form_specific(&$form) { // select whether or not this should be checked by default $form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield')); $form->setDefault('defaultdata', 0); // defaults to 'no' $form->setType('defaultdata', PARAM_BOOL); }
define_validate_specific()
Validate the data from the add/edit profile field form that is specific to the current data type.
function define_validate_specific($data) { $errors = array(); // Make sure defaultdata is not false if ($data->defaultdata == false) { $errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield'); } return $errors; }
define_after_data
Alter form based on submitted or existing data
function define_after_data(&$form) { if (empty($data->defaultdata)) { $mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield')); } }
define_save_preprocess
Pre-process data from the profile field form before it is saved.
function define_save_preprocess($data) { if (empty($data->defaultdata)) { $data->defaultdata = NULL; } return $data; }
field.class.php
edit_field_add()
Adds the profile field to the moodle form
function edit_field_add(&$mform) { // Create form field $checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name)); if ($this->data == '1') { $checkbox->setChecked(true); } $mform->setType($this->inputname, PARAM_BOOL); if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) { $mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client'); } }
display_data()
Display the data for this field
function display_data() { $options = new stdClass(); $options->para = false; $checked = intval($this->data) === 1 ? 'checked="checked"' : ''; return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />'; }
edit_field_set_default()
Sets the default data for the field in the form object
function edit_field_set_default(&$mform) { if (!empty($default)) { $mform->setDefault($this->inputname, $this->field->defaultdata); } }
edit_validate_field()
Validate the form field from profile page
function edit_validate_field($usernew) { $errors = array(); if (isset($usernew->{$this->inputname})) { if ($usernew->{$this->inputname}['text'] === '') { $errors[$this->inputname] = 'error'; } } return $errors; }
edit_save_data_preprocess()
Process the data before it gets saved in database
function edit_save_data_preprocess($data, &$datarecord) { if (is_array($data)) { $datarecord->dataformat = $data['format']; $data = $data['text']; } return $data; }
edit_field_set_locked()
HardFreeze the field if locked.
function edit_field_set_locked(&$mform) { if (!$mform->elementExists($this->inputname)) { return; } if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) { $mform->hardFreeze($this->inputname); $mform->setConstant($this->inputname, $this->data); } }
Common functions
The following will need to be added to any files accessing the profile_ functions:
require_once("$CFG->dirroot/user/profile/lib.php");
profile_user_record($userid)
Returns an object with the custom profile fields set for the given user
profile_save_data($usernew)
Saves custom profile field data
profile_validation($usernew, $files)
Validates custom user profile field
Template
Database tables
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
- user_info_field - Information for custom field added to user profile page.
- user_info_data - Data added by user for the custom profile field
FAQ
How to add custom user profile field
Admin can add existing or custom profile fields. Refer en : User profile fields for adding user profile fields to user profile.
Which form elements does moodle support
Refer Form_API for list of elements supported by moodle