MediaWiki/Hacking interfaccia

Il software MediaWiki mette a disposizione la possibilità agli utenti o agli amministratori del sito di creare script JS e fogli di stile per personalizzare l'interfaccia della wiki.

Con i fogli di stile

Mediante i fogli di stile (CSS), è possibile personalizzare totalmente l'aspetto dell'interfaccia di MediaWiki. Di seguito, saranno esaminati alcuni trucchetti o esempi già pronti di dichiarazioni per modificare la grafica della nostra wiki.

Per la lettura di questa sezione è fortemente consigliato conoscere il linguaggio CSS.

Reperire i giusti selettori

Per chi usa Mozilla Firefox è sufficiente premere contemporaneamente Ctrl+U per aprire una finestra in cui è visualizzato tutto il codice sorgente della pagina al momento caricata.

Questo serve per individuare la struttura DOM della pagina e gli attributi ID e class dei diversi elementi HTML: questo è indispensabile se si vuole personalizzare l'interfaccia tramite i CSS, in quanto questi ragionano in termini di codice sorgente e struttura del documento web.

Per approfondire, vedi CSS/Selettori.

È molto comodo, inoltre, l'uso dell'estensione di Firefox Web Developer Toolbar, la quale fornisce un'interessante funzionalità che permette di evidenziare l'elemento corrente indicandone anche la posizione nel DOM.

Alcuni selettori sono presenti in alcune pagine ed assenti in altre, quindi in caso di personalizzazioni "estreme" sarà necessario visualizzare il codice sorgente di una pagina per ogni namespace.
Per esempio i tab nella parte superiore delle pagine (link modifica, cronologia, sposta, ecc) hanno ID differenti a seconda del namespace della pagina; il tab con scritto "Template" è presente solo nelle pagine di template, quindi nel caso in cui volessimo modificare questo tab, esempio per metterci una piccola immagine al suo interno, dovremmo guardare il sorgente di una pagina casuale di template.

Un semplice esempio: inserire delle iconcine alle tab

Premendo Ctrl+U e cercando con lo strumento apposito di FireFox (Ctrl+F) il titolo della pagina, veniamo rimandati ad una porzione di codice, per riconoscere i tab, basta cercare delle parole chiave, ad esempio "template", dopo varie ricerche, vedremo del codice come quello nell'esempio qui sotto:

<li id="ca-nstab-template" class="selected">
 <a href="/wiki/Template:MediaWiki" title="Vedi il template [c]" accesskey="c">Template</a>
</li>

Sono tre righe di semplice HTML, ma in alcune possiamo trovare alcuni elementi a noi molto utili:

• li id="ca-nstab-template": ID dell'elemento, nel CSS servirà come primo selettore per la personalizzazione.
• class="selected": dichiara al software che il tab è selezionato; è un'informazione utile se ad esempio vogliamo lavorare solo sulla tab selezionata.
• a href="/wiki/Template:MediaWiki": link alla pagina.
• title="Vedi il template [c]": ciò che appare lasciando il puntatore del mouse fermo sul tab.
• accesskey="c": scorciatoia da tastiera (alt+shift+c, che però si limita a ricaricare la pagina).
• Template: testo che appare dentro al tab, utile per farci rendere conto se siamo nella porzione di codice giusta.
• </a></li>: chiusura dei tag.

Utilizzando Web Developer, invece, è possibile fare click su "Outline" nella toolbar apposita e poi "Outline Current Element" e "Show element Names When Outlining. I questo modo, passando sulla tab, potremo esaminare la sua posizione all'interno della gerarchia del DOM e individuarne l'ID e l'eventuale classe.

Quindi nel caso in cui volessimo aggiungere delle piccole icone al tab "template", dovremo usare il seguente codice CSS:

li#ca-nstab-template a {
 padding-left: 18px;
 background:url( http://Indirizzo_completo/immagine.estensione) top left no-repeat !important;
}

Questa dichiarazione CSS serve per inserire un'iconcina accanto al testo della tab "template". In particolare:

