User profile fields

Jump to: navigation, search

Introduction

This plugin allow you to add custom user profile fields, which can be added to user profile. For example, if you want to display radio buttons on user profile, then create radio user profile field plugin and add them to user profile field.

History

User profile fields exists from 1.9 and supports five default user profile field plugins:

  1. Checkbox
  2. datetime
  3. menu
  4. text
  5. textarea

File Structure

  1. Create a folder for your plugin in moodle/user/profile/field/customprofilefieldplugin
  2. Create 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 user profile field 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

  1. profilefield_ is prefixed to name of user profile field plugin, for identifying the name of the plugin.
  2. define.class.php should have a class with profile_define_ prefix to custom user profile field plugin name.
  3. field.class.php should have a class with profile_field_ prefix to custom user profile field plugin name.
  4. Language file should define pluginname as 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:

  1. user_info_field - Information for custom field added to user profile page.
  2. 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