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.)

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

The following code represents 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 more complete sample is available here. The files were validated using 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