Development:lib/formslib.php Usage

Usage of Formslib

There are many phpdoc style comments in lib/formslib.php

course/edit.php and the included course/edit_form.php provide a good example of usage of this library.

Also see the PEAR docs for HTML_QuickForm docs I found this quick tutorial and this slightly longer one particularly useful.

We created some special wrapper functions for moodle. Function $mform->get_data() returns an object with the contents of the submitted data or returns null if no data has been submitted or validation fails.

Basic Usage in A Normal Page

Generally the structure of a page with a form on it looks like this :

require_once('pathtoformdescription'); //you'll process some page parameters at the top here and get the info about //what instance of your module and what course you're in etc. Make sure you //include hidden variable in your forms which have their defaults set in set_data //which pass these variables from page to page


$mform = new yourmod_formfunction_form();//name of the form you defined in file above. //default 'action' for form is strip_querystring(qualified_me()) if ($mform->is_cancelled()){

   //you need this section if you have a cancel button on your form
   //here you tell php what to do if your user presses cancel
   //probably a redirect is called for!
   // PLEASE NOTE: is_cancelled() should be called before get_data(), as this may return true

} else if ($fromform=$mform->get_data()){ //this branch is where you process validated data.

} else { // this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed // or on the first display of the form.

   //setup strings for heading
   print_header_simple($streditinga, ,
    "<a href=\"$CFG->wwwroot/mod/$module->name/index.php?id=$course->id\">$strmodulenameplural</a> ->
    $strnav $streditinga", $mform->focus(), "", false);
   //notice use of $mform->focus() above which puts the cursor 
   //in the first form field or the first field with an error.

   //call to print_heading_with_help or print_heading? then :
   
   //put data you want to fill out in the form into array $toform here then :

   $mform->set_data($toform);
   $mform->display();
   print_footer($course);

}

You are encouraged to look at lib/formslib.php to see what additional functions and parameters are available. Available functions are well commented.

Defining Your Form Class

The form class tells us about the structure of the form. You are encouraged to put this in a file called {function}_form.php probably in the same folder in which the page that uses it is located. The name of your class should be {modname}_{function}_form eg. forum_post_form or course_edit_form. These classes will extend class moodleform.

Note the name you give the class is used as the id attribute of your form in html (any trailing '_form' is chopped off'). Your form class name should be unique in order for it to be selectable in CSS by theme designers who may want to tweak the css just for that form.

definition()

Help is here for defining your form by defining a function definition() in your form class that sets up your form structure.

Use in Activity Modules Add / Update Forms

Syntax is the same in activity modules to create your update / add page. We are still supporting mod.html but if you want to use the new formslib then you can in Moodle 1.8 just include in your module directory the file mod_form.php instead of mod.html and it will be automatically detected. Inside this file you define a class with class name '{modname}__mod_form' which extends the class 'moodleform_mod'. See many examples of the core modules which have been converted to use formslib already.

defaults_preprocessing

For activity modules you use the same syntax to define your form. You may also want to override method defaults_preprocessing this can be used to take the data from the data base and tell the form how to fill out defaults in the form with this data. For example in the forum module in forum/mod_form.php we needed to tick an enable check box if a date had been selected in the date select. Normally data is loaded from the database and directly loaded into form fields with the same name as the database record you only need to use defaults_preprocessing if there isn't this one to one relationship. Another example is the lesson/mod_form.php which takes the data from the database and unserializes it. choice/mod_form.php shows an exampe of loading data from another db table referred to by a foreign key, to include in the form.

Post Processing Still Done in lib.php Functions

Post processing of data is done in lib.php functions modname_add_instance and modname_update_instance after the data has been validated. When migrating a form often little changes need to be made in the post processing. An exception is that date and date_time_selector fields automatically have their submitted data turned into timestamps so you don't need to do this in your add and update functions anymore.

Automatically Including Standard Activity Module Form Elements

Standard activity module form elements are automatically included using the moodleform_mod method standard_coursemodule_elements(). The default is to include a visibility and groupsmode select box and to include all necessary hidden fields. You can pass a parameter false to tell the method that your module doesn't support groups and so you don't want the groupsmode select button.