Tutorial Creare Add-on per XenForo

[netkingZ]

Premessa: Mettetevi l'anima in pace questo Topic sarà lungo , quindi prendetevi 10 minuti per leggerlo , CAPIRLO e se vi va vi prendete anche un bel caffè.

Finite le belle notizie ... passiamo a quelle brutte.

Come si crea un Add-on per Xenforo?

1. Andate nel file config.php che si trova in library ed aprite il file con il vostro notepad ( o altri software).

root -->library --> config.php

2. alla fine del codice che leggete inserite questo codice:

$config['debug'] = true;

3. Salvate le modifiche ed andate nel Pannello Amministrativo del vostro sito. (Amministrazione)

Se notate adesso nei menù in alto dell'Amministrazione vi si è aperta la voce Sviluppo (Development)
Ecco da questo pannello possiamo creare gli Add-on.
___________________

Adesso vediamo quali sono le cose da fare per creare un Add-on vero e proprio:

[Lavoriamo sul vostro software di FTP , per esempio Cyberduck per Mac o FileZilla per Win]

1. Per prima cosa dobbiamo creare una cartella con il nome che vorremo dare al nostro Add-on nella cartella library ( in questo esempio la mia cartella si chiamerà: DynamicFooter )

root -->library --> DynamicFooter

N.B.: Ovvio che potete chiamarla come volete basta che sia un nome che rispecchi l'argomento del vostro Add-on.

2. All'interno della cartella DynamicFooter andremo a creare un file php che chiameremo nel mio esempio DyFoo.php ed inseriremo il seguente codice:

<?php
 
class DynamicFooter_DyFoo {
 
    public static function includeDyFoo($hookName, &$contents, array $hookParams, XenForo_template_Abstract $template) {
 
        if($hookName == 'ad_below_bottom_breadcrumb') {
 
            ob_start();
 
            ?>
            <div class="forum_footer">
 
            <div class="forum_posts_leftside">
 
            <h3>latest tux reports network resources</h3>
 
            <?php
 
 
 
            /* Script to pull the latest updated resources from the XF Resource Manager */
 
            /** @var $resModel  XenResource_Model_Resource */
            $resModel = XenForo_Model::create('XenResource_Model_Resource');
            $fetchOptions = array('limit' => 5, 'order' => 'resource_date', 'direction' => 'desc');
 
            $rmupdates = $resModel->getResources(array(), $fetchOptions);
 
            foreach ($rmupdates AS $rmupdate) {
                echo ("<div class='entry-meta'><a href='http://community.tuxreportsnetwork.com/" . XenForo_Link::buildPublicLink('resources', $rmupdate) . "' >" . XenForo_Helper_String::wholeWordTrim($rmupdate['title'], 55) . "</a> <br /></div>"); // Echo the title with a link.
            }
 
 
 
            ?>
 
                    </div><!-- Close forum_posts_leftside -->
 
                    <div class="forum_posts">
 
                        <h3>latest posts from our community</h3>
 
                        <?php
 
                        /* Script to pull the latest posts from the XF Forum */
 
                        $db = XenForo_Application::getDb();
 
                        if ( !$db ) {
 
                            die( 'This script did not connect to the database' . mysql_error() );
                        }
 
                        $thread_qry = "
                                    SELECT * FROM `xf_thread`
                                    ORDER BY `last_post_date` DESC
                                    LIMIT 5
                                    ";
 
                        $threads = XenForo_Application::get('db')->fetchAll($thread_qry);
 
                        foreach (    $threads AS $thread ) {
 
                            echo ("<div class='entry-meta'><a href='http://community.tuxreportsnetwork.com/" . XenForo_Link::buildPublicLink('threads', $thread) . "' >" . XenForo_Helper_String::wholeWordTrim($thread['title'], 48) . "</a> <span style='float:right; margin-right:60px'>Viewed: " . $thread['view_count']
                                    . "</span><br /></div>"); // Echo the title with a link.
 
                        }
 
                        ?>
 
                    </div><!-- Close forum_posts -->
 
                </div><!-- Forum Footer -->
<?php
                $contents .= ob_get_contents();
                ob_end_clean();
            }
 
    }
 
}
?>

3. Salvate il file appena creato.

 

[netkingZ]

Analizziamo il codice appena scritto:

1.

