SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Descarregar

Fer un primer plugin

Setembre de 2006 — mis à jour le : Agost de 2010

Totes les versions d’aquest article:


Es crea un plugin al mateix indret que s’instal·la aquells que es poden recuperar i ja estan preparats per funcionar (veure «Instal·lar un plugin »).

El sistema de plugins es fonamenta en la cerca de camins coneguts a dins d’una llista ben concreta. Els tecnòfils anomenaran això SPIP_PATH (cf. On ubicar els fitxers dels esquelets?). L’activació o no, d’un plugin es determina per l’afegit del seu directori associat en aquesta llista. Per tant, per fer el vostre primer plugin us cal crear:

-  Una carpeta plugins/ a l’arrel del lloc Web. La conseqüència directa d’aquesta acció és activar la interfície de gestió dels plugins. El primer símptoma serà l’aparició del botó «Gestió de plugins» a dins del menú «Configuració» de la interfície privada (només quan la interfície la tenim en mode complet)

-  Una subcarpeta mon_premier_plugin/ pel plugin a realitzar.

Per a indicar a SPIP el què és assenyat que faci el plugin, això es troba descrit per un fitxer, que porta el nom plugin.xml, que s’ha creat a dins de la carpeta del mateix plugin. Es tracta d’un fitxer que té una sintaxi estricta però relativament simple tal i com es pot veure:

Es tracta d’un fitxer que conté les úniques etiquetes obligatòries.

-  L’etiqueta nom es pot internacionalitzar gràcies a l’etiqueta multi (exemple: <nom><multi>My first plugin[fr]Mon premier plugin[ca]El meu primer plugin</multi></nom>). És el títol del plugin.
-  L’etiqueta version és purament informativa. No hi ha cap regla precisa per a generar els números de versió. És feina del desenvolupador generar-les ell mateix. No obstant, en un futur és possible que aquest valor serveixi per gestionar possibles dependències i una coherència mínima entre SPIP i els plugins...
-  L’etiqueta prefix és vital. Abans que res és important assegurar la singularitat d’aquest valor entre tots els plugins que instal·leu. A continuació defineix el prefix de les funcions que programareu en php i que seran els elements motors del plugin. D’aquesta manera, si diversos plugins cohabiten amb funcions amb tractaments similars, serà impossible que aquestes provoquin errors a causa dels seus noms. És el que s’anomena també un «espai de noms».

Encara que no produeixi cap efecte de moment, aquest mínim permet ja activar el plugin a dins de la interfície:

Per a fer això, marqueu la casella que hi ha al davant del nom del plugin i cliqueu a sobre del botó «validar» a baix. La zona del títol es torna agrisada.

Divertiu-vos retirant l’una o l’altre de les seves etiquetes per tal ce constatar que SPIP pot indicar-vos el què hi manca o simplement no funciona.

*-*-*

És possible situar altres elements a dins d’un fitxer plugin.xml:

-  L’etiqueta <etat>: 4 possibles valors. En absència d’aquesta etiqueta, o si existeix però està buida, el plugin és considerat com "en desenvolupament". El funcionament del plugin no és de cap manera influenciat pel valor d’aquesta etiqueta. Fixem-nos que un petít símbol gràfic colorit permet reconèixer l’estat d’un cop d’ull.

EstatCaràcter gràficSignificació
dev negre En curs de desenvolupament. Nombrosos bugs possibles. Pot ser que no funcioni.
test taronja La funció principal està operativa i es pot provar. Els desenvolupadors compten amb nosaltres per pujar comentaris sobre eventuals errors o observacions sobre l’ergonomia d’una interfície gràfica, per exemple.
estable verd Completament operatiu. Sense errors, en teoria.
experimental vermell És una aventura!

-  Les etiquetes <auteur> i <description> són facultatives i funcionen com els texts d’un article (totes les dreceres autoritzades) i serveixen per proporcionar informacions concises sobre el plugin. Així el codi:

mostrarà com a conseqüència:

Fixeu-vos que és necessari codificar els caràcters accentuats amb entitats html. (&eacute; per é, per exemple)

*-*-*

