Customlabel subtype development framework

Back to index

The customlabel subtype development framework is a set of writting and development rules which will make easy making new subtypes for use in course contents.

The customlabel concept is to centralize all mechanical aspects in the customlabel module, thus keeping writing of a subtype minimalist.

What is a subtype?

A subtype is a cutomlabel subplugin handled by the generic subplugin API of Moodle.

A subtype is essentially :

• a directory in the mod/customlabel/type directory
• a subclass of the customlabel_type (@see /mod/customlabel/type/customtype.class.php)
• a file version.php to handle subplugin verisonning
• a lang directory for storing templates and language dependant strings
• a local css file for preseting default styling

The customlabel_type class

The customlabel_type class describes what is the internal information model of the customlabel. The custom type must require the geenric customlabel_type implementation to extend the parent class :

  require_once ($CFG->dirroot."/mod/customlabel/type/customtype.class.php");
  

  class customlabel_type_coursedata extends customlabel_type{
  ... implementation ...
  }

Just three methods are enough to build the customtype :

The class constructor

Defines all information fields used by the customlabel templates. The class stores the type information and builds the $this->fields array that defines each field.

  function __construct($data){
     parent::__construct($data);
     $this->type = 'coursedata';
     $this->fields = array();

The constructor will define fields using the following code template :

  unset($field);
       $field->name = 'fieldname';
       $field->type = 'textfield';
       $this->fields['fieldname'] = $field;

Field type drives how the instance setting form will require information from the editing teacher. Depending on the type accessory attributes can be used to control specific aspects of the settings form.

Field type : choiceyesno

       unset($field);
       $field->name = 'choiceyesnoname';
       $field->type = 'choiceyesno';
       $this->fields['choiceyesnoname'] = $field;

Provides a boolean selector as a yes/no list

Field type : textfield

       unset($field);
       $field->name = 'textfieldname';
       $field->type = 'textfield';
       $field->size = 40;  // optional
       $field->mawlength = 40;  // optional
       $this->fields['textfieldname'] = $field;

Provides a simple textfield to get a simple string

Field type : htmlarea or editor

       unset($field);
       $field->name = 'textareafieldname';
       $field->type = 'textarea';
       $field->size = 80;
       $this->fields['textareafieldname'] = $field;

Provides an editable textarea or html editor (depending on site settings) for inpting a formatted multiline content.

Field type : list

  unset($field);
  $field->name = 'datafieldname';
  $field->type = 'list';
  $field->options = 'comma,separated,list,of,option,keys';
  $field->multiple = 'multiple';  // adds multiple choice capability
  $this->fields['datafieldname'] = $field;

Provides a select list keyed by the option list and labelled with option key tranlsations in the active language. Translations must be provided in lang files of the subtype plugin.

There are a set of additional optional attributes that can help in some situations:

  $field->straightoptions = true;

The effect will be that the values given in the option list will be presented litteraly, without translation, the same value being used for both key and option value.

Field type : datasource

  unset($field);
  $field->name = 'datafieldname';
  $field->type = 'datasource';
  $field->source = 'dbfieldkeyed';  // source mode
  $field->table = 'tablename where to get data from';
  $field->field = 'sourcefieldname';
  $field->select = 'some select clause';
  $field->multiple = 'multiple';  // adds multiple choice capability (defaults to : no)
  $field->constraintson = 'level1,level2';
  $field->mandatory = true; // (defaults to : false)
  $this->fields['datafieldname'] = $field;

Datasource field allows data stored in any part of Moodle to serve as information reference for the field. Data source can feed the list with value or keys depending the table can provide keys or both keys and labels. This selection is driven by the 'source" attribute that can be :

• dbfieldkey : get a value set from a given field in a given table directly from field values, keys by the 'id' primary key of the table.

Declaration sample :

  $field->name = 'courseselectorbyid';
  $field->type = 'datasource';
  $field->source = 'dbfieldkey';
  $field->table = 'course';
  $field->field = 'fullname';
  $field->ordering = 'sortorder';
  $field->select = ' visible = 1 ';
  $this->fields['courseselectorbyid'] = $field;

• dbfieldkeyed : get a value set from a given field in a given table from field values keyed by a given key.

Declaration sample :

  $field->name = 'courseselectorbyshortname';
  $field->type = 'datasource';
  $field->source = 'dbfieldkeyed';
  $field->table = 'course';
  $field->field = 'fullname';
  $field->key = 'shortname';
  $field->select = ' visible = 1 ';
  $field->ordering = 'sortorder';
  $this->fields['courseselectorbyshortname'] = $field;

• function : get a value set as a result of a given function call. The function is called without any arguments (could be amended).

  $field->name = 'selectorbyfunction';
  $field->type = 'datasource';
  $field->source = 'function';
  $field->file = 'sourcefile/path/from/dirroot';
  $field->function = 'functionname';
  $this->fields['selectorbyfunction'] = $field;

Preprocessing and postprocessing overrides

When composing the content of the label from the templates and the available data, the processing runs four steps :

• Preprocessing override (if implemented in the subtype)
• processing options from lists
• processing datasources
• Postprocessing override (if implemented in the subtype)

Typical post processing action could be to amend the production of lists and datasources to get special data setup.

  function preprocess_data(){
  }

  function postprocess_data(){
  }

Use $this->data to alter the available data before template production.

Templates

Customlabels are preprocessed in order to cache the content for better output performance. The content is calculated from templates when the instance is added or updated. The output is computed from templates available in language directories.

Template format

Templates are piece of HTML with placeholders for customlabel internal available information (resulting of the internal data prcoessing. See above). Placeholders are tags of the form %%attributename%%.

Example :

  <div class="custombox-commentbox">
  <%%comment%%>
  </div>

The Comment box customlabel only defines a single textarea attribute named 'comment', that is "callable" by the template.

From Moodle 2 migration, customlabel now accepts elementary conditional syntax :

  <%if %%attribute%% %>
  .... conditional tempalte code....
  <%endif %>

The tested attribute considered as a boolean (empty or not empty) test.

Language resolution

The course elements are compatible with multiple language content writing. As some elements are open to really free formatted content, the success of dealing with translations is obtained by providing templates for each language, and inject filtered information comming from element internal storage model.

The way language tagging is performed using tags is sadly not compatible with the standard multilanguage filter, that fails often parsing content when some parts of the content get locally formated with internal spans. Thus the customlabel module needs to be used with the special "multilang enchanced" filter, that will be fully compatible with other multilingual content of Moodle.