Student projects/Admin page cleanup/XML file format: Difference between revisions
mNo edit summary |
|||
Line 18: | Line 18: | ||
<!ATTLIST setting name CDATA #REQUIRED | <!ATTLIST setting name CDATA #REQUIRED | ||
visiblename CDATA #REQUIRED | visiblename CDATA #REQUIRED | ||
type (text|select|htmledit|checkbox) #REQUIRED | type (text|select|htmledit|checkbox|multiselect) #REQUIRED | ||
selectoptions CDATA #IMPLIED | selectoptions CDATA #IMPLIED | ||
description CDATA #REQUIRED | description CDATA #REQUIRED | ||
Line 77: | Line 77: | ||
* Defaults aren't being stored in the XML DTD since the PHP simplexml extension seems unable to process those defaults. Instead, PHP code that deals with the XML must appropriately replace default text when an implied attribute is blank. | * Defaults aren't being stored in the XML DTD since the PHP simplexml extension seems unable to process those defaults. Instead, PHP code that deals with the XML must appropriately replace default text when an implied attribute is blank. | ||
* The main XML file will be stored in lib/admin.xml | * The main XML file will be stored in lib/admin.xml | ||
[[Category:Developer]] | [[Category:Developer]] | ||
[[Category:Project]] | [[Category:Project]] |
Revision as of 01:16, 18 July 2006
Part of the Student projects/Admin page cleanup project involves coming up with a format for storing the hierarchy of admin settings and general information about the settings. (N.B. the XML file is for storing how the settings are organized, not the setting themselves -- those are still stored in the database for reasons of efficiency.)
XML DTD
The following XML DTD defines the format for the file that'll store the Moodle Admin structure:
<!DOCTYPE moodleadmin [ <!ELEMENT moodleadmin (category|settinggroup|settingpage)*> <!ELEMENT category (category|settinggroup|settingpage)*> <!ATTLIST category name CDATA #REQUIRED visiblename CDATA #REQUIRED auth CDATA #REQUIRED> <!ELEMENT settinggroup (setting*)> <!ATTLIST settinggroup name CDATA #REQUIRED visiblename CDATA #REQUIRED auth CDATA #REQUIRED icon CDATA #IMPLIED> <!ELEMENT setting EMPTY> <!ATTLIST setting name CDATA #REQUIRED visiblename CDATA #REQUIRED type (text|select|htmledit|checkbox|multiselect) #REQUIRED selectoptions CDATA #IMPLIED description CDATA #REQUIRED setoninstall (true|false) #IMPLIED writeproc CDATA #REQUIRED readproc CDATA #REQUIRED> <!ELEMENT settingpage EMPTY> <!ATTLIST settingpage name CDATA #REQUIRED visiblename CDATA #REQUIRED auth CDATA #REQUIRED icon CDATA #IMPLIED hardcoded CDATA #REQUIRED> ]>
Sample XML Files
Here's a short sample XML file
<moodleadmin> <category name="php_code_must_return_string" auth="php_code_must_return_boolean"> <settinggroup name="php_code_must_return_string" auth="php_code_that_must_return_boolean"> <setting name="php_code_must_return_string" type="(text|select|htmledit|checkbox)" selectoptions="option1,option2,option3" description="php_code_must_return_string" setoninstall="(true|false)" writeproc="php_code_must_return_boolean" readproc="php_code_must_return_string" /> </settinggroup> <settingpage name="php_code_must_return_string" hardcoded="filename.php" auth="php_code_must_return_boolean" /> </category> </moodleadmin>
A full(er) sample is available here. Validation on these files was done through this service.
Explanations
Categories appear in the hierarchical menu as folders, while settinggroups and settingpages appear as actual clickable items. Thus, categories can be nested, while settinggroups and settingpages must appear either within a category or at the moodleadmin root level. Settings must appear in a settinggroup.
Next, the attributes. If an attribute has the same name in two different tags (e.g. auth in settingpage and settinggroup), it's because it serves the same purpose in both tags. To that end, I'll only describe what happens to each attribute, not each tag/attribute combination. Also, note that many attributes actually take PHP code and not just plaintext, allowing for much more expandability without having to redo the XML DTD every time we need a new feature.
- name should contain an internal name for the element. This name must be unique within the parent tag (e.g. the same name could exist in two different categories, but all tags one level below a category must have unique names)
- visiblename should contain the actual text to be displayed to the user (e.g. as the name of the folder, of a settingpage, of an actual setting, etc.) It is parsed through PHP and must contain code that returns a string, for example
"User Settings" get_string('Administration')
- auth should contain PHP code that evaluates to either true or false to determine whether or not the current user should be given access to the settinggroup, settingpage or category. The auth field is also used to detect whether we're on a course page or the main page (since admin links are page-context-sensitive). For example
isadmin() iscreator() (($this->instance->pageid == SITEID) && isadmin())
(in progress...)
Remarks and Things Remaining To Be Done
- Defaults aren't being stored in the XML DTD since the PHP simplexml extension seems unable to process those defaults. Instead, PHP code that deals with the XML must appropriately replace default text when an implied attribute is blank.
- The main XML file will be stored in lib/admin.xml