lib/formslib.php repeat elements

Revision as of 17:06, 3 October 2017 by Marcus Green (talk | contribs) (Examples)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This function adds a repeating group of elements. An array index starting with a zero index will be added to the elementname so that the form will return arrays of submitted values.

Also on the form there will be a button to add extra elements to the form. The form page reloads with extra form elements. This involves no javascript.

Overview

Most of the necessary information is in the phpdoc comment for the repeat_elements() method:

    /**
     * Method to add a repeating group of elements to a form.
     *
     * @param array $elementobjs Array of elements or groups of elements that are to be repeated
     * @param int $repeats no of times to repeat elements initially
     * @param array $options a nested array. The first array key is the element name.
     *    the second array key is the type of option to set, and depend on that option,
     *    the value takes different forms.
     *         'default'    - default value to set. Can include '{no}' which is replaced by the repeat number.
     *         'type'       - PARAM_* type.
     *         'helpbutton' - array containing the helpbutton params.
     *         'disabledif' - array containing the disabledIf() arguments after the element name.
     *         'rule'       - array containing the addRule arguments after the element name.
     *         'expanded'   - whether this section of the form should be expanded by default. (Name be a header element.)
     *         'advanced'   - whether this element is hidden by 'Show more ...'.
     * @param string $repeathiddenname name for hidden element storing no of repeats in this form
     * @param string $addfieldsname name for button to add more fields
     * @param int $addfieldsno how many fields to add at a time
     * @param string $addstring name of button, {no} is replaced by no of blanks that will be added.
     * @param bool $addbuttoninside if true, don't call closeHeaderBefore($addfieldsname). Default false.
     * @return int no of repeats of element in this page
     */

The elements to repeat

Are in the $elementobjs array, with any options passed in the $options array.

WIthin these fields, for example, within the element labels or the Defaults (since Moodle 2.3) you can use {no} to represent which element number this is, counting from 1.

The number of repeats

$repeats is the number of repeats to show initially. $addfieldsno is the number of elements to add whenever the user clicks the 'add more fields' button. $addstring is the label for this button. It can use the {no} placeholder, this time for saying how many repeats will be added. $repeathiddenname is the name to use for the hidden form field that records how many repeats there are.

Examples

Here is some code using repeat_elements() from inside definition() method of the add or update a Choice form:

//-------------------------------------------------------------------------------
       $repeatarray = array();
        $repeatarray[] = $mform->createElement('text', 'option', get_string('optionno', 'choice'));
        $repeatarray[] = $mform->createElement('text', 'limit', get_string('limitno', 'choice'));
        $repeatarray[] = $mform->createElement('hidden', 'optionid', 0);
 
        if ($this->_instance){
            $repeatno = $DB->count_records('choice_options', array('choiceid'=>$this->_instance));
            $repeatno += 2;
        } else {
            $repeatno = 5;
        }
 
        $repeateloptions = array();
        $repeateloptions['limit']['default'] = 0;
        $repeateloptions['limit']['disabledif'] = array('limitanswers', 'eq', 0);
        $repeateloptions['limit']['rule'] = 'numeric';
        $repeateloptions['limit']['type'] = PARAM_INT;
 
        $repeateloptions['option']['helpbutton'] = array('choiceoptions', 'choice');
        $mform->setType('option', PARAM_CLEANHTML);
 
        $mform->setType('optionid', PARAM_INT);
 
        $this->repeat_elements($repeatarray, $repeatno,
                    $repeateloptions, 'option_repeats', 'option_add_fields', 3, null, true);

For other examples, have a look at the question type editing forms. They make extensive use of repeat_elements().