Package-info.xml: Difference between revisions From Online Manual

Jump to: navigation, search
m (Bot: Automated text replacement (-< +<))
(Add new 2.1 package tags)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Before reading on, you should know some definitions used in this documentation:
Before reading on, you should know some definitions used in this documentation:
* ''element'' aka ''tag'': an instruction used to tell the package manager what to do. ie <install&gt;</install&gt;
* ''element'' aka ''tag'': an instruction used to tell the package manager what to do. ie <install></install>
* ''attribute'' aka ''property'': an additional value used to describe an element
* ''attribute'' aka ''property'': an additional value used to describe an element
* ''inline'': code or text that is written in this file instead of coming from an outside source
* ''inline'': code or text that is written in this file instead of coming from an outside source
* ''file'': the name or location of a file to be used instead of "inline"
* ''file'': the name or location of a file to be used instead of "inline"
* ''location'' aka ''path'': the location on the computer of a directory and/or file</ul>
* ''location'' aka ''path'': the location on the computer of a directory and/or file
There are also variables that may be used in place of a path.
There are also variables that may be used in place of a path.
* $sourcedir: The directory where the source files are contained (ie Post.php, Admin.php, etc)
* $sourcedir: The directory where the source files are contained (ie Post.php, Admin.php, etc)
Line 12: Line 12:
* $imagesdir: The directory of the images for each theme
* $imagesdir: The directory of the images for each theme
* $languagedir: The location of the directories of language files
* $languagedir: The location of the directories of language files
* $smileysdir: The location of the smiley directory</ul>
* $smileysdir: The location of the smiley directory
'''package-info.xml'''
'''package-info.xml'''
''All elements, unless otherwise stated, are not optional and contain no attributes.''
''All elements, unless otherwise stated, are not optional and contain no attributes.''


