SoldatoLego, nella
sezione italiana del forum di SMF ha chiesto se esistevano info su come realizzare mod in italiano. Non essendo al corrente della risposta ho iniziato a scrivere un po' di quello che so (o credo di sapere
), al momento ho coperto il file
package-info.xml che è quel file che "istruisce" il package manager di SMF su come installare e disinstallare un mod.
Ho pensato potesse essere utile riportare quelle informazioni anche qui.
Prerequisiti per creare un mod: un minimo di conoscenza di html, xml, php, mysql (in teoria questo potrebbe non essere vero, ma diciamo che fa bene) e css.
In ogni mod, i passi che SMF deve fare per installarlo sono descritti nel file
package-info.xml. Si tratta di un file xml che contiene tutte le informazioni riguardo alle modifiche, al codice che devono essere eseguite ed ai file che devono essere inseriti durante l'installazione o rimossi durante la disinstallazione.
Un esempio:
<?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>emanuele:DemoPack</id>
<name>Package dimstrativo</name>
<version>1.0</version>
<type>modification</type>
<install for="1.1.*">
<readme parsebbc="true">readme.txt</readme>
<code>install.php</code>
<modification type="file">install.xml</modification>
<require-file name="demomod_admin.php" destination="$sourcedir" />
<require-dir name="demomod" destination="$boarddir" />
<require-file name="demomod_admin.template.php" destination="$themedir" />
</install>
<uninstall for="1.1.*">
<code>uninstall.php</code>
<modification reverse="true">install.xml</modification>
<remove-file name="$sourcedir/demomod_admin.php" />
<remove-dir name="$boarddir/demomod" />
<remove-file name="$themedir/demomod_admin.template.php" />
</uninstall>
</package-info>
Analizziamolo pezzo a pezzo.
La prima parte è quella che descrive il mod:
<?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>emanuele:DemoPack</id>
<name>Package dimstrativo</name>
<version>1.0</version>
<type>modification</type>
le prime tre righe sono generiche e sempre uguali.
Poi ci sono i seguenti tag:
- id: contiene un identificativo "unico", le indicazioni dicono che dovrebbe essere composto dal nome (o nick) dell'autore e il nome del mod separati da un ":".
- name: contiene il nome del mod
- version: contiene la versione del mod
- type: onestamente l'ho sempre lasciato così...posso immaginare che serva per distinguere i mod dai temi...credo.
Nella seconda parte ci sono le istruzioni vere e proprie per l'installazione:
<install for="1.1.*">
<readme parsebbc="true">readme.txt</readme>
<code>install.php</code>
<modification type="file">install.xml</modification>
<require-file name="demomod_admin.php" destination="$sourcedir" />
<require-file name="demomod_admin.template.php" destination="$themedir" />
<require-dir name="demomod" destination="$boarddir" />
<redirect url="$scripturl?action=admindemo" timeout="5000">endinstall.html</redirect>
</install>
La prima riga definisce per quale versione di SMF vale l'installazione seguente, in questo caso avendo indicato
for="1.1.*" gli dico che le istruzioni valgono per tutte le versioni di SMF 1.1, dalla 1.1.1 alla 1.1.11 (attualmente l'ultima). Questa soluzione ti permette di creare più blocchi con le istruzioni per installare su più versioni, ad esempio potresti fare:
<install for="1.1.*">
[...]
</install>
<install for="2.0 RC3">
[...]
</install>
cosi sarà possibile mettere nel primo blocco le istruzioni per l'installazione su SMF 1.1.x e nel secondo le istruzioni per l'installazione su SMF 2.0 RC3, ecc.
Nelle righe successive ci sono i tag:
- readme: contiene il nome di un file in cui puoi inserire informazioni riguardo il tuo mod. Il parsebbc="true" indica che se quel file conterrà dei tag bbc questi verranno interpretati come se si trattasse di un normale post.
- code: contiene il nome di un file php. Questo file php conterrà delle istruzioni, ovviamente in php, da eseguire durante l'installazione (solitamente viene utilizzato se il mod richiede modifiche al database).
- modification: contiene il nome di un file xml che a sua volta conterrà le istruzioni su come modificare i file di SMF veri e propri (oggetto di un prossimo post).
- require-file: nome (ed eventuale percorso) di un file da copiare da qualche parte nella struttura delle cartelle di SMF. Nell'esempio sopra, il file demomod_admin.php verrà copiato nella cartella "Sources". Oppure il file demomod_admin.template.php verrà copiato nella cartella del tema di default: "Themes/default".
- require-dir: simile al precedente, solo riferito ad una cartella. Nell'esempio verrà creata una cartella demomod nella radice del forum (ad esempio www.miosito.it/forum/).
- redirect: formato da 2 parti:
- endinstall.html: è un file che viene mostrato alla fine dell'installazione
- url e timeout: sono rispettivamente un percorso a cui si verrà reindirizzati alla fine dell'installazione dopo un certo periodo di tempo definito in millisecondi nel parametro timeout.
Di tutti questi l'unico veramente indispensabile è il tag
modification. Tutti gli altri sono opzionali e non è necessario che vi siano affinché il mod funzioni correttamente (ovviamente dipende da cosa il mod deve fare).
Infine l'ultimo blocco definisce le operazioni per la disinstallazione:
<uninstall for="1.1.*">
<code>uninstall.php</code>
<modification reverse="true">install.xml</modification>
<remove-file name="$sourcedir/demomod_admin.php" />
<remove-dir name="$boarddir/demomod" />
<remove-file name="$themedir/demomod_admin.template.php" />
</uninstall>
La struttura è molto simile al blocco d'installazione, cambiano i nomi e la struttura di alcuni tag (in particolare quelli per rimuovere i file e le cartelle, che diventano "remove-file/dir" e in cui appare l'attributo (? non son sicuro della terminologia xml...)
name in cui verrà indicato il percorso ed il nome del file da rimuovere). Da notare che al tag
modification è stato aggiunto
reverse="true" che indica al package manager di SMF che per effettuare la disinstallazione dovrà fare l'esatto contrario di quanto è indicato nel file xml (che per inciso è lo stesso indicato nel blocco "install"). Similmente all'install, nella prima riga si può specificare la versione di SMF per cui la disinstallazione è pensata e similmente all'install è possibile creare più blocchi per definire diverse procedure di disinstallazione per differenti versioni di SMF.
E per il file package-info.xml mi pare sia tutto.
Per quanto ne so, quanto ho appena scritto permette di creare mod compatibili con tutte le versioni di SMF dalla 1.1 in poi. Per la 1.0 non saprei, ma credo interessi relativamente poco.
Domande, errori, ecc., dite la vostra.
