module.xml

See also: ApiModules, ApiDocs

The module.xml file is used to describe a module, including it's display name, version, type, category, and the menu items it provides.

Example: 

<module>
	<rawname>timeconditions</rawname>
	<name>Time Conditions</name>
	<version>1.0.1</version>
        <description>
                Allows time-based conditional destinations.
                
                For example, you can create a time condition that goes to a ring group from 8-5 Monday to Friday, and an IVR at any other time.
        </description>
	<type>setup</type>
	<category>Basic</category>
	<menuitems>
		<timeconditions>Time Conditions</timeconditions>
	</menuitems>
        <depends>
                <module>core</module>
                <module>ivr gt1.0</module>
                <version>ge2.2</version>
                <engine>asterisk 1.2</engine>
                <file>%ASTETCDIR%/testfile</file>
        </depends>
	<location>release/timeconditions-1.0.tgz</location>
	<info>http://freepbx.org/wiki/TimeConditions</info>
        <changelog>
                *1.1*  Now supports easter calculations
                       Fixed bug #234567 and #3456789
                *1.0.1* Fixed bug #123456
                *1.0* First release
        </changelog>
</module>

The rawname should be unique, and should exactly match the name of the directory the module is stored in. The following keys & values should be defined:

  • rawname
    • The unique rawname that must match the module's directory name
  • name
    • The display name for the module
  • description added in 2.2
    • A description that shows up on the module admin page. Can be multiple lines
  • version
    • The version number of this module
    • Be sure to increment this when upgrading the module. Numeric versions only (1.2, 1.5.1.4 etc)
  • type
    • setup or tool. setup tells freePBX that this module should appear in the "Setup" page. type=tool would result in the module going in the "Tools" page.
  • category
    • Controls where in the module repository it shows up. Modules are grouped by category.
    • Standard categories are "Modules" "Core" "Addons"
  • menuitems
    • The key describes the unique menuid. The value describes the display name. There can be multiple menuitems defined. The menuid should be unique, and will link to the page.menuid.php for this module.
    • eg, <timecondition>Time Conditions</timecondition> shows "Time Conditions" on the menu, and links to page.timecondition.php.
    • The text displayed (ie: "Time Conditions") will be automatically translated if necessary/available.
    • A number of attributes are supported that modify the menuitem
      • category - The category this item should show up in. If not specified, defaults to the module category.
      • display - The menuitem to display (optional, defaults to the menuitem tag name). This is to allow a page to show up on the menu twice, which requires two distinct tag names. (added in 2.3b2)
      • type - The "type" this item should show up in (really, this is the page). Currently only "setup" and "tools" are valid options here, in the future this will probably be expanded upon. Defaults to the same type as the module.
      • href - Override the default link location, and link to this URL instead. This is really useful for linking to custom pages, and can contain a full url starting with http:// or a path starting with a single slash which refers to the top level directory of your web server. For example /help/me as a path would convert to http://www.somesite.com/help/me. Note: the old syntax of having an <a> tag inside the link is no longer supported!
      • target - The target frame for the link. This should normally be used when href is specified, and set to _blank to open in a new window.
      • sort - The sort priority, from -10 to 10. A lower priority is displayed earlier (eg, -5 is displayed before 2). All items with the same priority are sorted alphebetically. Defaults to 0.
    • Example: 
<menuitems>
  <devices>Devices</devices>
  <did category="Inbound Call Control">Inbound Routing</did>
  <wiki type="tool" category="Support" sort="5" href="http://www.freepbx.org" target="_blank">FreePBX.org</wiki>
</menuitems>
  • location
  • info
    • The URL to more info about the module, generally a wiki page on freepbx.org.
  • depends added in 2.2
    • Sets dependencies for the module that have to be met before it can be installed.
    • Allowed depends tags are:
      • version - FreePBX version. Can be precedded by an operator: ge (>=), gt (>), eq, =, ==, lt (<), le (<=), ne, !=. If no operator is given, defaults to gt.
      • module - Depends on another module. Value is simply the name of the module, or the name of a module followed by a space, followed by a version number (which can include operators as described above).
      • engine - The telephony engine (asterisk) name and version required. Follows the same conventions as a module.
      • file - A file that must exist on the filesystem, using an absolute path. (can parse out variables from amportal.conf using %AMPWEBROOT% syntax)
    • All the values in depends are combined together with AND - that is, everything must match for the module to be installed.
      • For the future, we may put in a smarter parsing engine that can interpret strings like "asterisk 1.2 | openpbx"
  • changelog added in 2.2
    • A paragraph describing recent changes to the module. Entries should include a version number, and be listed in reverse chronological order (newest first). The version number should be enclosed in asterisks, eg *1.2*
  • attention added in 2.2
    • A special field, similar to description, but shows up on a seperate (and default) tab. This allows for special notes (such as extra requirements, or long download times) which are brought to the user's attention before they see the download button.