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
Category:Formslib

Advanced Usage

(added categories)
m (This related to Moodle 1.8. We do not need to migrate it.)
 
(20 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Template:WillNotMigrate}}
{{Formslib}}
{{Moodle 1.8}}
The formslib api is fully implemented in Moodle 1.8. The partial backport into 1.7 does not work properly and is not supported.
== Features of Formslib ==
== Features of Formslib ==


* Created xhtml structure aiming for compliance with xhtml strict DTD and section 508 accessibility guidelines.
* Stylesheet for forms in Moodle standard themes.
* Stylesheet for forms in Moodle standard themes.
* Created xhtml structure to comply to xhtml strict DTD.
* Accessibility improvements :
* Facility to add Moodle help buttons to forms
** Input fields labeled
* Facility to process form data securely as is currently done with required_param, optional_param using setType
** Tableless layout.
 
** Tested and optimised for use on major screenreaders Dragon and JAWS.
== Usage ==
* New functionality :
 
** Facility to process form data securely as is currently done with required_param, optional_param using setType.
There are many phpdoc style comments in lib/formslib.php
** Form elements process submitted data themselves and check the submitted data. For instance in select type only options that have been added to the select are accepted when submitted.
 
** Form validation with custom validation function or addRule QuickForms validation. QuickForms validation allows for clientside validation.
course/edit.php and the included course/edit_form.php provide a good example of usage of this library.
** Feedback to the user about required input and errors in user input.
 
** Facility to add Moodle help buttons to forms.
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.
** upload_manager processes uploaded files securely.
 
** Many custom Moodle specific and non specific form elements to add to forms.
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.
*** Moodle specific elements modgrade, modvisible, modgroupmode and choosecoursefile, format
 
*** Non specific elements htmleditor, dateselector, datetimeselector, selectyesno
It is important to realise that there are three conditions under which a form page will be accessed.
*** Lots of modification to regular elements.
 
*** Easy to define your own custom elements.
==Cleaning data when using formslib==
* Some advanced functionality :
 
** Methods for adding repeated elements to a page. With button to add more elements.
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).
** Working on hiding / unhiding advanced options on a form.


=== Most Commonly Used PARAM_* Types ===
==Usage==


These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.
See the menu to the top right for pages on using formslib.php
 
* 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 ==
== To Do ==


* Conversion of forms to use the new forms API. See list of initial forms to be done below.
* Conversion of forms to use the new forms API. See list of initial forms to be done [http://tracker.moodle.org/browse/MDL-6937 in the tracker].
* Security audit.
* Further debugging.
 
== Initial Forms to Be Worked On ==


See progress [http://tracker.moodle.org/browse/MDL-6937 here]


== Forms Which Will Not Use Quick Forms But Need Some Recoding of HTML ==
== Forms Which May 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 were initially 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. (I don't see the problem with very small forms. I would still use the library, but I would not bother putting the form class definition in a separate file.[[User:Tim Hunt|Tim Hunt]]) 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 (18)  
Line 281: Line 276:
== These forms do not need any work ==
== These forms do not need any work ==


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


* auth\cas\index_form.html (59)  
* auth\cas\index_form.html (59)  
Line 395: Line 390:
* user\view.php (365)
* user\view.php (365)


== See also ==
* [http://xref.moodle.org/lib/formslib.php.html PHPXref documentation for formslib.php]
* [http://phpdocs.moodle.org/HEAD/index.html PHP docs] for developers 


[[Category:formslib]]
[[Category:Formslib]]

Latest revision as of 15:59, 10 June 2022


Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.


Moodle1.8


The formslib api is fully implemented in Moodle 1.8. The partial backport into 1.7 does not work properly and is not supported.

Features of Formslib

  • Created xhtml structure aiming for compliance with xhtml strict DTD and section 508 accessibility guidelines.
  • Stylesheet for forms in Moodle standard themes.
  • Accessibility improvements :
    • Input fields labeled
    • Tableless layout.
    • Tested and optimised for use on major screenreaders Dragon and JAWS.
  • New functionality :
    • Facility to process form data securely as is currently done with required_param, optional_param using setType.
    • Form elements process submitted data themselves and check the submitted data. For instance in select type only options that have been added to the select are accepted when submitted.
    • Form validation with custom validation function or addRule QuickForms validation. QuickForms validation allows for clientside validation.
    • Feedback to the user about required input and errors in user input.
    • Facility to add Moodle help buttons to forms.
    • upload_manager processes uploaded files securely.
    • Many custom Moodle specific and non specific form elements to add to forms.
      • Moodle specific elements modgrade, modvisible, modgroupmode and choosecoursefile, format
      • Non specific elements htmleditor, dateselector, datetimeselector, selectyesno
      • Lots of modification to regular elements.
      • Easy to define your own custom elements.
  • Some advanced functionality :
    • Methods for adding repeated elements to a page. With button to add more elements.
    • Working on hiding / unhiding advanced options on a form.

Usage

See the menu to the top right for pages on using formslib.php

To Do

  • Conversion of forms to use the new forms API. See list of initial forms to be done in the tracker.


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

Forms below were initially 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. (I don't see the problem with very small forms. I would still use the library, but I would not bother putting the form class definition in a separate file.Tim Hunt) 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 separate 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)

See also

Retrieved from "https://docs.moodle.org/dev/index.php?title=lib/formslib.php&oldid=63296"
Powered by MediaWiki