Caricamento...
Mostra Eventi

[italiano] Guida per sviluppare estensioni

Guide su phpBB 3.1, per eseguire operazioni al proprio forum, senza rischi e correttamente.
Avatar utente
brunino
Site Admin
Messaggi: 665
Iscritto il: dom nov 02, 2014 7:21 pm
Has thanked: 2 times
Been thanked: 57 times

[italiano] Guida per sviluppare estensioni

Messaggio da leggereda brunino » lun nov 24, 2014 4:41 pm

Menù


LE BASI
La prima cosa da fare prima di iniziare lo sviluppo di un'estensione é scegliere i nomi delle directory che la ospiteranno. esempio ext/staffit/toptentopics (ossia ext/nome_autore/nome_estensione)
All'interno di quella cartella vanno tutti i file dell'estensione.
Il primo file da creare obbligatoriamente é il composer.json: va creato nella directory della nostra estensione e va compilato come segue:

Codice: Seleziona tutto

 {
    "name": "staffit/toptentopics",
    "type": "phpbb-extension",
    "description": "Aggiunge un box nell'indice con ultimi topic, topic più visti e ultimi post",
    "homepage": "https://brunino.altervista.org",
    "version": "0.1.0-a1",
    "time": "2014-11-10",
    "license": "GPL-2.0",
    "authors": [
        {
            "name": "brunino",
            "email": "[email protected]",
            "homepage": "http://www.brunino.altervista.org",
            "role": "Developer"
        },
 {
            "name": "Carlo",
            "email": "[email protected]",
            "homepage": "http://www.phpbbitalia.net",
            "role": "Helper"
        },
        {
            "name": "Micogian",
            "email": "[email protected]",
            "homepage": "http://www.actafungorum.org/actaforum/",
            "role": "Previous Developer"
        }
    ],
    "require": {
        "php": ">=5.3"
    },
    "extra": {
        "display-name": "Top Ten Topics",
        "soft-require": {
             "phpbb/phpbb": "3.1.*@dev"
        },
        "version-check": {
            "host": "brunino.altervista.org",
            "directory": "/version/",
            "filename": "toptentopics.json"
        }
    }
}


