Block formslib

(This is currently a proposal and isn't available for use see [https://tracker.moodle.org/browse/MDL-9641 MDL-9641]).

Overview

The block formslib functions are designed to allow developers easily create forms for their blocks. Please read lib/formslib.php for full details about using formslib.

Creating a Global Configuration form

In order to create a global confuration form using formslib, you must create a file /blocks/BLOCKNAME/config_global_form.php

In this file a class needs to be created which follows the naming scheme: block_BLOCKNAME_config_global_form and extends block_config_global_form

In your form configuration class you need to implement the block_configuration() method, adding the elements you need with $this->add_config_element(). Using this method means the form elements will be processed when the block configuration is saved.

require_once $CFG->dirroot .'/blocks/block_config_global_form.php';

class block_BLOCKNAME_config_global_form extends block_config_global_form {

    function block_configuration(&$mform){

        // add a html editor text field named block_BLOCKNAME_text
        $this->add_config_element('htmleditor', 'block_BLOCKNAME_text', get_string('text','BLOCKNAME'));

        // This will set the value of the textfield to 'mydefaultstring' or,
        // if $CFG->block_BLOCKNAME_text already exists, it 
        // will set the field to the value of that
        $this->set_config_default('block_BLOCKNAME_text', 'mydefaultstring');

        $mform->setType('block_BLOCKNAME_text', PARAM_RAW);


       $this->add_config_element('text', 'block_BLOCKNAME_num', get_string('block_BLOCKNAME_num', 'BLOCKNAME'));

        $this->set_config_default('block_online_users_timetosee', '5');

        // Add client side validation which forces the field as numeric
        $mform->addRule('block_BLOCKNAME_num', null, 'numeric', null, 'client');

        $mform->setType('block_BLOCKNAME_num', PARAM_INT);

    }

}

Creating a Instance Configuration form

In order to create a global confuration form using formslib, you must create a file /blocks/BLOCKNAME/config_instance_form.php

In this file a class needs to be created which follows the naming scheme: block_BLOCKNAME_config_instance_form and extends block_config_instance_form.

In your form configuration class you need to implement the instance_configuration() method, adding the elements you need with $this->add_config_element(). Using this method means the form elements will be processed when the block configuration is saved.

<?php
require_once $CFG->dirroot .'/blocks/block_config_instance_form.php';

class block_BLOCKNAME_config_instance_form extends block_config_instance_form {

    function instance_configuration(&$mform){

        // add a text field named title
        $this->add_config_element('text','title',get_string('configtitle', 'BLOCKNAME'));

        // this will set the form field to 'my title'
        // or if a title string is already stored in the block instance
        // configuration, it will set it to that
        $this->set_config_default('title', 'my title string');

        $mform->setType('title', PARAM_NOTAGS);
        
    }

}

Custom formslib-style functions

add_config_element

This does the same as addElement, except that is also adds the element to the list of form elements which need to be saved by the block configuration. Thus it must be used if you wish to save the elememnt value in the block configuration!

set_config_default

set_config_default($name, $default = NULL)

This will try and set the the element named to its stored value ($CFG->$name, in the case of global configuration, $block->config->$name in the case of instance configuration).

If there is no stored value, the it will set the default to $default (if it exists)

overriden get_data

The block get_data methods will only export form values which were added to the form with add_config_element(), to ensure we only store configuration items we wish to.