User profile fields

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:
1. lang/en/profilefield_customprofilefieldplugin.php - Language file, containing strings for user profile field.
2. define.class.php - Definition of the user profile field type will be added in this file.
3. field.class.php - Controls user profile field display, while editing or showing as user profile field.
4. 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

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

Documentation