Package-info.xml Help

[ptmuldoon]

Unfortunately, I know very little about xml, thus unsure of the right syntax and element names needed.

To help myself in learning, and keeping things 'neater', I'm hoping to have my mod create a new folder/directory inside the Sources and Theme Directory, and than to place the mods file in those directories (and possible subdirectories).

Do you need to first create a new directory, and than make that directory read/writable?
Or will creating the file into a yet to exist subdirectory also create that subdirectory?

When uninstalling, can you simply remove the entire directory at once?  Or remove each file first and than afterwards remove the the subdirectory that was created?

Is there a listing perhaps of the different elements used for the package-info file?

Thanks
PT

[Liam.]

Don't worry, you don't need to CHMod anything much when creating a modification. It's generally best to use the <require dir> function instead of doing separate files, if you've got a few files in the same folder (for example, 2 files in the same folder, it may be just as easy to use <require file> than dir).

You can remove the whole directory at once, simply by replaceing <require dir> with <remove dir>,

[Liam.]

As for resources, throwing onto the homepage of the Mod Site, there are a few links...

Coding Guidelines and Package SDK, the latter you should look through more

[Arantor]

To help myself in learning, and keeping things 'neater', I'm hoping to have my mod create a new folder/directory inside the Sources and Theme Directory, and than to place the mods file in those directories (and possible subdirectories).

So in the package is a Source folder and a Theme folder. Provided the directories as a whole are moved into Sources/ and Themes/ respectively, i.e. you end up with Sources/Source, it's fine to just drop the folder in and remove it.

However, if you do as some mods do, and overlay your mod's Sources/ folder onto the main forum one... DON'T try to remove it with remove-dir, because all that'll happen is the entire Sources/ folder gets eaten and everyone's unhappy.

You don't need to create the folder, generally the package manager will do this for you.

There is a master listing, which is called the DTD but it's not particularly meaningful unless you're used to reading DTDs.

Instead I'm just going to use SimpleDesk's, which uses just about every element there is

We do it file by file generally, except for the image folders, since they're atomic units (we can remove/add at will)

Code Select Expand

<?xml version="1.0"?>
<!DOCTYPE package-info SYSTEM "http://www.simplemachines.org/xml/package-info">
<package-info xmlns="http://www.simplemachines.org/xml/package-info" xmlns:smf="http://www.simplemachines.org/">
<id>SimpleDeskTeam:SimpleDesk</id>
<name>SimpleDesk - Integrated Helpdesk for Simple Machines Forum</name>
<version>1.0 Felidae</version>
<type>modification</type>

<install for="2.0 RC2, 2.0 RC3">
<!-- readme files -->
<readme lang="english" parsebbc="true" type="file">language-readme/readme.english.txt</readme>

<!-- general edits -->
<modification format="xml" type="file">install-xml/install.xml</modification>
<modification format="xml" type="file">install-xml/install-attachments.xml</modification>
<modification format="xml" type="file">install-xml/install-trackip.xml</modification>

<!-- language files -->
<require-file name="language-php/SimpleDesk.english.php" destination="$languagedir" />
<require-file name="language-php/SimpleDeskPermissions.english.php" destination="$languagedir" />
<require-file name="language-php/SimpleDeskLogAction.english.php" destination="$languagedir" />
<require-file name="language-php/SimpleDeskAdmin.english.php" destination="$languagedir" />
<require-file name="language-php/SimpleDeskWho.english.php" destination="$languagedir" />
<require-file name="language-php/SimpleDeskProfile.english.php" destination="$languagedir" />

<!-- sources -->
<require-file name="source/SimpleDesk.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-Display.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-MiscActions.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-Assign.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-Post.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-AjaxHandler.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-TicketTopicMove.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-Delete.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-Admin.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-AdminCustomField.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-AdminPermissions.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-SSI.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-MergeSplit.php" destination="$sourcedir" />
<require-file name="source/SimpleDesk-Profile.php" destination="$sourcedir" />
<require-file name="source/Subs-SimpleDesk.php" destination="$sourcedir" />
<require-file name="source/Subs-SimpleDeskAdmin.php" destination="$sourcedir" />
<require-file name="source/Subs-SimpleDeskPost.php" destination="$sourcedir" />
<require-file name="source/Subs-SimpleDeskPermissions.php" destination="$sourcedir" />

<!-- templates -->
<require-file name="template/SimpleDesk.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-Display.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-Admin.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-AdminCustomField.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-AdminPermissions.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-Assign.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-Post.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-TicketTopicMove.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-MergeSplit.template.php" destination="$themedir" />
<require-file name="template/SimpleDesk-Profile.template.php" destination="$themedir" />