Si situeu al mateix nivell que plugin.xml un fitxer squelette.html, el vostre plugin un cop activat, permet l’ús de l’esmentat esquelet que serà utilitzable cridant-lo en el vostre navegador amb la notació «usual»: elvostrelloc.net/spip.php?page=squelette. Es tracta allà d’un simplista però primer exemple de sobrecàrrega de fitxer. Aquest principi serà tractat més exhaustivament en un altre tutorial.

*-*-*

Amb la finalitat d’il·lustrar aquesta demostració, realitzarem un plugin que tingui com objectiu acolorir d’una manera particular cada ocurrència de la paraula «spip» en un text. Per a fer-ho, anem a situar a dins de la carpeta del plugin els 2 fitxers útils i a informar SPIP dels seus noms per mitjà d’algunes etiquetes suplementàries a dins del fitxer XML:

Heus ací la descripció de les 2 etiquetes afegides:

-  <fonctions> : conté el nom d’un fitxer que serà carregat cada vegada que es calculi de nou. És l’equivalent per a cada plugin, del fitxer mes_fonctions.php. Per tant, només s’utilitza pel lloc públic, ja que només és cridat en cas de càlcul de la memòria cau. S’hi posarà típicament filtres o definicions d’etiquetes, de criteris.
-  <options> : conté el nom d’un fitxer que serà carregat a cada crida de pàgina. És l’equivalent per a cada plugin, del fitxer mes_options.php. També s’utilitza a dins de la interfície privada a cada crida de la pàgina.

Creeu els 2 fitxers amb el contingut que segueix:

exemple_fonctions.php:

exemple_options.php:

Atenció ! Hi ha noms de fitxer que és preferible no utilitzar en el cas dels plugins: estem en el marc d’una llista de directoris coneguts, i SPIP s’atura sempre al primer fitxer trobat. Si el fitxer de l’etiqueta <fonctions>, s’anomena mes_fonctions.php, hi haurà confusió amb el fitxer de la vostra carpeta esquelets, si existeix i sobretot, si hi ha programats molts plugins amb aquest nom de fitxer, els sistema corre el risc de perdre’s... el mateix per mes_options.php, que fa falta reservar pel nucli d’SPIP així com pels fitxers de llengües local_xx.php pels quals es preferirà un altre mètode descrit en un tutorial consagrat a la sobrecàrrega de codi.

Per tant: eviteu els noms «comuns» com mes_fonctions.php i mes_options.php.

Veurem en un altre article com sobrecarregar els directoris d’SPIP. Sapigueu ja que noms de directoris com «models», «formularis», «inc», «acció» etc... s’han d’utilitzar prudentment.

Finalment, tingueu cura de ser molt exactes a l’hora d’agafar noms de fitxers a plugin.xml, la interfície de gestió és molt capritxosa per l’afegit de les últimes etiquetes (missatges d’error que planten el servidor...)

Heus ací, en resum, aquest plugin aporta un nou filtre pels vostres esquelets. Proveu [(#TEXTE|colore_spip)] a dins d’ article.html per exemple.

*-*-*

Hem d’instal·lar tots els plugins a dins de la carpeta plugins/, però també podem crear subcarpetes per classificar els plugins que instal·lem o desenvolupem.

Així, per la següent arborescència:

plugins/
  |
  |-- mon_premier_plugin/
  |-- mes_raccourcis_supplementaires/
         |
         |-- raccourcis_2/
         |-- raccourcis_3/
  |-- mes_autres_plugins/
         |
         |-- raccourcis_4/
         |-- raccourcis_5/

la interfície de gestió tindrà aquest aspecte:

Anar més enllà

Un cop posats per aquest camí, se’ns plantegen, per exemple, interrogants tècnics lligats a problemàtiques de programació en PHP. És legítim.

El lloc de documentació tècnica està pensat per a respondre a aquestes preguntes. Pel que fa als plugins, us podeu dirigir a aquesta adreça si voleu tenir una primera aproximació sobre els punts d’entrada d’SPIP (o «pipeline»).


Descarregar l’esquelet d’aquesta pàgina Lloc Web fet amb l’SPIP | Espace de traduction | Espai privat