Aiuto:Accessori/Pulsanti della toolbar
|
Questa è la documentazione per Pulsanti della toolbar, un accessorio che può essere abilitato in Preferenze/Accessori. Il relativo script si trova in MediaWiki:Gadget-toolbar.js.
|
Con questo accessorio è possibile aggiungere alla barra degli strumenti di modifica ulteriori pulsanti per l'inserimento di tag di formattazione e dei template più comuni sulla Wikipedia in italiano. I pulsanti sono circa settanta e sono raggruppati in quattro gruppi: "Formattazione", "Avvisi voci", "Messaggi utente" e "Altro". Molti dei pulsanti appaiono solo nel namespace in cui è corretto utilizzarli.
I pulsanti che inseriscono template ne richiedono i parametri tramite una finestra di dialogo. Quelli invece che inseriscono tag di formattazione, in caso di selezione di testo nell'area di modifica, circondano la selezione con il tag.
Selezione dei pulsanti
Tramite una finestra di opzioni è possibile selezionare quali pulsanti visualizzare nella barra di modifica. La finestra di scelta si attiva dall'icona "Opzioni" 
, la prima a sinistra nell'area attivata dal menù "Altri pulsanti".
I pulsanti sono raggruppati in quattro tab, uno per tipologia e disposti in una tabella. Su ogni riga è presente l'icona, la descrizione e un checkbox per inserire la spunta. Cliccando "Salva" al fondo della finestra di dialogo i pulsanti selezionati sono aggiunti immediatamente alla barra degli strumenti di modifica e salvati nelle proprie preferenze.
Note tecniche
Questa sezione serve solo agli utenti che volessero aggiungere nuovi pulsanti alla toolbar (o per gli amministratori dell'interfaccia per modificare quelli già esistenti, definiti in MediaWiki:Gadget-toolbar-buttons.js). Richiede una conoscenza almeno di base di JavaScript.
Per l'accessorio un pulsante è rappresentato come un object literal[1], che estende le caratteristiche di mw:Extension:WikiEditor per la toolbar avanzata e dalla libreria mw.toolbar per la toolbar classica[2], aggiungendovi varie funzionalità integrate, come il supporto per i template, la finestra di dialogo per richiederne i parametri, le scorciatoie da tastiera, la modifica del campo oggetto, l'inserimento nella finestra opzioni di selezione dei pulsanti, ...
Nota: per chi non fosse interessato a queste funzionalità aggiuntive o volesse crearsele da solo, può sempre utilizzare direttamente le funzioni di wikiEditor o della toolbar classica dai propri script utente personali, come descritto a mw:Extension:WikiEditor/Toolbar customization, mw:Extension:WikiEditor/Toolbar customization/Library e mw:Manual:Custom edit buttons.
L'oggetto definito dall'accessorio ha le seguenti proprietà, in parte obbligatorie e facoltative:
- obbligatorie
- group (string): può assumere uno dei quattro valori "formattazione", "avvisivoci", "messaggiutente" o "altro". Serve per indicare in quale gruppo far comparire il pulsante nella toolbar e nella finestra opzioni di selezione dei pulsanti.
- icon (string): url completa all'immagine da usare per il pulsante.
- una terza proprietà obbligatoria va scelta fra "text", "template" e "execute", mutualmente esclusive, descritte nelle sezioni successive
- facoltative
- hotkey (string): un singolo carattere maiuscolo per indicare la scorciatoia da tastiera per attivare il pulsante, da usare insieme al tasto Alt.
- ns (array): un array di interi corrispondenti al numero di namespace in cui far comparire il pulsante. Per i casi più complessi si può utilizzare invece di un numero una funzione, che deve restituire true se il pulsante va fatto comparire.
- summary (string): il testo da usare nel campo oggetto. Se il campo oggetto contiene già del testo, è aggiunto al precedente. In caso di inserimento di template, il valore predefinito è "+NomeTemplate", quindi va utilizzata solo se diversa da questo valore.
- descr (string): il testo da visualizzare nella finestra Opzioni come descrizione del pulsante, se diverso dal predefinito.
text
La proprietà text serve per inserire del testo semplice nell'area di modifica alla posizione del cursore, o della selezione. L'accessorio utilizza per questa funzione il plugin jQuery textSelection[3], quindi ha le stesse relative proprietà, le principali:
- pre (string): il testo da inserire prima del cursore (o della selezione).
- post (string): il testo da inserire dopo il cursore (o della selezione).
- peri (string): il testo da inserire tra pre e post e da selezionare successivamente.
- replace (boolean): in caso di selezione determina la sostituzione della selezione con il valore di peri.
template
La proprietà template serve per inserire un template nell'area di modifica. È un oggetto con le seguenti proprietà:
- obbligatorie:
- name (string): il nome del template da inserire, senza "template:" e senza parentesi graffe.
- facoltative
- subst (boolean): se impostato a true verrà aggiunto "subst:" prima del nome del template.
- sign (boolean): se impostato a true verrà aggiunta la firma dopo il template.
- noinclude (boolean): se impostato a true il template verrà incluso nel tag noinclude.
- extratext (string): eventuale testo aggiuntivo dopo il template.
- position (string): può assumere uno dei due valori "top" o "bottom". Di default il template è inserito alla posizione del cursore. Con "top" invece verrà inserito all'inizio dell'area di modifica, con "bottom" al fondo.
- params (object): questo oggetto serve per richiedere i parametri del template tramite una finestra di dialogo. Ogni sua proprietà è il parametro da richiedere, definito tramite:
- type (string): può assumere uno dei tre valori "textbox", "combobox" o "checkbox". Con textbox verrà creata una casella di testo, con combobox una casella combinata e con checkbox una casella di spunta.
- label (string): l'etichetta che apparirà sopra la casella di input.
- value (string, array, boolean): valore che assumeranno rispettivamente il textbox, il combobox o il checkbox. Utilizzare una stringa per il textbox, un array per il combobox e un boolean per il checkbox.
- autocomplete (string): si può utilizzare solo con il type "textbox" e può assumere uno dei due valori "contribs" o "users". Con "contribs" la casella di input è autocompletata con i nomi delle ultime pagine editate, con "users" è autocompletata con i nomi degli utenti.
- format (function): questa proprietà è obbligatoria nel caso si sia utilizzato "params". È una funzione che riceve un unico argomento, "params", un array associativo tramite il quale vengono restituiti i parametri del template inseriti dall'utente. La funzione deve restituire il testo da inserire tra il nome del template, fino alla chiusura delle graffe. La funzione può essere utilizzata anche senza che si sia utilizzata la proprietà params, nel caso si vogliano aggiungere parametri predefiniti al template.
execute
La proprietà execute è una funzione da eseguire quando l'utente clicca sul pulsante. Va utilizzata per eseguire quelle funzionalità non riconducibili all'inserimento di testo o di template, come potrebbe essere effettuare correzioni grammaticali nel testo.
Aggiunta di pulsanti personalizzati
Attenendosi alla documentazione tecnica della sezione precedente, ogni utente può aggiungere dei propri pulsanti personalizzati alla toolbar. Verranno inseriti nella finestra di Opzioni, dalla quale andranno abilitati, come per i pulsanti predefiniti. I pulsanti vanno definiti in una propria sottopagina utente, Speciale:MiaPaginaUtente/toolbarbuttons.js, come segue:
window.gadgetToolbarUserButtons = {
'nome pulsante1': {
... definizione pulsante1 ...
},
'nome pulsante2': {
... definizione pulsante2 ...
}
};
È possibile trovare icone già pronte alla pagina commons:MediaWiki edit toolbar e nelle categorie: commons:category:MediaWiki edit toolbar e commons:category:MediaWiki edit toolbar formatting buttons.
Esempio completo
Segue un esempio completo contenente diversi pulsanti, per ogni principale tipologia: testo ('Code nowiki'), template ('Curiosità'), template con richiesta parametri ('Cinematografo') e funzione ('Accento').
window.gadgetToolbarUserButtons = {
'Code nowiki': {
group: 'formattazione',
icon: '//upload.wikimedia.org/wikipedia/commons/7/73/Button_code_nowiki.png',
text: {
pre: '<code><nowiki>',
post: '</nowiki></code>'
}
},
'Curiosità': {
group: 'avvisivoci',
ns: [ 0 ],
icon: '//upload.wikimedia.org/wikipedia/commons/2/28/Button_info.png',
template: {
name: 'Curiosità'
}
},
'Cinematografo': {
group: 'altro',
icon: '//upload.wikimedia.org/wikipedia/commons/5/58/Button_C.png',
template: {
name: 'Cinematografo',
params: {
tipo: {
type: 'combobox',
label: 'Tipo',
value: [ 'compagnia', 'film', 'nome' ]
},
id: {
type: 'textbox',
label: 'Id',
},
titolo: {
type: 'textbox',
label: 'Titolo (opzionale)',
}
},
format: function ( params ) {
return '|' + params.tipo + '|' + params.id +
( params.titolo ? '|' + params.titolo : '' );
}
}
},
'Accento': {
group: 'altro',
icon: '//upload.wikimedia.org/wikipedia/commons/3/35/Button_ébauche2.png',
descr: 'Sostitusce le occorrenze di perchè con perché.',
execute: function () {
var n = 0, newText = $( '#wpTextbox1' ).val().replace( /perchè/g, function () {
n += 1;
return 'perché';
} );
$( '#wpTextbox1' ).select().val( newText );
alert( 'Sostituzioni effettuate: ' + n );
}
}
};