<!-- images -->
<require-dir name="images/simpledesk" destination="$themes_dir/default/images" />
<require-dir name="images/shd" destination="$imagesdir/admin" />
<require-file name="images/feature_shd.png" destination="$imagesdir/admin" />

<!-- css -->
<require-file name="css/helpdesk.css" destination="$themedir/css" />
<require-file name="css/helpdesk_admin.css" destination="$themedir/css" />
<require-file name="css/helpdesk_ie6.css" destination="$themedir/css" />

<!-- scripts -->
<require-file name="scripts/helpdesk_admin.js" destination="$themedir/scripts" />
<require-file name="scripts/helpdesk.js" destination="$themedir/scripts" />

<!-- database changes -->
<database>install.php</database>

<redirect url="?action=admin;area=corefeatures#js_feature_shd" />
</install>

<uninstall for="2.0 RC2, 2.0 RC3">
<!-- database changes, undone -->
<database>uninstall-optional.php</database>
<code type="file">uninstall-required.php</code>

<!-- general edits, undone -->
<modification format="xml" type="file" reverse="true">install-xml/install.xml</modification>
<modification format="xml" type="file" reverse="true">install-xml/install-attachments.xml</modification>
<modification format="xml" type="file" reverse="true">install-xml/install-trackip.xml</modification>

<!-- language files, removed -->
<remove-file name="$languagedir/SimpleDesk.english.php" />
<remove-file name="$languagedir/SimpleDeskPermissions.english.php" />
<remove-file name="$languagedir/SimpleDeskLogAction.english.php" />
<remove-file name="$languagedir/SimpleDeskAdmin.english.php" />
<remove-file name="$languagedir/SimpleDeskWho.english.php" />
<remove-file name="$languagedir/SimpleDeskProfile.english.php" />

<!-- source files, removed -->
<remove-file name="$sourcedir/SimpleDesk.php" />
<remove-file name="$sourcedir/SimpleDesk-Display.php" />
<remove-file name="$sourcedir/SimpleDesk-MiscActions.php" />
<remove-file name="$sourcedir/SimpleDesk-Assign.php" />
<remove-file name="$sourcedir/SimpleDesk-Post.php" />
<remove-file name="$sourcedir/SimpleDesk-AjaxHandler.php" />
<remove-file name="$sourcedir/SimpleDesk-TicketTopicMove.php" />
<remove-file name="$sourcedir/SimpleDesk-Delete.php" />
<remove-file name="$sourcedir/SimpleDesk-Admin.php" />
<remove-file name="$sourcedir/SimpleDesk-AdminCustomField.php" />
<remove-file name="$sourcedir/SimpleDesk-AdminPermissions.php" />
<remove-file name="$sourcedir/SimpleDesk-SSI.php" />
<remove-file name="$sourcedir/SimpleDesk-MergeSplit.php" />
<remove-file name="$sourcedir/SimpleDesk-Profile.php" />
<remove-file name="$sourcedir/Subs-SimpleDesk.php" />
<remove-file name="$sourcedir/Subs-SimpleDeskAdmin.php" />
<remove-file name="$sourcedir/Subs-SimpleDeskPost.php" />
<remove-file name="$sourcedir/Subs-SimpleDeskPermissions.php" />

<!-- template files, removed -->
<remove-file name="$themedir/SimpleDesk.template.php" />
<remove-file name="$themedir/SimpleDesk-Display.template.php" />
<remove-file name="$themedir/SimpleDesk-Admin.template.php" />
<remove-file name="$themedir/SimpleDesk-AdminCustomField.template.php" />
<remove-file name="$themedir/SimpleDesk-AdminPermissions.template.php" />
<remove-file name="$themedir/SimpleDesk-Assign.template.php" />
<remove-file name="$themedir/SimpleDesk-Post.template.php" />
<remove-file name="$themedir/SimpleDesk-TicketTopicMove.template.php" />
<remove-file name="$themedir/SimpleDesk-MergeSplit.template.php" />
<remove-file name="$themedir/SimpleDesk-Profile.template.php" />

<!-- images, removed -->
<remove-dir name="$themes_dir/default/images/simpledesk" />
<remove-dir name="$imagesdir/admin/shd" />
<remove-file name="$imagesdir/admin/feature_shd.png" />

<!-- css, removed -->
<remove-file name="$themedir/css/helpdesk.css" />
<remove-file name="$themedir/css/helpdesk-admin.css" />
<remove-file name="$themedir/css/helpdesk-ie6.css" />

<!-- scripts, removed -->
<remove-file name="$themedir/scripts/helpdesk-admin.js" />
<remove-file name="$themedir/scripts/helpdesk.js" />
</uninstall>
</package-info>

So, breaking that down, these are all in the <install> block as actions to perform on an installation.

Code Select Expand

<readme lang="english" parsebbc="true" type="file">language-readme/readme.english.txt</readme>

Display the readme held in the given filename (as it is a file, rather than an inline readme), treat it as having bbcode and this one's English. You can in theory have multiple languages of readme in 2.0 RC2 and up, by specifying different lang parameters, provided that the English one is last.

Code Select Expand

<modification format="xml" type="file">install-xml/install.xml</modification>

Apply the edits listed in that file, as it is a file. It's also in XML; there are two kinds of modification files, XML and BoardMod which few people use these days. Generally, stick to XML.

Code Select Expand

<require-file name="language-php/SimpleDesk.english.php" destination="$languagedir" />

Move the individual file into the Themes/default/languages/ directory. Package manager worries about permissions.

Similarly:

Code Select Expand

<require-file name="source/SimpleDesk.php" destination="$sourcedir" />
and

Code Select Expand

<remove-file name="$themedir/SimpleDesk.template.php" />

This manages them into the Sources directory and main templates directory respectively.

Code Select Expand

<require-dir name="images/simpledesk" destination="$themes_dir/default/images" />

This explicitly copies the images/simpledesk folder from the mod package and puts it into Themes/default/images/simpledesk. Note the use of $themes_dir rather than $themedir. This is absolutely intentional.

$themedir doesn't just refer to an individual theme's directory, necessarily. If you edit a file in $themedir, the edit is replicated to any custom themes too.

$themes_dir points to the folder where all the themes live, i.e. Themes/ itself. Since we explicitly refer to every image under our control through $settings['default_images_url'], we put it there deliberately to avoid copying images for every single theme it's installed for.

Code Select Expand

<require-dir name="images/shd" destination="$imagesdir/admin" />

This copies a given folder in to the theme's images directory. Since we don't have proper control over that (because it's for the admin menu), we allow it to use the normal method - this creates the folder Themes/{whatever}/images/admin/shd and puts all the files in it.

Code Select Expand

<require-file name="images/feature_shd.png" destination="$imagesdir/admin" />

And this installs a single file into the images/admin directory itself, which is Themes/{whatever}/images/admin/ - this is for the Core Features page.

Code Select Expand

<database>install.php</database>

Runs the code specified in install.php on install, every time. The package manager also kicks off db_extend('packages') for us which is needed for the higher functions like db_create_table. If <database> is used, and the proper functions are used in 2.0, new tables/columns get logged and the offer to remove them on uninstall is presented.

In 1.1, <code> should be used instead.

Code Select Expand

<redirect url="?action=admin;area=corefeatures#js_feature_shd" />

Lastly, this tells the package manager what to do next after installation. There is a time property to set how long there is before auto redirection but I forget how to set that.


<uninstall> is mostly self explanatory given what <install> does. The key thing is <database> and <code>

<database> here runs when the user selects the option to uninstall all mod data. <code> on uninstall runs every single time regardless. We use the two together to make sure we clean up properly.


Sorry to throw that all at you, but that's the quickest way I know of explaining it. You're also encouraged to grab SD 1.0 final (this isn't the actual file from 1.0 final, this is the 1.1 dev build, I just haven't changed the version number yet ) and install it to see exactly what it does versus the instructions.

[ptmuldoon]

Thanks Guys, that should get me going some.

I'm looking to have something like

Sources/MyMod/XX.php
and
Themes/themeName/MyMod/xxx.template.php

It will just help me in placing the files where I need them to manipulate, add expand upon.

[Arantor]

The first one is fine. <require-dir> with MyMod would be fine and so would remove-dir on Sources/MyMod.

The problem is with the themes folder. How are you intending to load them? (I don't remember if loadTemplate deals with folders or not, I've never seen a mod that does that, either)

[ptmuldoon]

Just want to report back that loadTemplate does appear to support loading a template from a subdirectory.  Thus, this is loading the template, although I haven't done to much experimenting yet.

Code Select Expand


// Load the General Template for this action.
loadTemplate('MyModTemplates/Sample');


[live627]

Just want to report back that loadTemplate does appear to support loading a template from a subdirectory.  Thus, this is loading the template, although I haven't done to much experimenting yet.

Code Select Expand


// Load the General Template for this action.
loadTemplate('MyModTemplates/Sample');


Correct, loadTemplate() does indeed load templates from sub folders. I vaguely remember seeing some kind of mod that does this (can't remember if it was ajax chat, aeva media, or my own mod )

[Arantor]

I assume that works equally well if you have a custom theme installed and/or a custom version of the template in a custom theme.

I'd never tried it before, so didn't know if it would work