MODX Technical Specification

The phpBB MOD Team

Tags highlighted in purple have been modified since MODX 1.0.1 or were newly introduced with MODX 1.2.0
Tags highlighted in red are modified in MODX 1.2.2.
Tags highlighted in green are modified in MODX 1.2.3.
Tags highlighted in dodgerblue are modified in MODX 1.2.4.
Tags highlighted in royalblue are modified in MODX 1.2.5.
Tags highlighted in darkgreen are modified in MODX 1.2.6.

  • <mod>

    • The root tag of a MODX file. Contains all the other tags.
    • Must occur exactly once in a MODX file
    • <header>

      • Parent: <mod>
      • Attributes: None
      • Must occur exactly once in a <mod> tag
      • Children: <title>, <description>, <author-notes>, <link-group>, <mod-version>, <installation>, <history>, <header>, <meta>
      • <title>

        • Parent: <header>
        • Attributes:
          • lang – Required – an ISO language code
        • Must occur at least once in a <header> tag
        • Children: None
        • Contains:
          • String: The MOD title in the language specified by the lang attribute
      • <description>

        • Parent: <header>
        • Attributes:
          • lang – Required – an ISO language code
        • Must occur at least once in a <header> tag
        • Children: None
        • Contains:
          • String: The MOD description in the language specified by the lang attribute
      • <author-notes>

        • Parent: <header>
        • Attributes
          • lang – Required – an ISO language code
        • May occur multiple times
        • Children: None
        • Contains:
          • String: Any author notes. Should be displayed by any automatic installers
      • <github>

        • Parent: <header>
        • Attributes: None
        • May occur only once
        • Children: None
        • Contains:
          • String: Fully qualified URL to the github repo for the MOD
      • <author-group>

        • Parent: <header>
        • Attributes: None
        • Must occur at least once in a <header> tag
        • Children: <author>
        • Contents: None
        • <author>

          • Parent: <author-group>
          • Attributes: None
          • Must occur at least once in an <author-group> tag
          • Children: <realname>, <username>, <homepage>, <email>, <contributions-group>
          • Contents: None
          • <realname>

            • Parent: <author>
            • Attributes: None
            • May occur only once
            • Contents: String – The MOD author’s real name
          • <username>

            • Parent: <author>
            • Attributes:
              • phpbbcom – Optional – Set to no if the author is not registered at phpbb.com
            • Must occur exactly once in an <author> tag
            • Contents: String – The author’s username at phpBB.com if registered
            • Children: None
          • <homepage>

            • Parent: <author>
            • Attributes: None
            • May occur only once
            • Contents: String – A complete URI to the MOD author’s homepage
            • Children: None
          • <email>

            • Parent: <author>
            • Attributes: None
            • May occur only once
            • Contents: String – A contact email address for the MOD author
            • Children: None
          • <contributions-group>

            • Parent: <author>
            • Attributes: None
            • May occur any number of times in an <author> tag (optional)
            • Contents: None
            • Children: <contributions>
            • <contributions>

              • Parent: <contributions-group>
              • Attributes:
                • status – String describing the author’s current status: either current or past
                • from – date the author began contributing
                • to – date the author ceased contributing
                • position – position of the contributor for this MOD
                Only the status attribute is required.
              • Must occur at least once in a <contributions-group> tag
              • Contents: None
              • Children: None
      • <link-group>

        • Parent: <header>
        • Attributes: None
        • May occur only once
        • Children: <link>
        • <link>

          • Parent: <link-group>
          • Attributes:
            • type – Required
              One of the following:
              • dependency – A MOD that is required before the current MOD can be installed.
              • parent – Link from a contrib, language, or template back to the parent MODX file.
              • template – Link to template-specific instructions.
              • language – Link to instructions for installing a non-English translation.
              • contrib – Link to a contribution, for example an additional feature or upgrade from an older version.
              • template-lang – Link to a template and language specific instruction.
              • text – Link to a text file.
              • uninstall – Link to uninstall instructions.
            • href – Required – Complete link (relative or absolute) to the needed instructions. The href is usually a relative link for all link types except dependency
            • lang – Required – ISO language code for the language the link title is written in
            • realname – Optional – The real name of the style or language the file this links to.
          • Must occur at least once in a <link-group> tag
          • Children: None
          • Contents:
            • String – Link title written in the language specified by the lang attribute
      • <mod-version>

        • Parent: <header>
        • Must occur exactly once in a <header> tag
        • Children: None
        • Contents: String – Version number compatible with PHP's version_compare. Notably:
          • All versions below 1.0.0 are development versions
      • <installation>

        • Parent: <header>
        • Must occur exactly once in a <header> tag
        • Children: <level>, <time>, <target-version>
        • Contents: none
        • <level>

          • Parent: <installation>
          • Must occur exactly once in an <installation> tag
          • Children: None
          • Contents: String – easy, intermediate, or advanced
        • <time>

          • Parent: <installation>
          • Must occur exactly once in an <installation> tag
          • Children: None
          • Contents: Integer – Estimated time needed to install this MOD by hand, in seconds.
        • <target-version>

          • Parent: <installation>
          • Must occur exactly once in an <installation> tag
          • Children: None
          • Contents: Version of phpBB for which the MOD was developed. This should be an exact version, for example 2.0.23.
      • <history>

        • Parent: <header>
        • May occur multiple times
        • Children: <entry>
        • Contents: None
        • <entry>

          • Parent: <history>
          • Must occur at least once in a <history> tag
          • Children: <date>, <rev-version>, <changelog>
          • Contents: None
          • <date>

            • Parent: <entry>
            • Must occur exactly once in an <entry> tag
            • Children: None
            • Contents: String – A Date in the format specified by ISO 8601, or in other words YYYY-MM-DD
          • <rev-version>

            • Parent: <entry>
            • Must occur exactly once in an <entry> tag
            • Children: None
            • Contents: String – The old MOD version
            • Note: <entry> tags should be sorted by the rev-version that they contain, in either increasing or decreasing order
          • <changelog>

            • Parent: <entry>
            • Must occur at least once in an <entry> tag
            • Children: <change>
            • Contents: None
            • Attributes:
              • lang - Required - ISO language code for the language in which the change is written
            • <change>

              • Parent: <changelog>
              • Must occur at least once in a <changelog> tag
              • Children: None
              • Contents: String – The list of changes, written in the language specified by the lang of the changelog tag
      • <meta>

        • Parent: <header>
        • May occur multiple times
        • Children: None
        • Attributes:
          • name - Required - Name of Meta tag
          • content - Required - Value of meta information
        • Contents: None
      • <license>

        • Parent: <header>
        • Must occur exactly once in a <header> tag
        • Children: None
        • Contents: String – The name of the license the MOD is released under, along with a URI to the full text of that license
    • <action-group>

      • Parent: <mod>
      • Must occur exactly once in a <mod> tag
      • Children: <open>, <sql>, <diy-instructions>, <copy>, <delete>, <php-installer>
      • Contents: None
      • <sql>

        • Parent: <action-group>
        • May occur multiple times
        • Attributes:
          • dbms – String – The SQL dialect in use for the query. Can be one of the following: firebird, mssql, mysql_40, mysql_41, oracle, postgres, sqlite, sql-parser . This attribute is optional, and defaults to sql-parser if it is not supplied.
        • Children: None
        • Contents: The SQL query to perform, in the dialect specified by dbms. Multiple SQL queries are allowed within one <sql> tag, separated by a line feed.
      • <copy>

        • Parent: <action-group>
        • May occur multiple times
        • Children: <file>
        • Contents: None
        • <file>

          • Parent: <copy>
          • May occur multiple times in a <copy> tag
          • Attributes:
            • from – String – Required - Relative path from the current MODX file for the source file. Example: root/survey.php. Can also be a wildcard match using *.* Example: root/*.*
            • to – String – Required - Relative path from the phpBB root to the destination of the file. Should be an exact filename if an exact file name was given in the from attribute, or a directory name if a wildcard was used.
          • Children: None
          • Contents: None
      • <delete>

        • Parent: <action-group>
        • May occur multiple times
        • Children: <file>
        • Contents: None
        • <file>

          • Parent: <delete>
          • May occur multiple times in a <delete> tag
          • Attributes:
            • name – String – Required - Path from forum root to the file or directory to delete. Can also be a wildcard match using *.* Example: includes/my_mod/*.*
          • Children: None
          • Contents: None
      • <open>

        • Parent: <action-group>
        • May occur multiple times in an <action-group> tag
        • Attributes:
          • src – String – Relative path from the phpBB root for the file to open. For example, includes/functions.php
        • Children: <edit>
        • Contents: None
        • <edit>

          • Parent: <open>
          • Must occur at least one in an <open> tag. Every discreet change to a file should be wrapped in its own edit tag, regardless of the number of children it contains.
          • Children: <find>, <action>, <inline-edit>, <comment>, <remove>
          • Contents: None
          • <find>

            • Parent: <edit>
            • Must occur at least once in an <edit> tag.
            • Children: None
            • Contents: String – The portion of the file to find.
            • Note: <find> tags in the MODX file should be in the order that the find targets appear in the file. In other words, a processor of the MODX file should never need to go backwards in the file to locate all of the finds. When there are multiple finds within a single edit tag, the processor should handle all finds before any actions.
          • <remove>

            • Parent: <edit>
            • May occur only once in an <edit> tag.
            • Children: None
            • Contents: String – The portion of the file to find and delete.
            • Note: If the code to remove is unique for that file you do not need a preceding find tag, but can be good to make sure the right code gets deleted.
          • <action>

            • Parent: <edit>
            • May occur multiple times. There must be at least one <action> or <inline-edit> tag within an <edit> tag.
            • Children: None
            • Attributes:
              • type – String – One of these choices: after-add, before-add, replace-with, operation
              • The syntax for the operation action is a bit obscure because it uses tokens. The find action would have a token like this:
                colspan="{:%1}"
                The operation action would look like this:
                {:%1} + 1
                The end result is that the colspan is increased by one.
            • Contents: String – The string to add before the find, add after the find, replace the find with, or the operation string described above
          • <inline-edit>

            • Parent: <edit>
            • May occur multiple times. There must be at least one <inline-edit> or <action> tag within an <edit> tag.
            • Children: <inline-find>, <inline-action>, <inline-remove>
            • Contents: None
            • <inline-find>

              • Parent: <inline-edit>
              • Must occur at least once in an <inline-edit> tag. May occur many times, and should be processed like the <find> tag.
              • Children: None
              • Contents: String – The find target
              • Note: <inline-find> tags may not contain line breaks
            • <inline-remove>

              • Parent: <inline-edit>
              • May occur only once in an <inline-edit> tag. Should be processed like the <remove> tag.
              • Children: None
              • Contents: String – Code to find and delete.
              • Note: <inline-remove> tags may not contain line breaks
            • <inline-action>

              • Parent: <inline-edit>
              • Must occur at least once in an <inline-edit> tag
              • Children: None
              • Attributes:
                • type – Required – One of the following: after-add, before-add, replace, or operation.
              • Contents: String – The string to add inline after, add inline before, replace the inline find with, or perform a mathematical operation on. Note that the inline-action tag may not contain line breaks
          • <comment>

            • Parent: <edit>
            • May occur multiple times in an <edit> tag.
            • Children: None
            • Attributes:
              • lang – Required – ISO language code for the language in which the comment is written
            • Contents: String – Comment pertaining to the edit that is in progress
      • <php-installer>

        • Parent: <action-group>
        • Attributes: None
        • May occur only once
        • Children: None
        • Contents: String – Path from forum root to a php install file that needs to be run in order to complete the installation.
      • <diy-instructions>

        • Parent: <action-group>
        • May occur multiple times in an <action-group> tag
        • Attributes:
          • lang – Required – ISO Code for the language in which the Do It Yourself instructions are written
        • Contents: String – The Do It Yourself Instructions, or instructions that cannot be described accurately using the other MODX commands