Capitolo 3. Creazione delle voci di menu

Quando si crea una nuova estensione, è necessario indicarlo a RKWard. Quindi la prima cosa da fare è scrivere un file .pluginmap (o modificarne uno esistente). Il formato del file .pluginmap è XML. Vi guideremo attraverso un esempio (assicurarsi, ovviamente, di aver configurato RKWard per caricare la propria .pluginmap - Impostazioni → Configura RKWard → Estensioni):

<!DOCTYPE rkpluginmap>
        

Il doctype non è realmente interpretato, ma impostarlo comunque a "rkpluginmap".

<document base_prefix="" namespace="mie_estensioni" id="mia_mappa_estensioni">
        

L'attributo base_prefix può essere utilizzato, se tutte le estensioni si trovano in una cartella comune. Fondamentalmente, quindi è possibile omettere quella cartella dai nomi dei file specificati di seguito. È sicuro lasciarlo su "".

Come si vedrà di seguito, tutte le estensioni ottengono un identificatore univoco, id. namespace è un modo per organizzare tali ID e rendere meno probabile la creazione accidentale di un identificatore duplicato. Internamente, fondamentalmente lo spazio dei nomi e quindi un «::» viene anteposto a tutti gli identificatori specificati in questa .pluginmap. In generale, se si intende distribuire le estensioni in un pacchetto di R, è una buona idea utilizzare il nome del pacchetto come parametro namespace. Le estensioni fornite con la distribuzione ufficiale di RKWard hanno namespace="rkward".

L'attributo id è facoltativo, ma specificando un id per la propria .pluginmap si consente ad altre persone di poter caricare automaticamente la vostra .pluginmap dalle loro .pluginmap (vedere la sezione sulle dipendenze).

<components>
        

Componenti? Non stiamo parlando di estensioni? Sì, ma in futuro le estensioni non saranno altro che una classe speciale di componenti. Quello che facciamo qui, quindi, è registrare tutti i componenti/estensioni con RKWard. Diamo un'occhiata a una voce di esempio:

<component type="standard" id="t_test_two_vars" file="test_t_due_variabili.xml" label="Test t a due variabili" />
        

Innanzitutto l'attributo type: lasciarlo su "standard" per ora. Altri tipi non sono ancora implementati. L'id a cui abbiamo già accennato. A ciascun componente deve essere assegnato un identificativo univoco (nel suo spazio dei nomi). Sceglierne uno facilmente riconoscibile. Evitare spazi e caratteri speciali. Finora non sono stati vietati, ma potrebbero avere significati speciali. Con l'attributo file, si specifica dove si trova la descrizione dell'estensione attuale. Questo è relativo alla cartella in cui si trova il file di .pluginmap e il base_prefix sopra. Infine, fornire un'etichetta al componente. Questa etichetta sarà mostrata nel momento in cui l'estensione viene inserita nel menu (o in futuro, forse anche in altri posti).

Tipicamente un file di .pluginmap conterrà diversi componenti, quindi eccone alcuni:

<component type="standard" id="test_non_implementato" file="means/unimplemented.xml" />
                <component type="standard" id="test_t_fittizio" file="means/ttests/fictional.xml" label="Questo è un test t fittizio" />
                <component type="standard" id="descrittiva" file="descriptive.xml" label="Statistiche descrittive" />
                <component type="standard" id="corr_matrix" file="corr_matrix.xml" label="Matrice di correlazione" />
                <component type="standard" id="anova_semplice" file="simple_anova.xml" label="Anova semplice" />
        </components>
        

OK, questo è stato il primo passo. RKWard ora sa che esistono quelle estensioni. Ma come invocarle? Devono essere inserite in una gerarchia di menu:

<hierarchy>
                <menu id="analisi" label="Analisi">
        

Proprio sotto il tag <hierarchy>, si inizia a descrivere, in quale <menu> le proprie estensioni dovrebbero andare. Con la riga sopra, in pratica si indica che la propria estensione dovrebbe essere nel menu Analisi (non necessariamente direttamente lì, ma in un sottomenu). Il menu Analisi è standard in RKWard, quindi non deve essere creato da zero. Tuttavia, se non esistesse ancora, usando l'attributo label si attribuisce il suo nome. Infine, id identifica ancora una volta questo <menu>. Questo è necessario, in modo che diversi file di .pluginmap possono posizionare le loro estensioni negli stessi menu. Lo fanno cercando un <menu> con il id indicato. Se l'ID non esiste ancora, sarà creato un nuovo menu. Altrimenti le voci saranno aggiunte al menu esistente.

<menu id="medie" label="Medie">
        

Fondamentalmente la stessa cosa qui: ora definiamo un sottomenu nel menu Analisi. Deve essere chiamato Medie.

<menu id="test_t" label="Test t">
        

E un livello finale nella gerarchia dei menu: un sottomenu del sottomenu Medie.

<entry component="test_t_due_variabili />
        

Ora, finalmente, questo è il menu in cui vogliamo inserire l'estensione. Il tag <entry> segnala che in realtà è il posto effettivo, invece di un altro sottomenu. L'attributo component si riferisce all'id fornito all'estensione/componente suddetta.

<entry component="fictional_t_test" />
                                </menu>
                                <entry component="fictional_t_test" />
                        </menu>
                        <menu id="frequency" label="Frequenza" index="2"/>
        

In caso di smarrimento: questo è un altro sottomenu del menu Analisi. Vedere la schermata seguente. Salteremo parte di ciò che non è visibile, contrassegnato da [...].

[...]
                        </menu>
                        <entry component="corr_matrix"/>
                        <entry component="descriptive"/>
                        <entry component="simple_anova"/>
                </menu>
        

Queste sono le voci finali visibili nelle schermate seguenti.

<menu id="grafici" label="grafici">
                        [...]
                </menu>
        

Ovviamente è possibile inserire anche le proprie estensioni in menu diversi da Analisi.

<menu id="file" label="File">
                        [...]
                </menu>
        

Anche nei menu standard come File. Tutto ciò di cui si ha bisogno è l'id corretto.

</hierarchy>        
</document>
        

Ecco come farlo. E questa schermata mostra il risultato:

Confusi? Il modo più semplice per iniziare è probabilmente prendere alcuni dei file di .pluginmap esistenti forniti con la distribuzione e modificandoli in base alle proprie esigenze. Inoltre, se si ha bisogno di aiuto, non esitare a scrivere alla lista di distribuzione di sviluppo.