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 – 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
<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
- May occur only once
- Contents: String – The MOD author’s real name
<username>
- Parent: <author>
- Attributes: None
- Must occur exactly once in an <author> tag
- Contents: String – The author’s username at phpBB.com
- 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>
- 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
- May occur only once
- 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
- 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
- type – Required
- 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 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>
- 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
- Contents: String – Information hidden by the standard XSL. Usually used for notes about generators
<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>
- 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: 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 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
<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>
- 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.
<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} + 1The 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>
- 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 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
<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
