Traduzione documentazione

[SoldatoLego]

Ciao a tutti, magari faccio una domanda stupida, ma dato la mia difficoltà con la lingua inglese non è che qualcuno sa indicarmi dove posso reperire il manuale per creare MOD?

ho provato a leggere il manuale online ed esattamente la sezione: Modifications and Understanding SMF's source
ma ho capito ben poco (quasi nulla)

avrei una mezza idea di fare una modifica...avrei anche un punto di partenza...ma mi mancano le nozioni base

[emanuele]

Io preferisco l'approccio "learn by doing" (cioè "impara facendo"), quindi ho preso altri mod ed ho guardato come loro facevano cose simili a quelle che volevo fare io.

Quel documento l'avevo letto ai tempi, ma non ricordo mi abbia fornito grande aiuto...

[SoldatoLego]

Io preferisco l'approccio "learn by doing" (cioè "impara facendo"), quindi ho preso altri mod ed ho guardato come loro facevano cose simili a quelle che volevo fare io.

Quel documento l'avevo letto ai tempi, ma non ricordo mi abbia fornito grande aiuto...

Emanuele ma sai che sei sempre tu il primo a rispondermi  ... ovviamente son contento di ciò!! 

ad ogni modo fino ad adesso sono andato di "impara facendo" ma come dicevo sopra probabilmente mi mancano le basi...forse dovrei iniziare con un corso di php, uno di css e riprendere gli appunti di sql ...ma con un pò di testa riesco pian piano a modificare i file esistenti "brutalmente" (modifica il file a mano) e magari anche a metter su quello che voglio dalla mia mod....ma poi non sarei in grado più di toglierla

Da quello che ho capito una mod parte dall'installazione -> apre un file X che gli dica cosa fare (creare/editare files) e dove farlo -> funzionare correttamente (con diversi temi e con diversi supporti linguistici)

però in una mod esiste anche la possibilità di tornare nei propri passi e disinstallare la mod...ecco xkè pensavo che tale manuale mi potesse dare lo "sprint" iniziale ...tu che ne pensi?

[emanuele]

Emanuele ma sai che sei sempre tu il primo a rispondermi  ... ovviamente son contento di ciò!! 

eheheheh
In questi giorni è veramente un caso...

Tra l'altro adesso che ricordo, il documento che hai letto è anche abbastanza vecchio dato che credo si riferisca ancora ad SMF 1.0...

Vediamo un po' se riesco a mettere giù quattro idee...

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 installarla sono descritti nel file package-info.xml. Si tratta di un file xml che contiene tutte le informazioni riguardo alle modifiche, al codice che deve essere eseguito ed ai file che devono essere inseriti durante l'installazione o rimossi durante la disinstallazione.
Un esempio:

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>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:

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>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 deve essere composto dal nome 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:
  

Code Select Expand


<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:

Code Select Expand


<install for="1.1.*">
[...]
</install>
<install for="2.0 RC3">
[...]
</install>

cosi potrai mettere nel primo blocco le istruzioni per l'installazione su SMF 1.1.x, mentre 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.
  
• 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.
  
• 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:

Code Select Expand


<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").

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.

Domani sera se interessa (e se riesco), posso descrivere brevemente la struttura del file "install.xml".

[SoldatoLego]

non ho parole...più chiaro di così non si poteva!come sempre del resto

Sai spero tu sia un docente in qualche scuola?? ci vorrebbero docenti così chiari e preparati [anche solo per i corsi di formazione]



per le conoscenze iniziali diciamo che ho scarse basi, ma il codice mi sembra di facile lettura e spero di non avere grossi problemi
grazie ancora e qualsiasi informazione che vorrai darmi ancora sarà sicuramente di mio gradimento

[emanuele]

non ho parole...più chiaro di così non si poteva!come sempre del resto

Sai spero tu sia un docente in qualche scuola?? ci vorrebbero docenti così chiari e preparati [anche solo per i corsi di formazione]

Sia mai, meglio non sfidare la sorte: già mi è andata bene con quanto ho scritto sopra...
Sono assolutamente negato per spiegare.

per le conoscenze iniziali diciamo che ho scarse basi, ma il codice mi sembra di facile lettura e spero di non avere grossi problemi
grazie ancora e qualsiasi informazione che vorrai darmi ancora sarà sicuramente di mio gradimento

Sì, il codice è abbastanza facile da seguire. Poi ovviamente tutto può essere complicato a piacere!
Come promemoria: tra SMF 1.1.x e 2 ci sono grosse differenze per chi crea mod, sia a livello del tema, sia a livello delle interazioni con il database.

Ovviamente disponibile a rispondere laddove conosco la risposta!

[Giochi]

Sia mai, meglio non sfidare la sorte: già mi è andata bene con quanto ho scritto sopra...
Sono assolutamente negato per spiegare.