Come vedete nella parte finale viene richiamato un file situato nel mio sito che serve al gestore estensioni nel PCA per dirti (quando hai installato un'estensione) a quale versione attuale si trova l'estensione e se quella che hai tu é aggiornata. É necessario creare un file nel vostro server con estensione .json che dovete richiamare (vedi sopra come) nel composer.json e lo scrivete con la seguente sintassi:

Codice: Seleziona tutto

 {
    "stable": {
        "1.0": {
            "current": "1.0.0",
            "announcement": "https://www.phpbb.com/community/viewtopic.php#",
            "download": "https://www.phpbb.com/123",
            "eol": null,
            "security": false
        }
    },
    "unstable": {
        "1.0": {
            "current": "1.0.1",
            "announcement": "http://acme.foobar.com/version_1.0.1",
            "eol": null,
            "security": false
        },
        "1.1": {
            "current": "1.1.0-b4",
            "announcement": "http://acme.foobar.com/version_1.1.0",
            "eol": null,
            "security": false
        }
    }
}


A questo punto inizia lo sviluppo vero e proprio dell'estensione.

MODIFICHE AI TEMPLATE
Con le estensioni non si può più andare a pescare un punto dei template e aggiungere/rimuovere/cambiare una parte del codice bensì bisogna usare gli eventi proposti da phpbb e di cui trovate l'elenco completo qui: https://wiki.phpbb.com/Event_List#Template_Events
[se non trovate un evento che vi serve dovete richiederlo e sperare che lo inseriscano nella prossima versione phpbb] oppure andate direttamente nei template, cercate il punto in cui volete aggiungere il codice e guardate se lì nei dintorni c'é un evento.
Nei template gli eventi si riconoscono perché sono semplicemente <!-- EVENT nome_evento --> quindi se nei template trovate questo pezzo di codice quello é un evento che potete usare nelle estensioni.

Gli eventi template possono essere usati solo per aggiungere codice html ai template.
Per eseguire un evento è sufficiente creare un file con nome directory_tua_estensione/styles/all/template/event/nome_evento.html e all'interno mettere il codice html da aggiungere.
Da notare nel nome della cartella la scritta all per quanto riguarda gli stili. Mettendo all quell'evento sarà applicato a tutti gli stili mettendo solo il nome di uno stile (esempio styles/prosilver/template...) limiterete quell'aggiunta al solo stile specificato.
Per aggiungere un file css o un file js basta inserire in un evento (dell'overall_header se lo si vuole in tutte le pagine o in un evento di una pagina specifica):

Codice: Seleziona tutto

<!-- INCLUDECSS nome_file.css -->

Il file dovrà andare nella cartella styles/all/template

Codice: Seleziona tutto

<!-- INCLUDEJS nome_file.js -->

Il file dovrà andare nella cartella styles/all/template

MODIFICHE AL PHP
Le problematiche nascono se si vuol modificare php.
Anche in questo caso c'é una lista di eventi utilizzabili. Questa volta bisogna creare alcuni file in base a cosa si deve fare.
Un file necessario é il config/services.yml
Qui bisogna specificare le variabili che ci serviranno nel php (es $db per eseguire query sql; $template per passare dati da php a template).
Esempio di services.yml

Codice: Seleziona tutto

 services:
    staffit.toptentopics.listener:
        class: staffit\toptentopics\event\listener
        arguments:
            - @dbal.conn
            - @template
            - @auth
            - @user
            - %core.root_path%
            - %core.php_ext%
        tags:
            - { name: event.listener }

Gli eventi php li gestiamo nel file event/listener.php vediamo come:

Codice: Seleziona tutto

 <?php
namespace staffit\toptentopics\event;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
class listener implements
EventSubscriberInterface{
protected $db;
protected $template;
protected $auth;
protected $user;
protected $root_path;
protected $phpEx;

//costruttore
public function __construct(\phpbb\db\driver\driver_interface $db, \phpbb\template\template $template, \phpbb\auth\auth $auth, \phpbb\user $user, $root_path, $phpEx)
{
   $this->db = $db;
   $this->template = $template;
   $this->auth = $auth;
   $this->user = $user;
   $this->root_path = $root_path;
   $this->phpEx   = $phpEx ;
}

static public function getSubscribedEvents()   {      return array(         'core.nome_evento'                  => 'mia_funzione',               );   }   
public function mia_funzione($event)   {      
//codice da eseguire nell'evento
}
}

Nella prima parte definiamo le variabili che già abbiamo richiesto nel services così
protected $db;
poi dobbiamo creare il costruttore sempre per definire quelle variabili.
Tutte le variabili infatti in phpbb3.1 sono state trasformate da $db->sql_query a $this->db->sql_query e così anche per user e template ecc...
QUI c'é un elenco il più possibile completo delle variabili passabili dal service e utilizzabili nei php.
In seguito definiamo gli eventi che vogliamo usare e cosa far eseguire per ognuno di essi: definiamo l'evento e gli associamo una nuova funzione che poi andiamo a creare sotto. La funzione avrà come unico parametro $event nel quale verrà passato qualcosa in base all'evento (lo trovate scritto nella lista degli eventi) e che potrà essere modificato e rimandato indietro tramite return $event;

AGGIUNGERE PAGINA PERSONALIZZATA
Il primo file da creare é il service/routing.yml così:

Codice: Seleziona tutto

 staffit_banlist_controller:
    path: /banlist/
    defaults: { _controller: staffit.banlist.controller:funzione_pagina }

accanto a path appare il nome col quale la pagina sarà richiamata. Le pagine dalla 3.1 sono del tipo app.php/nome_pagina
nella parte defaults dove è scritto funzione_pagina, viene definita la funzione php che mostrerà la pagina.


poi serve creare un file /controller/

qui dovremo creare la funzione funzione_pagina

FILE DI LINGUA
Per rendere l'estensione utilizzabile anche dagli altri paesi (validabile da phpbb.com) bisogna inserire la possibilità di traduzione. Il file di lingua é uno solo ossia il language/en/common.php (sempre dentro la cartella dell'estensione)
al posto di en vanno le sigle delle lingue (en, it...) delle traduzioni.
Il file common va compilato così:

Codice: Seleziona tutto

 <?php
if (!defined('IN_PHPBB'))
{
exit;
}
if (empty($lang) || !is_array($lang))
{
$lang = array();
}
$lang = array_merge($lang, array(
'NOME_VARIABILE'         => 'Scritta che appare',   'BAN_LIST'         => 'Lista Ban',   'BAN_IN'         => 'Inizio Ban',   'BAN_OUT'         => 'Fine Ban',   'BAN_REASON'         => 'Motivo',    'PERMABAN'           => 'Ban Permanente',    'NO_REASON_BAN'      => 'Nessuna motivazione specificata',    'TOTALS_BAN'          => 'C&apos;&egrave; un utente bannato',    'TOTAL_BANS'          => 'Ci sono %s utenti bannati',));

Nei template tali variabili si richiamano scrivendo semplicemente {L_NOME_VARIABILE} che verrà tramutata nella scritta relativa alla lingua dell'utente che la legge.
Per far sì che il file di lingua venga interpretato bisogna aggiungere un evento al file che gestisce gli eventi php (event/listener.php solitamente). L'evento da aggiungere é user_setup e nella funzione relativa a questo evento inseriamo:

Codice: Seleziona tutto

 $lang_set_ext = $event['lang_set_ext'];      $lang_set_ext[] = array(         'ext_name' => 'staffit/banlist',         'lang_set' => 'common',
);
$event['lang_set_ext'] = $lang_set_ext;


N.B. nella traduzione della variabile TOTAL_BANS potete notare ad un certo punto %s: serve a inserire qualcosa senza spezzare in due la traduzione. Per inserire qualcosa dentro %s dovete mettere nel vostro php:

Codice: Seleziona tutto

.....


AGGIUNGERE PAGINA PERSONALIZZATA CON VARIABILE
É come creare una pagina personalizzata ma invece che app.php/nome_pagina per averla app.php/nome_pagina/variabile dove variabile é una variabile che avremo a disposizione in php.
Analogamente a prima creiamo il routing ma con qualche lieve differenza:

Codice: Seleziona tutto

 staffit_banlist_controller:
    pattern: /banlist/{variabile}
    defaults: { _controller: staffit.banlist.controller:nome_funzione }

come vedete definiamo con {variabile} la variabile.

Nella funzione php associata alla pagina, la prendiamo semplicemente così

MODIFICARE IL DATABASE
I file che verranno eseguiti quando l'estensione sarà abilitata sono collocati nella cartella /migrations e svolgono funzioni quali: aggiunta righe, colonne e tabelle al database, aggiunta moduli PCA, PCU....
Non importa il loro nome ee non vanno richiamati da nessuna parte: tutti i file in quella cartella saranno lanciati automaticamente al momento dell'installazione dell'estensione.
I vari utilizzi sono specificati direttamente qui sotto nelle varie parti interessate.

AGGIUNGERE MODULO PCA

Un modulo PCA é formato anch'esso da php e html.
I file php sono 2.
File acp/main_info.php

Codice: Seleziona tutto

 <?php
namespace acme\demo\acp;
class main_info{
function module()   {      
return array(         'filename'   => '\acme\demo\acp\main_module',         'title'      => 'ACP_DEMO_TITLE',         'version'   => '1.0.0',         'modes'      => array(            'settings'   => array('title' => 'ACP_DEMO', 'auth' => 'ext_acme/demo && acl_a_board', 'cat' => array('ACP_DEMO_TITLE')),         ),      );   }}

In cui inseriamo le informazioni del modulo, e il file
acp/main_module.php (il nome viene definito nel file main_info alla voce filename):

in questo scriviamo le cose che il modulo fa quando viene aperto (definiamo le variabili) e quando viene inviato il form (modifichiamo il database).


Per far sì che sia abilitato automaticamente bisogna aggiungere questa parte nel file della cartella migrations:


AGGIUNGERE BLOCCO A MODULO PCA
Analogamente alle modifiche dei template, c'é la lista degli eventi relativi ai moduli già esistenti del PCA.
Per eseguire un evento (ossia aggiungere codice html) é sufficiente creare un file adm/style/event/nome_evento.html con le stesse modalità degli eventi template.
Ci sono anche eventi php legati al PCA, si usano come eventi php normali.

PERMESSI
Aggiungere dei permessi è molto semplice: basta inserire queste semplici modifiche:

SELEZIONE FORUM PCA
Per inserire un nuovo campo nella Gestione di ogni Forum della Board e poter riusare tale opzione.

Bisogna utilizzare 3 eventi nel nostro file che contiene i vari eventi php.
Li definiamo (non serve cambiare nulla qui)

Codice: Seleziona tutto

  'core.acp_manage_forums_request_data' => 'acp_data', 'core.acp_manage_forums_initialise_data' => 'acp_init', 'core.acp_manage_forums_display_form' => 'acp_form',


E poi creiamo le relative funzioni.
NB: cambiare nomecampo con un nome che sia più adeguato

Codice: Seleziona tutto

//quando viene inviato
public function acp_data($event)
{
$array = $event['forum_data'];
      $array['forum_nomecampo'] = $this->request->variable('forum_nomecampo', 1);
$event['forum_data'] = $array;
}

//quando è un nuovo forum
public function acp_init($event)
{
if ($event['action'] == 'add')
      {
         $array = $event['forum_data'];
         $array['forum_nomecampo'] = 1; //valore predefinito 1 si o 0 no
         $event['forum_data'] = $array;
      }
}

//invio al template
public function acp_form($event)
{
$array = $event['template_data'];
      $array['NOMECAMPO'] = $event['forum_data']['forum_nomecampo'];
$event['template_data'] = $array;
}


Poi bisogna agire nel template PCA tramite un evento, e quindi creiamo il file
adm/style/event/acp_forums_normal_settings_append.html
E ci aggiungiamo l'input che vogliamo... Esempio:

Codice: Seleziona tutto

<dl>
   <dt><label for="forum_vft">{L_QUALCOSA}{L_COLON}</label><br /><span>{L_QUALCOSA_APPROFONDITO}</span></dt>
   <dd>
      <label>
<select class="select" name="forum_nomecampo">
<option value="0"<!-- IF NOMECAMPO eq 0 --> selected<!-- ENDIF -->>{L_NO}</option>
<option value="1"<!-- IF NOMECAMPO eq 1 --> selected<!-- ENDIF -->>{L_YES}</option>
</select>
</label>
   </dd>
</dl>

Se si vuole usare un input diverso dalla select, la value dovrà essere {NOMECAMPO}

Infine bisogna aggiungere nel database, un campo alla tabella e lo facciamo con un file migrations, chiamiamolo
forumselect.php
NB. al posto della x devi mettere il valore predefinito per tutti i forum preesistenti al momento dell'istallazione dell'estensione, 1 o 0
1 = abilitata
0 = disabilitata

Codice: Seleziona tutto

<?php
/**
*
* @package Nome Ext
* @copyright (c) 2015 brunino
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/
namespace bruninoit\nomeext\migrations;
class forumselect extends \phpbb\db\migration\migration
{
   static public function depends_on()
   {
      return array('\phpbb\db\migration\data\v310\gold');
   }

public function update_schema()
   {
      return array(
         'add_columns' => array(
            $this->table_prefix . 'forums' => array(
               'forum_nomecampo' => array('TINT:1', x),
            ),
         ),
      );
   }

   public function revert_schema()
   {
      return array(
         'drop_columns' => array(
            $this->table_prefix . 'forums' => array(
               'forum_nomecampo',
            ),
         ),
      );
   }
}


Qualsiasi domanda o correzione é ben accetta.


Avatar utente
frank
Messaggi: 46
Iscritto il: lun set 14, 2015 3:18 am
Been thanked: 1 time

Re: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda frank » mar set 15, 2015 2:06 am

brunino ha scritto:Source of the post "time": "2014-11-10",


Sto creando la mia prima estensione che va ad aggiungere una parte di evento a 3 file che sono:
template/viewforum_body.html
template/viewtopic_body.html
template/posting_layout.html


l'evento originale che c'è già in questi 3 file è

Codice: Seleziona tutto

<!-- IF S_FORUM_RULES -->

io con l'estensione devo farlo diventare così

Codice: Seleziona tutto

<!-- IF S_FORUM_RULES and (S_USER_NEW or not S_REGISTERED_USER) -->


Finora ho creato le cartelle e il json (che poi ti farò vedere), nei 3 file della cartella event ho inserito questo

Codice: Seleziona tutto

<p style="display:none;"><!-- IF S_FORUM_RULES --></p>
<!-- IF S_FORUM_RULES and (S_USER_NEW or not S_REGISTERED_USER) -->

Schermata 09-2457281 alle 04.41.05.png
Schermata 09-2457281 alle 04.41.05.png (23.51 KiB) Visto 155252 volte


L'estensione l'ho caricata, ho vuotato la cache, ma Il problema è che appare sempre così a tutti i gruppi, admin compreso.
Allegati
Schermata 09-2457281 alle 02.37.00.png
Schermata 09-2457281 alle 02.37.00.png (7.82 KiB) Visto 155254 volte


Avatar utente
brunino
Site Admin
Messaggi: 665
Iscritto il: dom nov 02, 2014 7:21 pm
Has thanked: 2 times
Been thanked: 57 times

R: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda brunino » mar set 15, 2015 1:13 pm

Mi sa che non hai capito bene il funzionamento degli eventi. Gli eventi sono dei punti specifici in alcuni file, su cui l'estensione puo' agire. Nel resto dei file, non puoi agire e quindi modificare. Devi vedere se nel punto che vuoi modificare c'e un evento... altrimenti non lo puoi fare, con un'estensione.


Avatar utente
frank
Messaggi: 46
Iscritto il: lun set 14, 2015 3:18 am
Been thanked: 1 time

Re: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda frank » mar set 15, 2015 6:56 pm

Questo è il codice completo originale che c'è in ognuno dei 3 file

Codice: Seleziona tutto

<!-- IF S_FORUM_RULES -->
   <div class="rules<!-- IF U_FORUM_RULES --> rules-link<!-- ENDIF -->">
      <div class="inner">
      
      <!-- IF U_FORUM_RULES -->
         <a href="{U_FORUM_RULES}">{L_FORUM_RULES}</a>
      <!-- ELSE -->
         <strong>{L_FORUM_RULES}</strong><br />
         {FORUM_RULES}
      <!-- ENDIF -->
      
      </div>
   </div>
<!-- ENDIF -->


Avatar utente
brunino
Site Admin
Messaggi: 665
Iscritto il: dom nov 02, 2014 7:21 pm
Has thanked: 2 times
Been thanked: 57 times

R: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda brunino » mar set 15, 2015 7:20 pm

Si, ma per intervenire devi usare gli eventi... li non ve ne sono...

Inviato dal mio GT-S5360 con Tapatalk 2


Avatar utente
brunino
Site Admin
Messaggi: 665
Iscritto il: dom nov 02, 2014 7:21 pm
Has thanked: 2 times
Been thanked: 57 times

Re: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda brunino » sab set 19, 2015 3:52 pm

Guida migliorata.


Avatar utente
frank
Messaggi: 46
Iscritto il: lun set 14, 2015 3:18 am
Been thanked: 1 time

Re: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda frank » dom set 20, 2015 1:02 am

Questa frase non è chiarissima, non ha un senso compiuto: "Per aggiungere un file css o un file js basta inserire in un evento (dell'overall_header se lo si vuole in tutte le pagine o in un evento di una pagina specifica):"
Poi le sez. "Aggiungere modulo PCA" e "Permessi", non sono complete.

Poi, volevo chiederti: se io volessi creare un'estensione che modifica solo i css, tipo PERSONAL.CSS che viene richiamato in stylesheet @import url("PERSONAL.css"); come si fa?


Avatar utente
brunino
Site Admin
Messaggi: 665
Iscritto il: dom nov 02, 2014 7:21 pm
Has thanked: 2 times
Been thanked: 57 times

R: Re: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda brunino » dom set 20, 2015 11:57 am

frank ha scritto:Questa frase non è chiarissima, non ha un senso compiuto: "Per aggiungere un file css o un file js basta inserire in un evento (dell'overall_header se lo si vuole in tutte le pagine o in un evento di una pagina specifica):"


Senso ce l'ha... devi inserire i codici sottostanti (nella guida) in un evento template o dell'overall_header o in uno di una specifica pagina.

frank ha scritto:Poi le sez. "Aggiungere modulo PCA" e "Permessi", non sono complete.


Eh lo so... quando posso le aggiungo

Inviato dal mio GT-S5360 con Tapatalk 2


Avatar utente
brunino
Site Admin
Messaggi: 665
Iscritto il: dom nov 02, 2014 7:21 pm
Has thanked: 2 times
Been thanked: 57 times

R: Re: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda brunino » dom set 20, 2015 11:58 am

frank ha scritto:se io volessi creare un'estensione che modifica solo i css, tipo PERSONAL.CSS che viene richiamato in stylesheet @import url("PERSONAL.css"); come si fa?


Ti basta seguire la guida nel punto che indica come inserire un css personalizzato con includecss...

Inviato dal mio GT-S5360 con Tapatalk 2


Avatar utente
deeno
Messaggi: 2
Iscritto il: ven apr 01, 2016 10:39 am

Re: [italiano] Guida per sviluppare estensioni

Messaggio da leggereda deeno » ven apr 01, 2016 10:45 am

It is very nice.



Chi ha visto questo topic

brunino (43), cece74 (1), systemcrack (2), Aldo (2), frank (78), fourbrothersnews (1), legionario82 (2), costanzo (1), spyro (2), ozzi (2), Buddy (8), alagia (5), sakkioto2 (1), deeno (2), esqa (1), Nick (2), caroline111 (1), Andrea Isi (2)

Torna a “Guide”

Chi c’è in linea

Visitano il forum: Nessuno e 4 ospiti

  • Argomenti più visti
    Top Poster
    Ultimi Post
cron

Login