• li#ca-nstab-template a: questa parte del codice (selettore) serve a CSS per identificare l'elemento o gli elementi della pagina a cui applicare le dichiarazioni inserite tra le parentesi graffe: in questo caso, indichiamo di prendere tutti gli elementi <a> contenuti nell'elemento <li> che presenta l'ID ca-nstab-template, cioè la tab del namespace "template".
• padding-left: 18px;: questa dichiarazione CSS indica di inserire all'interno della tab un padding sinistro di 18px. In pratica, aggiunge una spaziatura di 18px a sinistra del testo nella tab per fare spazio all'iconcina.
• background: url(http://Indirizzo_completo/immagine.estensione): indirizzo da cui prelevare l'immagine. Attenzione: l'immagine, nel caso specifico dei tab, deve essere di dimensioni 16x16 pixel, altrimenti potrebbe non vedersi o vedersi in parte.
  L'indirizzo, nel caso in cui fosse un'immagine caricata in una wiki, non è l'indirizzo che appare nella wiki, ma la sua URL, che può essere reperita nella pagina apposita scrivendo il nome dell'immagine. Se invece fosse caricata in un sito esterno, ad esempio il vostro, se navigate con FF potete cliccare con il tasto destro del mouse sull'immagine, e scegliere Copia indirizzo immagine.
• top left: questa parte della dichiarazione CSS specifica di inserire l'immagine nell'angolo in alto a sinistra della tab
• no-repeat: questa parola chiave indica che l'immagine non deve essere ripetuta nella tab
• !important: questo modificatore serve per attribuire più peso alla dichiarazione CSS. Se non inserita, potrebbe essere superata dal codice CSS proveniente da altri file.

Questo codice va inserito nel proprio monobook personale in qualsiasi posizione, anche in fondo va bene: in questo modo il codice sarà visibile solo dall'utente che ne ha fatto uso. Per rendere la modifica visibile a tutti, il codice va aggiunto al file Common.css di sistema, modificabile però solo da amministratori

Ultime modifiche colorate

Le RC colorate in azione

Utilizzando i CSS è possibile anche personalizzare la pagina delle Ultime modifiche. È possibile ad esempio con alcune dichiarazioni CSS differenziare con diversi colori le modifiche positive, negative o nulle. Questo grazie al software, che inserisce questo numero accanto al link alla pagina all'interno di un elemento <span> con una classe particolare:

• .mw-plusminus-pos: questa classe identifica le modifiche positive (cioè nelle quali sono stati aggiunti dei caratteri).
• .mw-plusminus-neg: identifica le modifiche negative.
• .mw-plusminus-null: identifica le modifiche nulle.

Conoscendo queste tre classi, è possibile identificare ciascuna modifica di un certo tipo e attribuire a ciascuna di esse un diverso stile utilizzando ad esempio la proprietà color

Notifica nuova messaggi

Quando un utente riceve nuovi messaggi, MediaWiki mostra un messaggio di avviso. La notifica può essere personalizzata in quanto è identificata dalla classe usermessage. Ad esempio:

.usermessage { /* imposta uno sfondo blu */
 background: blue;
 border-color: navy; 
 color: aqua;
}

.usermessage a { /* imposta i link bianchi altrimenti non si vede nulla */
color: white;
}

.usermessage a:visited { /* colora di rosso i link già visitati */
color: red;
}

Table of Content

La tabella dei contenuti (o "TOC") non è altro che una tabella HTML con id #toc. Possiamo ad esempio lavorare sullo span .tocnumber nascondendolo:

#toc .tocnumber {
 display: none; /* nasconde l'elemento */
}

In particolare, questa dichiarazione nasconde i numeri accanto ai titoli nel TOC

Con i JavaScript

Anche tramite il linguaggio JavaScript è possibile modificare l'interfaccia di MediaWiki, anche se in modo diverso. Mentre con i CSS è possibile eseguire solo modifiche alla visualizzazione, lavorando con gli script è possibile anche aggiungere, rimuovere o nascondere elementi della pagina. Per la lettura di questa sezione è fortemente consigliato conoscere il linguaggio JavaScript.

Una funzione JavaScript molto interessante che mette a disposizione il software è addOnloadHook(), che permette di eseguire una funzione al caricamento della pagina.
Infatti, senza far ricorso a questa funzione, le istruzioni verrebbero eseguite prima del caricamento della pagina, senza poter accedere agli elementi del DOM.

In generale, per far eseguire un JavaScript in ogni pagina di MediaWiki, utilizziamo questo codice:

addOnloadHook( function () {
 //le istruzioni inserite qui verranno eseguite al caricamento della pagina
}
);

Questa istruzione va inserita nel proprio Monobook.js (per creare un JavaScript personale) oppure nel suo omologo nel namespace MediaWiki (per far eseguire lo script in ogni pagina della wiki).
Ovviamente è possibile inserire nel monobook delle funzioni, ma queste devono essere comunque eseguite tramite lo hook.

Creare un portlet personalizzato

Muovendosi tra gli oggetti del DOM, è possibile creare, modificare o eliminare gli oggetti nella pagina; per esempio è possibile creare un menu personale nella barra laterale (portlet), partendo da quelli già esistenti:

//tratto da [[User:Ramac/monobook.js]]
var barra = document.getElementById('p-navigation').parentNode; //ottiene un riferimento alla barra laterale
var com = document.getElementById('p-community'); //ottiene un riferimento alla sezione comunità (solo per it.books,
// per altre wiki è necessario ottenere l'ID degli altri portlet)
 
//crea i nuovi elementi e imposta gli attributi
var mieiLink = document.createElement('DIV'); //div che contiene tutto il nuovo portlet
var titolo = document.createElement('H5'); //intestazione del portlet
var divBody = document.createElement('DIV'); //corpo del portlet
var ul = document.createElement('UL'); //crea un elenco puntato dentro il quale saranno inseriti i link
 
mieiLink.setAttribute("class","portlet"); //necessario per la visualizzazione
mieiLink.setAttribute("id","p-myLinks");
divBody.setAttribute("class","pBody");

var textTitolo = document.createTextNode("TITOLO"); //titolo del portlet
titolo.appendChild(textTitolo); //inserisce il testo nel tag <h5>

//inserisce gli elementi nella pagina
divBody.appendChild(ul);
mieiLink.appendChild(titolo);
mieiLink.appendChild(divBody);

//inserisce infine il div nella barra laterale prima del portlet comunità
barra.insertBefore(mieiLink, com);

In questo modo è stato creato un nuovo box nella barra laterale (come "navigazione" o "ricerca" pronto a contenere i nostri link o i nostri oggetto HTML. Sarà sufficiente infatti creare un nuovo oggetto DOM e poi "appenderlo" all'elemento <ul> memorizzato nella variabile ul. Il codice seguente inserisce nel porlet appena creato un link:

var l = document.createElement('LI'); //crea un punto elenco
l.setAttribute('id','l-miolink'); //imposta un ID, non si sa mai, può servire
 
//crea il link e ne imposta gli attributi
var link = document.createElement('A');
link.setAttribute('href', 'url a cui punta il link');
link.setAttribute('title', 'titolo del link');

//crea il testo per il link e lo aggiunge ad esso
var text = document.createTextNode('testo del link');
link.appendChild(text);

//"appende" (inserisce) prima il link al punto elenco e poi questo all'elenco puntato
l.appendChild(link);
ul.appendChild(l);

Ovviamente non è possibile inserire solo link; è possibile anche inserire moduli ad esempio per creare un box di ricerca personalizzato, o qualsiasi altro elemento XHTML.

Aggiungere eventi agli oggetti della pagina

Per motivi di sicurezza e di comodità, è impossibile aggiungere script JavaScript all'interno delle pagine wiki tramite l'uso del tag <script> o gli eventi associati agli oggetti (utilizzando ad esempio gli attributi onclick o onmousemove. L'unico modo per poter aggiungere questi hook è tramite gli script personali o di sistema:

//per comodità definiamo una funzione
//la useremo per gestire l'evento click
function link_onclick () {
 alert("Hai cliccato sul pulsante");
 return false;
}
addOnloadHook ( function (){
 var link = document.getElementById('l-javascript'); //accediamo all'elemento creato prima
 if (link) { //se la variabile contiene Null il link non esiste e non viene eseguito questo codice
  link.onClick = link_onclick; //si noti che non sono messe le parentesi
  //questo perché vogliamo ottenere un riferimento alla funzione
  //e non il valore che questa restituisce
 }
}
);

In generale, per collegare un evento ad un oggetto della pagina, è sufficiente accedervi tramite il DOM e poi impostare correttamente la proprietà relativa all'evento da collegare.