Student projects/Admin page cleanup/XML file format
Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Student projects/Admin page cleanup/XML file format.
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.)
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>
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())
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