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


  • <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 – an ISO language code – required
    • Must occur at least once
    • Children: None
    • Contains:
      • String: The MOD title in the language specified by the lang attribute
  • <description>

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

    • Parent: <header>
    • Attributes
      • lang – an ISO language code – required
    • Optional, can have multiple occurrences
    • Children: None
    • Contains:
      • String: Any author notes. Should be displayed by any automatic installers
  • <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
    • Contents: None
  • <realname>

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

    • Parent: <author>
    • Attributes: None
    • Required, may occur only once
    • Contents: String – The author’s username at phpBB.com
    • Children: None
  • <homepage>

    • Parent: <author>
    • Attributes: None
    • Optional, may occur only once in an <author> tag
    • Contents: String – A complete URI to the MOD author’s homepage
    • Children: None
  • <contributions>

    • Parent: <author>
    • Attributes:
      • status – String describing the author’s current status: either current or past
      • from – Year the author began contributing
      • to – Year the author ceased contributing
    • Optional, may occur only once in an <author> tag
    • Contents: None
    • Children: None
  • <link-group>

    • Parent: <header>
    • Attributes: None
    • May occur only once. <link-group> is an optional tag.
    • 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
      • 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
    • Occurs 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>
    • Occurs exactly once in a <header> tag
    • Children: None
    • Contents: String – Version number compliant with the phpBB versioning system. Notably:
      • All versions less 1.0.0 are development versions
      • All versions with an odd middle digit are development versions
  • <installation>

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

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

    • Parent: <installation>
    • Occurs 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>
    • Occurs 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>
    • Occurs at most once in an <installation> tag. <history> is an optional tag.
    • Children: entry
    • Contents: None
  • <entry>

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

    • Parent: <entry>
    • Occurs 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>
    • Occurs 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>
    • Occurs 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>
    • Occurs 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>
    • Optional, may occur many times
    • Children: None
    • Contents: String – Information hidden by the standard XSL. Usually used for notes about generators
  • <license>

    • Parent: <header>
    • Occurs 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>
    • Occurs exactly once in a <mod> tag
    • Children: open, sql, diy-instructions, copy
    • Contents: None
  • <sql>

    • Parent: <action-group>
    • May occur any number of times in an <action-group> tag.
    • Attributes:
      • dbms – String – The SQL dialect in use for the query. Can be one of the following: mysql, mysql_40, mysql_41, mysqli, mysql4, mssaccess, oracle, postgres, db2, firebird, 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 any number of times in an <action-group> tag
    • Children: <file>
    • Contents: None
  • <file>

    • Parent: Copy
    • May occur any number of times in a <copy> tag
    • Attributes:
      • from – String – Required - Relative path from the current MODX file for the source file. Required. 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
  • <open>

    • Parent: <action-group>
    • May occur any number of 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>
    • Occurs 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
    • Contents: None
  • <find>

    • Parent: <edit>
    • Occurs at least once in an <edit> tag.
    • Children: None
    • Contents: String – The portion of the file to find. 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.
  • <action>

    • Parent: <edit>
    • Optional and may occur many 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

      A note on the operation action: The syntax 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>
    • Optional and may occur many times. There must be at least one <inline-edit> or <action> tag within an <edit> tag.
    • Children: inline-find, inline-action
    • 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-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 any number of 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
  • <diy-instructions>

    • Parent: <action-group>
    • May occur any number of 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