class DynamicFooter_DyFoo {

Si comprendo come la classe segua il percorso del file , infatti come per il percorso che portava il file la sequenza è DynamicFooter --> DyFoo.php , cosi anche per la Classe il percorso deve essere identico con il cambiamento che sparisce il simbolo freccetta [-->] che viene sostituito dal simbolo underscore [_] e sparisce l'estensione del file [.php], quindi regole fondamentali sono:

a) Che il nome della Classe sia IDENTICO al percorso del File.​

b) Prima sempre il nome della/e cartella/e per ultimo quello del File. (Infatti il file può stare in quanto sotto-cartelle volete , basta che il percorso della Classe le riporti tutte in sequenza)​

c) Non devono esservi spazi (scrivere Dy Foo <-- NON viene letto da XenForo)​

d) La sequenza del percorso nella classe si scrive sempre con [_] per separare una cartella dall'altra o la cartella che contiene il file dal file stesso​

(scrivere DynamicFooter DyFoo <-- sbagliato , scrivere DynamicFooter-DyFoo <-- sbagliato , scrivere DynamicFooter_DyFoo <-- Giusto!!)​

N.B.: Ammettiamo che il file si trovi in sotto-cartelle? la dicitura giusta per esempio sarebbe :​

DynamicFooter_FooterFolder_DyFoo​

​

Il Nome della Classe (DynamicFooter_DyFoo) è da ricordarselo , ci servirà in futuro per la creazione dell'Add-on , segnatevelo da qualche parte ...

2.

public static function includeDyFoo