* '''<package-info&gt;</package-info&gt;'''
* '''<package-info></package-info>'''
* Must encompass all other elements in the file.
** Must encompass all other elements in the file.
* '''Attributes''':
** '''Attributes''':
* ''xmlns'': defaults to ''[http://www.simplemachines.org/xml/package-info http://www.simplemachines.org/xml/package-info]''; optional
*** ''xmlns'': defaults to ''[http://www.simplemachines.org/xml/package-info http://www.simplemachines.org/xml/package-info]''; optional
* '''<id&gt;</id&gt;'''
* '''<id></id>'''
 
** Contains the id of the package. Should be in the format of [username]:[package name]. For instance ''sleepy:LeetMod'' When submitting a mod to the mod site, the username should be your username from [http://www.simplemachines.org www.simplemachines.org]
* Contains the id of the package. Should be in the format of [username]:[package name]. For instance ''sleepy:LeetMod'' When submitting a mod to the mod site, the username should be your username from [http://www.simplemachines.org www.simplemachines.org]
* '''<name></name>'''
* '''<name&gt;</name&gt;'''
** Contains the name of the package.
 
* '''<type></type>'''
* Contains the name of the package.
** The type of package - "avatar", "language", or "modification".
* '''<type&gt;</type&gt;'''
* '''<version></version>'''
 
** The package's current version.
* The type of package - "avatar", "language", or "modification".
* '''<install></install>, <upgrade></upgrade>, and <uninstall></uninstall>'''
* '''<version&gt;</version&gt;'''
** Actions taken on installation. The elements and their attributes are the same for the install, upgrade, and uninstall elements.
 
** '''Attributes''':
* The package's current version.
*** ''for'': What versions to install/upgrade/uninstall for. Comma delimited string with ranges such as "1.0-1.5,2.0"; optional
* '''<install&gt;</install&gt;, <upgrade&gt;</upgrade&gt;, and <uninstall&gt;</uninstall&gt;'''
*** ''from'': Upgrade Only; What mod versions they are upgrading from. Comma delimited string with ranges such as "1.0-1.5,2.0"; optional
 
** '''Elements''':
* Actions taken on installation. The elements and their attributes are the same for the install, upgrade, and uninstall elements.
*** '''<readme></readme> or <readme /> (for use with type="file" only)'''
* '''Attributes''':
**** Filename of the readme file
 
**** '''Optional''': Yes
* ''for'': What versions to install/upgrade/uninstall for. Comma delimited string with ranges such as "1.0-1.5,2.0"; optional
**** '''Attributes''':
* ''from'': Upgrade Only; What mod versions they are upgrading from. Comma delimited string with ranges such as "1.0-1.5,2.0"; optional
***** lang: which language this readme applies to; optional
* '''Elements''':
***** parsebbc: whether or not to parse bbcode in the readme; optional; defaults to false
 
***** type: "inline" or "file"; defaults to "file"; optional
* '''<readme&gt;</readme&gt; or <readme /&gt; (for use with type="file" only)'''
*** '''<hook />'''
 
**** Adds an integration function
* Filename of the readme file
**** Only exists in SMF 2.1 or higher
* '''Optional''': Yes
**** '''Optional''': Yes
* '''Attributes''':
**** '''Attributes''':
 
***** hook: the complete hook name
* lang: which language this readme applies to; optional
***** function: the function name. Can be a call to a method via Class::method
* parsebbc: whether or not to parse bbcode in the readme; optional; defaults to false
***** file: the file. Must include one of the following wildcards: $boarddir, $sourcedir, $themedir, example: $sourcedir/Test.php
* type: "inline" or "file"; defaults to "file"; optional
***** object: indicates if your class will be instantiated when its respective hook is called. If true, your function must be a method
* '''<code&gt;</code&gt; or <code /&gt; (for use with type="file" only)'''
***** reverse: removes the integration function
 
*** '''<credits></credits>'''
* Filename of a php file to be executed.
**** Title of the package
* Deprecated use in SMF 2.0, please use <database&gt; in SMF 2.0 or higher
**** Only exists in SMF 2.1 or higher
* '''Optional''': Yes
**** '''Optional''': Yes
* '''Attributes''':
**** '''Attributes''':
 
***** url: link to third party website if any
* type: "inline" or "file"; defaults to "file"; optional</ul></ul>
***** license: name of the chosen package license
* '''<database&gt;</database&gt; or <database /&gt; (for use with type="file" only)'''
***** licenseurl: link to the full license contents
 
***** copyright: copyright year
* Filename of a database code to be executed.
*** '''<nowiki><code></code> or <code /> </nowiki>(for use with type="file" only)'''
* Only exists in SMF 2.0 or higher
**** Filename of a php file to be executed.
* '''Optional''': Yes
**** '''Optional''': Yes
* '''Attributes''':
**** '''Attributes''':
 
***** type: "inline" or "file"; defaults to "file"; optional
* type: "inline" or "file"; defaults to "file"; optional
*** '''<database></database> or <database /> (for use with type="file" only)'''
* '''<modification&gt;</modification&gt; or <modification /&gt; (for use with type="file" only)'''
**** Filename of a database code to be executed.
 
**** Only exists in SMF 2.0 or higher
* Instructions to take for a modification.
**** '''Optional''': Yes
* '''Optional''': Yes
**** '''Attributes''':
* '''Attributes''':
***** type: "inline" or "file"; defaults to "file"; optional
 
*** '''<modification></modification> or <modification /> (for use with type="file" only)'''
* type: if "inline", you may use the <file&gt;, <operation&gt;, <search&gt;, and <add&gt; elements listed in the modification.xml documentation."inline" or "file"; defaults to "file"; optional
**** Instructions to take for a modification.
* reverse: reverse the instructions; "true" or "false"; defaults to "false"; optional
**** '''Optional''': Yes
* format: this documentation only covers xml formatted modifications and it is recommended that you use this format; "xml" or "boardmod"; defaults to "xml"; optional
**** '''Attributes''':
* '''<create-dir /&gt;'''
***** type: if "inline", you may use the <file>, <operation>, <search>, and <add> elements listed in the modification.xml documentation."inline" or "file"; defaults to "file"; optional
 
****** reverse: reverse the instructions; "true" or "false"; defaults to "false"; optional
* Create a new directory.
****** format: this documentation only covers xml formatted modifications and it is recommended that you use this format; "xml" or "boardmod"; defaults to "xml"; optional
* '''Optional''': Yes
*** '''<create-dir />'''
* '''Attributes''':
**** Create a new directory.
 
**** '''Optional''': Yes
* name: the name of the directory
**** '''Attributes''':
* destination: the path of the directory where you want to create this new directory
***** name: the name of the directory
* '''<create-file /&gt;'''
***** destination: the path of the directory where you want to create this new directory
 
*** '''<create-file />'''
* Create a blank file.
**** Create a blank file.
* '''Optional''': Yes
**** '''Optional''': Yes
* '''Attributes''':
**** '''Attributes''':
 
***** name: the name of the file
* name: the name of the file
***** destination: the path of the directory where you want to create this new file
* destination: the path of the directory where you want to create this new file
*** '''<require-dir />'''
* '''<require-dir /&gt;'''
**** Require a directory and all files in it from inside the package.
 
**** '''Optional''': Yes
* Require a directory and all files in it from inside the package.
**** '''Attributes''':
* '''Optional''': Yes
***** from: the path to the directory
* '''Attributes''':
***** name: the name of the directory
 
***** destination: the path of where you want to put this directory>
* from: the path to the directory
*** '''<require-file />'''
* name: the name of the directory
**** Require a file from inside the package.
* destination: the path of where you want to put this directory>
**** '''Optional''': Yes
* '''<require-file /&gt;'''
**** '''Attributes''':
 
***** from: the path to the file
* Require a file from inside the package.
***** name: the name of the file
* '''Optional''': Yes
***** destination: the path of where you want to put this file
* '''Attributes''':
*** '''<move-dir />'''
 
**** Move an entire directory. May also be used to rename a directory by moving it to it's parent directory with a different name.
* from: the path to the file
**** '''Optional''': Yes
* name: the name of the file
**** '''Attributes''':
* destination: the path of where you want to put this file
***** from: the path of the directory you want to move
* '''<move-dir /&gt;'''
***** name: the name of the directory
 
***** destination: the path to where you want to put the directory
* Move an entire directory. May also be used to rename a directory by moving it to it's parent directory with a different name.
*** '''<move-file />'''
* '''Optional''': Yes
**** Move a file. May also be used to rename a file by moving it to it's parent directory with a different name.
* '''Attributes''':
**** '''Optional''': Yes
 
**** '''Attributes''':
* from: the path of the directory you want to move
***** from: the path of the file you want to move
* name: the name of the directory
***** name: the name of the file
* destination: the path to where you want to put the directory
***** destination: the path to where you want to put the file
* '''<move-file /&gt;'''
*** '''<remove-dir />'''
 
**** Remove a directory and all files in it.
* Move a file. May also be used to rename a file by moving it to it's parent directory with a different name.
**** '''Optional''': Yes
* '''Optional''': Yes
**** '''Attributes''':
* '''Attributes''':
***** name: the name and path of the directory to be removed
 
*** '''<remove-file />'''
* from: the path of the file you want to move
**** Remove a file.
* name: the name of the file
**** '''Optional''': Yes
* destination: the path to where you want to put the file
**** '''Attributes''':
* '''<remove-dir /&gt;'''
***** name: the name and path of the file to be removed
 
*** '''<redirect></redirect> or <redirect />'''
* Remove a directory and all files in it.
**** Redirect after install/upgrade/uninstall.
* '''Optional''': Yes
**** '''Optional''': Yes
* '''Attributes''':
**** '''Attributes''':
 
***** url: the url to redirect to; Required. "$boardurl", "$scripturl", and "$session_id" are accepted.
* name: the name and path of the directory to be removed
***** type: inline or file. Whether to use a file or inline text for redirect text.
* '''<remove-file /&gt;'''
***** timeout: Time until the redirect occurs. Default: 5 seconds
 
* Remove a file.
* '''Optional''': Yes
* '''Attributes''':
 
* name: the name and path of the file to be removed
* '''<redirect&gt;</redirect&gt; or <redirect /&gt;'''
 
* Redirect after install/upgrade/uninstall.
* '''Optional''': Yes
* '''Attributes''':
 
* url: the url to redirect to; Required. "$boardurl", "$scripturl", and "$session_id" are accepted.
* type: inline or file. Whether to use a file or inline text for redirect text.
* timeout: Time until the redirect occurs. Default: 5 seconds


[[Category:Developing SMF]]
[[Category:Developing SMF]]
[[Category:Package SDK]]
[[Category:Package SDK]]

Latest revision as of 18:04, 12 July 2019

Before reading on, you should know some definitions used in this documentation:

  • element aka tag: an instruction used to tell the package manager what to do. ie <install></install>
  • attribute aka property: an additional value used to describe an element
  • inline: code or text that is written in this file instead of coming from an outside source
  • file: the name or location of a file to be used instead of "inline"
  • location aka path: the location on the computer of a directory and/or file

There are also variables that may be used in place of a path.

  • $sourcedir: The directory where the source files are contained (ie Post.php, Admin.php, etc)
  • $boarddir: The directory where index.php is found. Usually one level beneath the source files are contained.
  • $avatardir: The directory where the avatars may be found
  • $themedir: The directory where the directories of the themes are located
  • $imagesdir: The directory of the images for each theme
  • $languagedir: The location of the directories of language files
  • $smileysdir: The location of the smiley directory

package-info.xml All elements, unless otherwise stated, are not optional and contain no attributes.

  • <package-info></package-info>
  • <id></id>
    • Contains the id of the package. Should be in the format of [username]:[package name]. For instance sleepy:LeetMod When submitting a mod to the mod site, the username should be your username from www.simplemachines.org
  • <name></name>
    • Contains the name of the package.
  • <type></type>
    • The type of package - "avatar", "language", or "modification".
  • <version></version>
    • The package's current version.
  • <install></install>, <upgrade></upgrade>, and <uninstall></uninstall>
    • Actions taken on installation. The elements and their attributes are the same for the install, upgrade, and uninstall elements.
    • Attributes:
      • for: What versions to install/upgrade/uninstall for. Comma delimited string with ranges such as "1.0-1.5,2.0"; optional
      • from: Upgrade Only; What mod versions they are upgrading from. Comma delimited string with ranges such as "1.0-1.5,2.0"; optional
    • Elements:
      • <readme></readme> or <readme /> (for use with type="file" only)
        • Filename of the readme file
        • Optional: Yes
        • Attributes:
          • lang: which language this readme applies to; optional
          • parsebbc: whether or not to parse bbcode in the readme; optional; defaults to false
          • type: "inline" or "file"; defaults to "file"; optional
      • <hook />
        • Adds an integration function
        • Only exists in SMF 2.1 or higher
        • Optional: Yes
        • Attributes:
          • hook: the complete hook name
          • function: the function name. Can be a call to a method via Class::method
          • file: the file. Must include one of the following wildcards: $boarddir, $sourcedir, $themedir, example: $sourcedir/Test.php
          • object: indicates if your class will be instantiated when its respective hook is called. If true, your function must be a method
          • reverse: removes the integration function
      • <credits></credits>
        • Title of the package
        • Only exists in SMF 2.1 or higher
        • Optional: Yes
        • Attributes:
          • url: link to third party website if any
          • license: name of the chosen package license
          • licenseurl: link to the full license contents
          • copyright: copyright year
      • <code></code> or <code /> (for use with type="file" only)
        • Filename of a php file to be executed.
        • Optional: Yes
        • Attributes:
          • type: "inline" or "file"; defaults to "file"; optional
      • <database></database> or <database /> (for use with type="file" only)
        • Filename of a database code to be executed.
        • Only exists in SMF 2.0 or higher
        • Optional: Yes
        • Attributes:
          • type: "inline" or "file"; defaults to "file"; optional
      • <modification></modification> or <modification /> (for use with type="file" only)
        • Instructions to take for a modification.
        • Optional: Yes
        • Attributes:
          • type: if "inline", you may use the <file>, <operation>, <search>, and <add> elements listed in the modification.xml documentation."inline" or "file"; defaults to "file"; optional
            • reverse: reverse the instructions; "true" or "false"; defaults to "false"; optional
            • format: this documentation only covers xml formatted modifications and it is recommended that you use this format; "xml" or "boardmod"; defaults to "xml"; optional
      • <create-dir />
        • Create a new directory.
        • Optional: Yes
        • Attributes:
          • name: the name of the directory
          • destination: the path of the directory where you want to create this new directory
      • <create-file />
        • Create a blank file.
        • Optional: Yes
        • Attributes:
          • name: the name of the file
          • destination: the path of the directory where you want to create this new file
      • <require-dir />
        • Require a directory and all files in it from inside the package.
        • Optional: Yes
        • Attributes:
          • from: the path to the directory
          • name: the name of the directory
          • destination: the path of where you want to put this directory>
      • <require-file />
        • Require a file from inside the package.
        • Optional: Yes
        • Attributes:
          • from: the path to the file
          • name: the name of the file
          • destination: the path of where you want to put this file
      • <move-dir />
        • Move an entire directory. May also be used to rename a directory by moving it to it's parent directory with a different name.
        • Optional: Yes
        • Attributes:
          • from: the path of the directory you want to move
          • name: the name of the directory
          • destination: the path to where you want to put the directory
      • <move-file />
        • Move a file. May also be used to rename a file by moving it to it's parent directory with a different name.
        • Optional: Yes
        • Attributes:
          • from: the path of the file you want to move
          • name: the name of the file
          • destination: the path to where you want to put the file
      • <remove-dir />
        • Remove a directory and all files in it.
        • Optional: Yes
        • Attributes:
          • name: the name and path of the directory to be removed
      • <remove-file />
        • Remove a file.
        • Optional: Yes
        • Attributes:
          • name: the name and path of the file to be removed
      • <redirect></redirect> or <redirect />
        • Redirect after install/upgrade/uninstall.
        • Optional: Yes
        • Attributes:
          • url: the url to redirect to; Required. "$boardurl", "$scripturl", and "$session_id" are accepted.
          • type: inline or file. Whether to use a file or inline text for redirect text.
          • timeout: Time until the redirect occurs. Default: 5 seconds


Advertisement: