Category:Package SDK: Difference between revisions From Online Manual

Jump to: navigation, search
No edit summary
(Adds info about the <hook /> element)
 
(5 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This software development kit, for package and mod developers, is here to help people quickly begin to create packages and modifications for SMF.
This software development kit, for package and mod developers, is here to help people quickly begin to create packages and modifications for SMF.


Download the entire SDK from the [http://www.simplemachines.org/community/index.php?action=dlattach;topic=20319.0;attach=93904 community forum]
Download the entire SDK from the [https://www.simplemachines.org/community/index.php?topic=20319.0 community forum]


[[Category:Developing SMF]]
 
----
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>'''
**Must encompass all other elements in the file.
**'''Attributes''':
***''xmlns'': defaults to "http://www.simplemachines.org/xml/package-info"; optional
 
*'''<id></id>'''
**Contains the id of the package. Should be in the format of [username]:[package name]. For instance [i]sleepy:LeetMod[/i] 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
***'''&lt;code>&lt;/code>''' or '''&lt;code />''' (for use with type="file" only)
****Filename of a php file to be executed.
****Deprecated use in SMF 2.0, please use <database> in SMF 2.0 or higher
****'''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
***'''<hook />'''
****Add a function to an integration hook, or remove a function from an integration hook.
****Only exists in SMF 2.1 or higher
****'''Optional''': Yes
****'''Attributes''':
*****hook: the name of the integration hook as found in SMF
*****function: the name of the function to call
*****file: the path to the file that contains the function. In most cases, this will be a file added to the Sources directory by your mod, so you can use "$sourcedir/MyModFile.php" (replacing "MyModFile.php" with the actual file name).
*****reverse: if "true" removes the function from the integration hook (used for uninstalling); defaults to "false"; 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
 
{{Developing SMF}}

Latest revision as of 17:34, 3 February 2022

This software development kit, for package and mod developers, is here to help people quickly begin to create packages and modifications for SMF.

Download the entire SDK from the community forum



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.

  • <id></id>
    • Contains the id of the package. Should be in the format of [username]:[package name]. For instance [i]sleepy:LeetMod[/i] 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
      • <code></code> or <code /> (for use with type="file" only)
        • Filename of a php file to be executed.
        • Deprecated use in SMF 2.0, please use <database> in SMF 2.0 or higher
        • 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
      • <hook />
        • Add a function to an integration hook, or remove a function from an integration hook.
        • Only exists in SMF 2.1 or higher
        • Optional: Yes
        • Attributes:
          • hook: the name of the integration hook as found in SMF
          • function: the name of the function to call
          • file: the path to the file that contains the function. In most cases, this will be a file added to the Sources directory by your mod, so you can use "$sourcedir/MyModFile.php" (replacing "MyModFile.php" with the actual file name).
          • reverse: if "true" removes the function from the integration hook (used for uninstalling); defaults to "false"; 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

Pages in category "Package SDK"

The following 3 pages are in this category, out of 3 total.



Advertisement: