Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

lib/formslib.php: Difference between revisions

From MoodleDocs
No edit summary
Line 1: Line 1:
== Work Done on Formslib ==
== Features of Formslib ==


* Created stylesheet for forms.
* Stylesheet for forms in Moodle standard themes.
* Created initial xhtml structure (maybe changed later).
* Created xhtml structure to comply to xhtml strict DTD.
* Created demo of formslib converting an exisiting form to use the new formslib course/edit.php which has been included in Moodle 1.7 as course/edit2.php
* Facility to add Moodle help buttons to forms
* Added facility to add help buttons to forms, worked on ways to process form data securely as is currently done with required_param, optional_param
* Facility to process form data securely as is currently done with required_param, optional_param using setType


== Usage ==
== Usage ==


course/edit2.php and the included course/edit_form.php provide a good example of usage of this library.
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 [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://www.midnighthax.com/quickform.php slightly longer one] particularly useful.
Also see the PEAR docs for [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://www.midnighthax.com/quickform.php slightly longer one] particularly useful.
Line 14: Line 16:
We created some special wrapper functions for moodle. $mform->data_submitted() returns false if no data has been submitted or validation fails or returns an object with the contents of the submitted data.
We created some special wrapper functions for moodle. $mform->data_submitted() returns false if no data has been submitted or validation fails or returns an object with the contents of the submitted data.


It is important to realise that there are three conditions under which a form page will be accessed :
It is important to realise that there are three conditions under which a form page will be accessed.
 
# the form is loaded for the first time
# the form has been submitted but there are errors so the form should be redisplayed (if using server side validation)
# the form will be processed. Often this means data will be inserted in the db. After data is inserted in the db redirect should be used to reload the page or to go to the next page.


==Cleaning data when using formslib==
==Cleaning data when using formslib==
Line 40: Line 38:
* Security audit.
* Security audit.
* Further debugging.
* Further debugging.


== Initial Forms to Be Worked On ==
== Initial Forms to Be Worked On ==


See progress [http://tracker.moodle.org/browse/MDL-6937 here]
See progress [http://tracker.moodle.org/browse/MDL-6937 here]
We will leave the form data being processed as it was. The quick form libraries will be used just to print the forms. The values for each form element will be passed to the quickform code from the existing code after the existing code has filled in default values and processed any submitted values. This will save significant time since the logic for processing submitted values and setting defaults is often interwoven in Moodle and to unweave that and do it the quickforms way will take some time. So better to let the old code handle the processing and defaults of values and just concentrate on rendering accessible forms using xhtml and css.
Later we can work on having quickforms process the form values on these old forms if required. I do hope to work on having course/mod.php use the form descriptions to process submitted values from the activity module update forms.
Forms that have been initially selected as good candidates for conversion are ones that are ones not too complex :
* blocks\loancalc\block_loancalc.php (158)
* blog\preferences.html (1)
* calendar\event_edit.html (5)
* calendar\event_new.html (5)
* calendar\preferences.php (207)
* course\edit.html (55)
* course\editsection.html (2)
* course\groups-edit.html (86)
* course\groups-edit.html (154)
* course\lib.php (141)
* course\request.html (22)
* course\scales.php (180)
* login\signup_form.html (28)
* message\settings.php (95)
* mod\assignment\config.php (881)
* mod\assignment\mod.html (38)
* mod\chat\config.html (1)
* mod\chat\mod.html (21)
* mod\choice\mod.html (61)
* mod\data\config.php (1)
* mod\data\mod.html (76)
* mod\exercise\mod.html (44)
* mod\forum\config.html (1)
* mod\forum\mod.html (54)
* mod\forum\post.html (20)
* mod\forum\search.php (271)
* mod\forum\subscriber.html (2)
* mod\glossary\comment.html (9)
* mod\glossary\config.html (5)
* mod\glossary\edit.html (9)
* mod\glossary\formats.php (70)
* mod\glossary\import.html (1)
* mod\glossary\mod.html (72)
* mod\hotpot\config.html (1)
* mod\hotpot\mod.html (25)
* mod\hotpot\report.php (414)
* mod\label\mod.html (7)
* mod\lams\config.html (36)
* mod\lams\mod.html (36)
* mod\lesson\action\addpage.php (49)
* mod\lesson\mod.html (137)
* mod\quiz\config.html (88)
* mod\quiz\mod.html (144)
* mod\resource\config.html (1)
* mod\resource\type\common.html (1)
* mod\scorm\config.html (10)
* mod\scorm\mod.html (407)
* mod\survey\details.php (28)
* mod\survey\mod.html (14)
* mod\wiki\mod.html (62)
* mod\wiki\revertpages.html (11)
* mod\workshop\assessments.php (464)
* mod\workshop\assessment_grading_form.html (6)
* mod\workshop\mod.html (86)
* question\format\coursetestmanager\format.php (60)
* question\import.php (221)
* search\query.php (141)
* user\edit.html (23)
== More Forms to Work On (slightly more complex to implement). ==
* backup\backup_check.html (38)
* backup\backup_form.html (116)
* backup\config.html (90)
* backup\restore_form.html (150)
* blocks\login\block_login.php (51)
* blog\edit.html (20)
* course\category.php (265)
* course\groups-edit.html (121)
* course\importstudents.html (2)
* course\student.html (2)
* course\teacher.php (139)
* enrol\authorize\enrol.html (60)
* enrol\authorize\enrol.html (170)
* lib\blocklib.php (495)
* mod\choice\lib.php (61)
* mod\choice\view.php (87)


== Forms Which Will Not Use Quick Forms But Need Some Recoding of HTML ==
== Forms Which Will Not Use Quick Forms But Need Some Recoding of HTML ==


Forms below are not deemed good candidates for migration to using the quickform library because they are either too big and complex or mostly because they are very small forms. But they do still need some recoding of the html to make it more accessible.
Forms below are not deemed good candidates for migration to using the quickform library because they are either too big and complex or mostly because they are very small forms. But they do still need some recoding of the html to make it more accessible.
Line 372: Line 281:
== These forms do not need any work ==
== These forms do not need any work ==


Admin forms are being worked on by others in a seperate project.
Admin forms have been worked on by others in a seperate project.


* auth\cas\index_form.html (59)  
* auth\cas\index_form.html (59)  

Revision as of 07:37, 12 November 2006

Features of Formslib

  • Stylesheet for forms in Moodle standard themes.
  • Created xhtml structure to comply to xhtml strict DTD.
  • Facility to add Moodle help buttons to forms
  • Facility to process form data securely as is currently done with required_param, optional_param using setType

Usage

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. $mform->data_submitted() returns false if no data has been submitted or validation fails or returns an object with the contents of the submitted data.

It is important to realise that there are three conditions under which a form page will be accessed.

Cleaning data when using formslib

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

Most Commonly Used PARAM_* Types

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

  • PARAM_CLEAN is deprecated and you should try to use a more specific type.
  • PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
  • PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
  • PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
  • PARAM_INT should be used for integers.
  • PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

To Do

  • Conversion of forms to use the new forms API. See list of initial forms to be done below.
  • Security audit.
  • Further debugging.

Initial Forms to Be Worked On

See progress here

Forms Which Will Not Use Quick Forms But Need Some Recoding of HTML

Forms below are not deemed good candidates for migration to using the quickform library because they are either too big and complex or mostly because they are very small forms. But they do still need some recoding of the html to make it more accessible.

  • auth\cas\index_form.html (18)
  • auth\cas\index_form.html (32)
  • auth\cas\index_form.html (45)
  • blocks\search\block_search.php (49)
  • blog\tags.html (13)
  • blog\tags.html (43)
  • blog\tags.html (79)
  • blog\tags.html (90)
  • calendar\event_delete.html (4)
  • calendar\event_delete.html (21)
  • calendar\event_delete.html (38)
  • calendar\event_select.html (3)
  • course\import\activities\mod.php (55)
  • course\import\activities\mod.php (55)
  • course\import\activities\mod.php (55)
  • course\import\groups\mod.php (19)
  • course\index.php (279)
  • course\lib.php (1607)
  • course\lib.php (1613)
  • course\lib.php (1619)
  • course\loginas.php (68)
  • course\pending-reject.html(1)
  • course\report\log\lib.php (154)
  • course\report\participation\index.php (115)
  • course\report\participation\index.php (181)
  • course\report\participation\index.php (326)
  • course\report\participation\mod.php (73)
  • course\report\stats\lib.php (30)
  • course\report\stats\report.php (15)
  • course\search.php (162)
  • course\teacher.php (214)
  • enrol\authorize\locallib.php (193)
  • enrol\manual\enrol.html (16)
  • enrol\manual\enrol.html (44)
  • error\index.php (33)
  • files\index.php (180)
  • files\index.php (191)
  • files\index.php (321)
  • files\index.php (332)
  • files\index.php (362)
  • files\index.php (372)
  • files\index.php (408)
  • files\index.php (420)
  • files\index.php (466)
  • files\index.php (476)
  • files\index.php (506)
  • files\index.php (554)
  • files\index.php (702)
  • files\index.php (832)
  • files\index.php (843)
  • files\index.php (852)
  • files\index.php (858)
  • grade\exceptions.html (107)
  • grade\exceptions.html (128)
  • grade\exceptions.html (150)
  • grade\lib.php (2314)
  • grade\lib.php (2368)
  • grade\lib.php (2553)
  • grade\lib.php (2566)
  • grade\lib.php (2652)
  • grade\lib.php (2804)
  • install.php (667)
  • install.php (870)
  • iplookup\ipatlas\ip-atlas_prefs.php (106)
  • iplookup\ipatlas\plot.php (132)
  • lib\editor\htmlarea\coursefiles.php (232)
  • lib\editor\htmlarea\coursefiles.php (242)
  • lib\editor\htmlarea\coursefiles.php (336)
  • lib\editor\htmlarea\coursefiles.php (346)
  • lib\editor\htmlarea\coursefiles.php (375)
  • lib\editor\htmlarea\coursefiles.php (384)
  • lib\editor\htmlarea\coursefiles.php (412)
  • lib\editor\htmlarea\coursefiles.php (423)
  • lib\editor\htmlarea\coursefiles.php (468)
  • lib\editor\htmlarea\coursefiles.php (477)
  • lib\editor\htmlarea\coursefiles.php (506)
  • lib\editor\htmlarea\coursefiles.php (553)
  • lib\editor\htmlarea\coursefiles.php (698)
  • lib\editor\htmlarea\coursefiles.php (817)
  • lib\editor\htmlarea\plugins\SpellChecker\spell-check-ui.html (63)
  • lib\editor\htmlarea\popups\createanchor.php (54)
  • lib\editor\htmlarea\popups\fullscreen.php (171)
  • lib\editor\htmlarea\popups\insert_image.php (181)
  • lib\editor\htmlarea\popups\insert_image.php (285)
  • lib\editor\htmlarea\popups\insert_image.php (287)
  • lib\editor\htmlarea\popups\insert_image.php (289)
  • lib\editor\htmlarea\popups\insert_image.php (291)
  • lib\editor\htmlarea\popups\insert_image.php (319)
  • lib\editor\htmlarea\popups\insert_image.php (328)
  • lib\editor\htmlarea\popups\insert_image_std.php (154)
  • lib\editor\htmlarea\popups\insert_table.php (83)
  • lib\editor\htmlarea\popups\link.php (103)
  • lib\editor\htmlarea\popups\link.php (105)
  • lib\editor\htmlarea\popups\link.php (107)
  • lib\editor\htmlarea\popups\link.php (109)
  • lib\editor\htmlarea\popups\link.php (128)
  • lib\editor\htmlarea\popups\link.php (136)
  • lib\editor\htmlarea\popups\searchandreplace.php (107)
  • lib\editor\htmlarea\popups\select_color.php (65)
  • lib\editor\tinymce\jscripts\tiny_mce\plugins\advimage\image.htm (12)
  • lib\editor\tinymce\jscripts\tiny_mce\plugins\fullscreen\fullscreen.htm (87)
  • lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\anchor.htm (9)
  • lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\editor_template_src.js (90)
  • lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\image.htm (11)
  • lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\jscripts\image.js (52)
  • lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\jscripts\link.js (46)
  • lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\link.htm (11)
  • lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\source_editor.htm (10)
  • lib\editor\tinymce\jscripts\tiny_mce\tiny_mce_src.js (531)
  • lib\editor\tinymce\jscripts\tiny_mce\tiny_mce_src.js (874)
  • lib\html2text.php (94)
  • lib\html2text.php (140)
  • lib\questionlib.php (1174)
  • lib\rsslib.php (465)
  • lib\speller\controls.html (77)
  • lib\uploadlib.php (466)
  • lib\weblib.php (987)
  • login\change_password_form.html (45)
  • login\forgot_password.php (251)
  • login\index_form.html (25)
  • message\search.php (95)
  • message\send.php (95)
  • mod\assignment\lib.php (881)
  • mod\assignment\lib.php (1183)
  • mod\assignment\lib.php (1200)
  • mod\assignment\type\online\assignment.class.php (132)
  • mod\assignment\type\upload\assignment.class.php (826)
  • mod\assignment\type\upload\assignment.class.php (1302)
  • mod\assignment\type\upload\assignment.class.php (1318)
  • mod\assignment\type\uploadsingle\assignment.class.php (86)
  • mod\data\comment.php (65)
  • mod\data\edit.php (238) --recode html in all 12 field.class.php files
  • mod\data\edit.php (288)
  • mod\data\field\latlong\field.class.php (98)
  • mod\data\field.php (301)
  • mod\data\lib.php (184) --recode html in all 12 field mod.html files
  • mod\data\lib.php (953)
  • mod\data\lib.php (1003)
  • mod\data\lib.php (1150)
  • mod\data\preset.php (297)
  • mod\data\preset.php (319)
  • mod\data\preset.php (625)
  • mod\data\templates.php (139)
  • mod\exercise\assessments.php (88)
  • mod\exercise\assessments.php (274)
  • mod\exercise\locallib.php (1573)
  • mod\exercise\locallib.php (2374)
  • mod\exercise\locallib.php (2874)
  • mod\exercise\submissions.php (72)
  • mod\exercise\view.php (254)
  • mod\forum\lib.php (2316)
  • mod\forum\lib.php (3197)
  • mod\forum\prune.html (1)
  • mod\glossary\comment.php (101)
  • mod\glossary\editcategories.html (6)
  • mod\glossary\editcategories.php (109)
  • mod\glossary\export.php (65)
  • mod\glossary\view.php (269)
  • mod\glossary\view.php (332)
  • mod\journal\edit.html (1)
  • mod\journal\mod.html (20)
  • mod\journal\report.php (116)
  • mod\lesson\action\addbranchtable.php (36)
  • mod\lesson\action\continue.php (817)
  • mod\lesson\action\editpage.php (55)
  • mod\lesson\import.php (86)
  • mod\lesson\importppt.php (85)
  • mod\lesson\view.php (142)
  • mod\lesson\view.php (692)
  • mod\lesson\view.php (917)
  • mod\lesson\view.php (1195)
  • mod\lesson\view.php (1649)
  • mod\lesson\view.php (1986)
  • mod\quiz\attempt.php (142)
  • mod\quiz\attempt.php (475) --inlvolves rewriting question plugins
  • mod\quiz\editlib.php (178)
  • mod\quiz\editlib.php (310)
  • mod\quiz\report\analysis\report.php (364)
  • mod\quiz\report\grading\report.php (356)
  • mod\quiz\report\overview\report.php (451)
  • mod\quiz\report\overview\report.php (510)
  • mod\resource\type\file\localfile.php (39)
  • mod\resource\type\file\localpath.php (43)
  • mod\scorm\coefficientsetting.php (173)
  • mod\scorm\locallib.php (441)
  • mod\survey\report.php (397)
  • mod\survey\view.php (106)
  • mod\wiki\admin.php (265)
  • mod\wiki\checklinks.html (5)
  • mod\wiki\ewiki\ewiki.php (524)
  • mod\wiki\ewiki\ewiki.php (1478)
  • mod\wiki\ewiki\ewiki.php (1535)
  • mod\wiki\ewiki\ewiki.php (1607)
  • mod\wiki\ewiki\plugins\email_protect.php (123)
  • mod\wiki\ewiki\plugins\moodle\downloads.php (105)
  • mod\wiki\ewiki\plugins\moodle\moodle_wikidump.php (68)
  • mod\wiki\lib.php (1016)
  • mod\wiki\removepages.html (8)
  • mod\wiki\setpageflags.html (5)
  • mod\wiki\strippages.html (5)
  • mod\wiki\view.php (265)
  • mod\workshop\assessments.php (95)
  • mod\workshop\assessments.php (426)
  • mod\workshop\locallib.php (1993)
  • mod\workshop\locallib.php (2933)
  • mod\workshop\submissions.php (77)
  • mod\workshop\submissions.php (253)
  • mod\workshop\view.php (156)
  • question\category_class.php (192)
  • question\category_class.php (445)
  • question\category_class.php (598)
  • question\editlib.php (167)
  • question\editlib.php (172)
  • question\editlib.php (328)
  • question\export.php (157)
  • question\format\coursetestmanager\format.php (122)
  • question\preview.php (190)
  • question\type\datasetdependent\categorydatasetdefinitions.php (71)
  • question\type\datasetdependent\datasetitems.php (252)
  • question\type\datasetdependent\datasetitems.php (266)
  • question\type\rqp\types.php (162)
  • question\type\editquestionstart.html (1)
  • question\type\random\editquestionstart.html (1)
  • question\type\rqp\editquestionstart.html (1)
  • question\type\rqp\types.php (162)
  • sso\hive\expired.php (29)
  • user\extendenrol.php (48)
  • user\index.php (174)
  • user\index.php (311)
  • user\index.php (574)
  • user\message.html (1)

These forms do not need any work

Admin forms have been worked on by others in a seperate project.

  • auth\cas\index_form.html (59)
  • auth\cas\index_form.html (76)
  • blocks\search_forums\block_search_forums.php (31)
  • blog\blogpage.php (173)
  • blog\edit.php (62)
  • calendar\export_basic.html (3)
  • calendar\export_basic.html (34)
  • calendar\lib.php (1224)
  • calendar\view.php (207)
  • calendar\view.php (330)
  • calendar\view.php (525)
  • course\category.php (434)
  • course\reset.php (59)
  • enrol\manual\enrol.html (32)
  • enrol\paypal\enrol.html (7)
  • filter\algebra\algebradebug.php (331)
  • filter\tex\texdebug.php (208)
  • filter\tex\texed.php (74)
  • lang\en_utf8\help\quiz\multianswer.html (16)
  • lang\en_utf8\help\quiz\multianswer.html (32)
  • lib\adodb\adodb-perf.inc.php (675)
  • lib\adodb\adodb-perf.inc.php (894)
  • lib\speller\spellchecker.html (46)
  • lib\speller\wordWindow.js (146)
  • lib\weblib.php (674)
  • lib\weblib.php (2840)
  • lib\weblib.php (3675)
  • lib\weblib.php (3704)
  • lib\weblib.php (3722)
  • lib\weblib.php (3752)
  • lib\weblib.php (3778)
  • lib\weblib.php (3802)
  • lib\weblib.php (3826)
  • lib\weblib.php (3854)
  • lib\weblib.php (4021)
  • lib\weblib.php (4026)
  • lib\yui\container\container-debug.js (6469)
  • lib\yui\container\container-debug.js (6481)
  • lib\yui\container\container-debug.js (7017)
  • lib\yui\container\container-debug.js (7053)
  • lib\yui\container\container-debug.js (7073)
  • lib\yui\container\container-min.js (457)
  • lib\yui\container\container-min.js (505)
  • lib\yui\container\container.js (6381)
  • lib\yui\container\container.js (6393)
  • lib\yui\container\container.js (6929)
  • lib\yui\container\container.js (6965)
  • lib\yui\container\container.js (6985)
  • login\index_form.html (59)
  • login\index_form.html (73)
  • login\index_form.html (86)
  • login\index_form.html (102)
  • mod\assignment\type\common.html (1)
  • mod\assignment\type\upload\assignment.class.php (102)
  • mod\assignment\type\upload\assignment.class.php (129)
  • mod\assignment\type\upload\assignment.class.php (163)
  • mod\assignment\type\upload\assignment.class.php (1412)
  • mod\chat\gui_header_js\chatinput.php (59)
  • mod\chat\gui_header_js\chatinput.php (65)
  • mod\chat\gui_sockets\chatinput.php (115)
  • mod\chat\gui_sockets\chatinput.php (127)
  • mod\chat\pagelib.php (68)
  • mod\data\pagelib.php (71)
  • mod\data\preset.php (120)
  • mod\data\preset.php (131)
  • mod\data\preset.php (148)
  • mod\data\preset.php (161)
  • mod\data\preset.php (168)
  • mod\data\preset.php (193)
  • mod\data\preset.php (326)
  • mod\forum\lib.php (2991)
  • mod\forum\lib.php (3517)
  • mod\glossary\editcategories.php (178)
  • mod\hotpot\hotpot-full.js (957)
  • mod\hotpot\hotpot-full.js (4145)
  • mod\hotpot\hotpot-full.js (4217)
  • mod\hotpot\hotpot-full.js (5705)
  • mod\hotpot\index.php (112)
  • mod\hotpot\index.php (120)
  • mod\hotpot\index.php (385)
  • mod\hotpot\index.php (403)
  • mod\hotpot\lib.php (1608)
  • mod\hotpot\lib.php (1626)
  • mod\hotpot\report\fullstat\report.php (425)
  • mod\hotpot\report\overview\report.php (233)
  • mod\hotpot\template\v6.php (2499)
  • mod\hotpot\template\v6.php (2603)
  • mod\hotpot\view.php (79)
  • mod\lesson\mediafile.php (28)
  • mod\lesson\report.php (106)
  • mod\lesson\report.php (273)
  • mod\lesson\view.php (81)
  • mod\lesson\view.php (93)
  • mod\quiz\index.php (29)
  • mod\quiz\jstimer.php (35)
  • mod\quiz\pagelib.php (69)
  • mod\resource\type\repository\hive\openhive.php (43)
  • mod\scorm\locallib.php (465)
  • mod\wiki\ewiki\ewiki.php (1094)
  • mod\wiki\ewiki\ewiki.php (1653)
  • question\category_class.php (385)
  • question\format\xhtml\format.php (128)
  • question\type\datasetdependent\datasetitems.php (275)
  • user\messageselect.php (79)
  • user\view.php (312)
  • user\view.php (317)
  • user\view.php (325)
  • user\view.php (340)
  • user\view.php (353)
  • user\view.php (357)
  • user\view.php (365)