Questa è la funzione che verrà richiamata dalla "funzione CallBack" di Xenforo.
(Per informazioni leggere approfondimento generale qui : http://www.xfitalia.it/community/threads/guida-funzione-callback.845/ )

Come abbiamo fatto per la Classe anche la Funzione ha un nome che nel mio caso è includeDyFoo
ed è importante che gli assegnate voi un nome perche anche questa parte del codice ci servirà per la "funzione CallBack" di XenForo.
N.B.: L'unica regola che vi consiglio di seguire è che il nome deve essere unico quindi evitate di scrivere include_DyFoo o altro ma scrivete tutto attaccato.

3.

($hookName, &$contents, array $hookParams, XenForo_template_Abstract $template) {

Questa parte del codice sono gli argomenti che dovremo sviluppare , analizziamoli brevemente:

$hookName = è l'elemento chiave di questa funzione in quanto come dice il nome "hook" = gancio , serve per agganciare lo script all'interno di Xenforo.​

$contents = è la variabile che fa da "contenitore/punto di riferimento per lo script" ( la capiremo meglio dopo).​

$hookParams = se si volesse passare dei Parametri associati al gancio , ma non sarà questo il caso.​

$template = se uno volesse può personalizzare il template richiamando una parte del template da lui creata.​

​

4.

if($hookName == 'ad_below_bottom_breadcrumb') {

Questa parte del codice sta dicendo :"Se $hookName coincide con ad_below_bottom_bredcrumb" ,
quindi quando sfogliando i template di XenForo dal lato Admin di solito trovate scritto
<xen:hook name="ad_below_bottom_breadcrumb"> adesso sapete che il nome che inserirete in questa dicitura sarà il gancio , il cardine di collegamento fra questo script ed il template dove inserirete questo script.
[poi dopo vedremo meglio anche questo aspetto fondamentale]

5.

ob_start();

?>
<div class="forum_footer">

<div class="forum_posts_leftside">

<h3>latest tux reports network resources</h3>

L' ob_start() non fa altro che aprire la "sessione" dello script , mentre gli altri sono rispettivamente 2 div ( con classi di css annesse che si trovano gia su XenForo) ed un semplice "titolo di terzo livello".

6.

<?php



/* Script to pull the latest updated resources from the XenForo Resource Manager */

/** @var $resModel XenResource_Model_Resource */
$resModel = XenForo_Model::create('XenResource_Model_Resource');
$fetchOptions = array('limit' => 5, 'order' => 'resource_date', 'direction' => 'desc');

$rmupdates = $resModel->getResources(array(), $fetchOptions);

foreach ($rmupdates AS $rmupdate) {
echo ("<div class='entry-meta'><a href='http://community.tuxreportsnetwork.com/" . XenForo_Link::buildPublicLink('resources', $rmupdate) . "' >" . XenForo_Helper_String::wholeWordTrim($rmupdate['title'], 55) . "</a> <br /></div>"); // Echo the title with a link.
}



?>

Questa parte del codice altro non fa che andare a richiamare alcuni dati da un sito esterno ma la sintassi usata è molto simile a quella che vedremo a breve quindi non mi dilungo più di tanto.


I Div che seguono li salto a piè pari perche sono intuibili e facili anche per chi è alle prime armi di HTML semplice e passo invece ad analizzare il seguente codice che è molto più interessante:

7.

<?php /* Script to pull the latest posts from the XenForo Forum */

$db = XenForo_Application::getDb();

if ( !$db ) { die( 'This script did not connect to the database' . mysql_error() );
}
$thread_qry = " SELECT * FROM `xf_thread` ORDER BY `last_post_date` DESC LIMIT 5 ";
$threads = XenForo_Application::get('db')->fetchAll($thread_qry);
foreach ( $threads AS $thread ) {

echo ("<div class='entry-meta'><a href='http://community.tuxreportsnetwork.com/" . XenForo_Link::buildPublicLink('threads', $thread) . "' >" . XenForo_Helper_String::wholeWordTrim($thread['title'], 48) . "</a> <span style='float:right; margin-right:60px'>Viewed: " . $thread['view_count'] . "</span><br /></div>"); // Echo the title with a link. } ?>

la dicitura

$db = XenForo_Application::getDb();

altro non fa che connettervi al database , è l'equivalente di include('config.php'); , solo che se iscrivete include lui non lo sa interpretare , quindi si usa questa dicitura qui sopra riportata.

if ( !$db ) { die( 'This script did not connect to the database' . mysql_error() );
}

Dice solo :"Se il Database non è connesso , allora scrivi questo messaggio e segnala l'errore".

$thread_qry = " SELECT * FROM `xf_thread` ORDER BY `last_post_date` DESC LIMIT 5 ";

Questa invece è la "dicitura" della query che vogliamo creare ed è uguale a quella che si scriverebbe in un normale sistema di php-mysql

$threads = XenForo_Application::get('db')->fetchAll($thread_qry);

Mentre questa parte di codice equivale a scrivere:
mysql_query($thread_qry) incorporando $query = mysql_fetch_array($result), l'unione dei due codici da vita alla forma sopra indicata.

foreach ( $threads AS $thread ) {

Questo altro non è che l'equivalente di scrivere :

while($row = mysql_fetch_array($result)){

.....

}



Quindi basta dirgli che $threads è $thread dove $thread è come se fosse $row , quindi se noi dovessimo prendere i dati tramite il while faremo :

while($row = mysql_fetch_array($result)){

$casa = $row['edificio'];

$strada = $row['via'];

// e se dovessimo inserirli in una variabile dovremmo scrivere :



$citta = "<label> che bella".$strada." e che bella".casa." che avete.</label>";

}



la stessa cosa viene fatta con il codice sopra postato solamente che dovremmo scrivere cosi:

foreach ( $threads AS $row) {



echo ('<label> che bella'.$row["via"].' e che bella'.$row["edificio"].' che avete.</label>');



e cosi è stato fatto con il codice che segue :

echo ("<div class='entry-meta'><a href='http://community.tuxreportsnetwork.com/" . XenForo_Link::buildPublicLink('threads', $thread) . "' >" . XenForo_Helper_String::wholeWordTrim($thread['title'], 48) . "</a> <span style='float:right; margin-right:60px'>Viewed: " . $thread['view_count'] . "</span><br /></div>"); // Echo the title with a link. } ?>

Ci rimane l'ultima parte del codice che è questa:

<?php $contents .= ob_get_contents(); ob_end_clean(); } } } ?>

Che altro non fa che dire :

$contents .= ob_get_contents () ; = serve per analizzare e racchiudere il codice ed eseguirlo trasformandolo in HTML ( il punto [.] come per il php normale crea la sequenzialità del prodotto del while.

ob_end_clean(); = Chiude il tutto e termina l'esecuzione del codice ripulendolo al meglio.



Termina l'analisi del codice potete incominciare a prepararvi il secondo caffè ...

_______________________

 

[netkingZ]

Finita la pausa caffè ri-iniziamo con la spiegazione ....

1.Andiamo sull' Amministrazione e clicchiamo sulla voce Sviluppo.
2. Nel menu di sinistra ci sarà una voce che recita "Crea Add-on" cliccate e nella finestra che vi appare riempite questi campi come segue ( io li riempirò tenendo conto sempre dell'esempio fin qui portato avanti ):

IDAddon: DynamicFooterAddon ( un nome qualsiasi )
Titolo : DynamicFooterAddon ( un nome qualsiasi , è bene che sia uguale all'IDAddon)
L'Add-on è attivo [SI]
Stringa Versione : 1.0.0 ( se è la prima versione che fate , poi di volta in volta che ne fate uscire di nuove l'aggiornate)
ID Versione : 10200 ( questa è la versione di compatibilità con il tipo di Xenforo, sarebbe bene che se la versione ultima di XenForo è la 1.2.0 anche l'Add-on contenga il numero 10200 come compatibilità fra l'Add-on e Xenforo.)
URL: (nel caso vogliate mettercelo per pubblicizzare il vostro Add-on )

Codice di Installazione & Codice di Disinstallazione:
Per questi due devo fare un discorso a parte in quanto sarebbe bene che il vostro Add-on prevedesse un sistema di installazione , quindi se il sistema deve creare delle tabelle su Database è bene che si crei un codice che faccia cio , quindi nel caso l'aveste creato dovreste seguire l'esempio qui sotto:

Codice di Installazione :
Classe ( inseriremo per esempio DynamicFooterInstall)
Metodo o Funzione (inseriremo per esempio DyFooInstall)

Codice di Disinstallazione :
Classe ( inseriremo per esempio DynamicFooterUninstall)
Metodo o Funzione (inseriremo per esempio DyFooUninstall)

3. Salvate e il "Contenitore Add-on" l'avete creato , adesso non vi rimane che imparentare il Codice all'Add-on ed il Template all'Add-on , vediamo come fare:

_________________

Imparentare Add-on con Script DyFoo.php

1. Sempre dal Pannello Sviluppo trovate la voce "Listener Codice Eventi" ( dal menu di Sinistra) cliccandoci sopra vi verrà chiesto:

Ascolta l'Evento: Dovrete scegliere =>Template_hook
Perche? Perche è la Funzione contenuta dalla Classe che abbiamo creato con lo Script, se notate nella Descrizione sotto al menu a tendina dopo aver scelto Template_hook noterete che vi spiegano esattamente le stesse voci che vi ho spiegato io ($hookName, $contents, ect.).

Suggerimento Evento : [opzionale]
Esegui CallBack:
Classe (inseriremo DynamicFooter_DyFoo)
Metodo o Funzione (inseriremo includeDyFoo)
N.B.: Non è un caso che siano gli stessi della Classe e della Funzione del file DyFoo.php ... (logico Watson ... )

Ordine Esecuzione Callback: [potete lasciare 10]
Attiva Esecuzione Callback: [SI]
Descrizione: (inserite un il nome dell''Add-on per esempio , ma potete decidere voi cosa mettere ai fini dell'Add-on non è necessaria)

Add-on: Scegliete ovviamente DynamicFooterAddon ( insomma l'Add-on che avete creato qualche passaggio qui sopra)

2. Salvate.

Se avete fatto tutto Ok non vi devono uscire messaggi di errore.

L'ultimo sforzo che siamo in dirittura ... e giu con il terzo caffè ( e si spera ultimo)

_____________

Imparentare Add-on con il Template Personale

Allora va fatta una premessa , il codice fin qui scritto nello Script funziona anche senza in quanto si aggangia tramite il gancio 'ad_below_bottom_breadcrumb'
che si trova nel Footer gia di base di XenForo ma facciamo caso che non esista e che noi vogliamo crearne uno personale, vi spiego come fare:

1. Cliccate su Aspetto e poi sulla voce Stili.
2. Una volta aperta la pagina degli stili andate su Stile Master , e poi cliccate sulla destra sul nome Template ( dello stile Master ovvio ).
3. Nella nuova schermata cliccate sul pulsante in alto a destra denominato : Crea Nuovo Template.
4. nella nuova schermata date un titolo al vostro Template ( è una porzione di un template non un template intero intendiamoci) , nel "body" centrale inserite un po di codice e poi in basso dove vi viene chiesto l'Add-on scegliete il vostro Add-on.

Vi faccio vedere l'esempio basandoci sul mio di esempio (scusate il gioco di parole):

Titolo Template : Footer_DynamicFooter
"Body":

<div style="background-color: #EDEDED ; height: 200px ; width:900px">

<xen:hook name="ad_below_bottom_breadcrumb">
{$contents}
</xen:hook>
</div>


Add-on: DynamicFooterAddon

vi spiego la parte del "Body":
con la dicitura <xen:hook name="ad_below_bottom_breadcrumb"> sto dicendo allo script che prenda come aggangio , come riferimento questo nome e che quindi non vada a finire altrove e che venga visualizzato solo qui.
mentre con la dicitura {$contents} richiamo al variabile $contents che era nello Script e gli sto dicendo che il contenuto dello Script deve essere visualizzato li.
con </xen:hook> chiudo semplicemente il comando iniziato prima.

cosi facendo , scegliendo in basso l'Add-on avete associato a quell'Add-on anche il template da voi creato.

Se volessi inserirlo nelle pagine del Forum?

N.B.: Ripeto di base lo Script funziona anche senza questa parte del Template che ho appena spirgato , quindi prendete questa parte e quella del Template Personale come un qualcosa in più.

Basta semplicemente andare nel Template dove vogliamo fare apparire il nostro Add-on e inserire la seguente dicitura:

<xen:include template="Footer_DynamicFooter" />

E se volessi Esportare il mio Add-on ?

1. Andate nel Menu Sviluppo , Cliccate su Lista Add-on , Cliccate sul vostro Add-on.
2. Nella nuova schermata in alto a destra trovate il pulsante Esporta.

il sistema creerà un file .XML dove all'interno ci sono le istruzioni per creare , semplicemnte importandolo su di un nuovo XenForo il vostro Add-on. Nelle istruzzioni sono compresi:
- l'Add-on inteso come "Contenitore di dati"
- il file Listener creato ( ricordate? Imparentare Add-on con Script DyFoo.php )
-ed il template Personale che avete creato .
tutto questo una volta installato il vostro Add-on verrà rimportato ,

Mentre per la cartella DynamicFooter in library ed il File contenuto nella cartella (DyFoo.php ) dovrete creare una cartella Upload contenente questa cartella. Quindi in un ipotetica "cartella per i clienti" , inserite :
- il file .XML
- La cartella Upload che contiene la cartella Library ( creata da voi come esempio dei passaggi ) , che contiene la cartella DynamicFooter.


Consigli Utili: Fate delle prove prima di pubblicizzare il vostro Add-on. Adesso dopo molta pazienza e 3 caffè ( forse 4 ) avete la possibilità di creare un vostro Add-on , se avete avito la pazienza di leggere e CAPIRE tutto ... a voi la prossima mossa.

Questa non è la soluzione definitiva a tutti i vostri problemi di Add-on , ma è un buon inizio , capire questo vi fa fare un passo avanti.

Se avete seguito per filo e per segno il risultato finale deve essere questo :

P.S.: Questo non è un Tutorial per arrivare a fare questo specifico Add-on ma ho preso questo Add-on perche mi sembra facile da capire, l'importante a fine di questa lunga e noiosa lettura è aver compreso come si fanno gli Add-on e provare a farne uno ,anche stupido e piccolino , per iniziare e provare a migliorarsi.

Bella.
netkingZ

 

[Il Custode]

wow Sono impressionato dal contributo
Grazie a nome di tutti gli utenti di xfitalia

 

[netkingZ]

 

[Spawn]

Salve. ottima guida...ma per creare o modificare Add-on in XF2 la procedura cambia molto? Io per esempio ho modificato advanced search per plasmarlo in base alle mie esigenze ma con la versione di XF2 non ho capito come fargliela digerire al sistema. Se la sostituisco alla precedente non mi appare il bottone Aggiornamento ma in cp Admin mi appare un errore ...mostrato in foto. Il motore di ricerca modificato è una scheggia mi funziona benissimo (in locale)ma mi rode che il sistema non lo digerisce bene. Come si fa a dire al sistema che questa modifica è un aggiornamento di quella istallata?

 

[Kintaro]

@Spawn ho idea che riceverai più notizie sul xf.com nella sezione di sviluppo.
XF2 cambia molto lato sviluppo da XF1