Hoofdstuk 3. Menu-ingangen aanmaken

Wanneer u een nieuwe plugin maakt, moet u dit aan RKWard vertellen. Dus is het eerste wat u moet doen, het schrijven van een .pluginmap-bestand (of het wijzigen van een bestaand bestand). Het formaat van een .pluginmap-bestand is XML. Ik loop met u door een voorbeeld (ook, natuurlijk, moet u er voor zorgen dat RKWard zo is ingesteld, dat het uw .pluginmap inleest -- Instellingen → RKWard instellen → Plugins):

<!DOCTYPE rkpluginmap>
        

De doctype wordt niet werkelijk geïnterpreteerd, maar wel ingesteld op "rkpluginmap".

<document base_prefix="" namespace="myplugins" id="mypluginmap">
        

Het base_prefix-attribuut kan worden gebruikt als al uw plugins in dezelfde directory zijn. U kunt dan die directory weglaten uit de hieronder genoemde bestandsnamen. U kunt die veilig "" laten blijven.

Zoals u hieronder zult zien, krijgen alle plugins een unieke naam, id. De namespace is een manier waarop IDs worden georganiseerd, zodat zij niet zo gauw per ongeluk dezelfde naam krijgen. In feite komt het erop neer dat de namespace (naamruimte) en daarna een“::” worden voorgevoegd aan alle namen die u opgeeft in deze .pluginmap. In het algemeen moet u, als u van plan bent uw plugins uit te geven in een R-pakket, het is een goed idee om de pakketnaam als namespace-parameter. Plugins geleverd met de officiële RKWard-distributie heeft namespace="rkward".

Het id-attribuut is optioneel, maar een id (een naam dus)voor uw .pluginmap opgeven maakt het anderen mogelijk hun.pluginmaps uw .pluginmap, automatisch te laten inlezen (zie de sectie over afhankelijkheden).

<components>
        

Componenten? We spreken toch over plugins? Ja, maar in de toekomst zijn plugins niets anders dan een speciale class van componenten. Wat we hier dus aan het doen zijn, is alle componenten/plugins te registreren in RKWard. Bekijken we een voorbeeld:

<component type="standard" id="t_test_two_vars" file="t_test_two_vars.xml" label="Two Variable t-Test" /> (Vert.: Door het hele document vertaal ik dit niet, om de kans op verwarring, bij mij en de lezer, te minimaliseren. De vertaling hier zou zijn: <component type="standaard" id="t_test_twee_vars" file="t_test_twee_vars.xml" label="Twee variabelen t-Test" />)
        

Eerst het type-attribuut: Laat dit voorlopig "standard" zijn. Andere typen zijn er nog niet. De id is al kort aan bod geweest. Elke component moet een (in zijn eigen namespace) unieke naam hebben. Kies er een die gemakkelijk herkenbaar is. Geen spaties, en geen speciale karakters. Mag wel, voorlopig, maar die kunnen een speciale betekenis hebben. Met het file-attribuut, geeft u de locatie op van de beschrijving van de actuele plugin zelf. Die is relatief ten opzichte van de directory waarin het .pluginmap-bestand is, en de base_prefix hierboven. Tenslotte, geef de component een naam. Deze naam wordt overal getoond waar de plugin in het menu wordt geplaatst (of in de toekomst ook elders).

Een .pluginmap-bestand bevat typisch een aantal componenten, dus hier zijn er nog een paar:

<component type="standard" id="unimplemented_test" file="means/unimplemented.xml" />
                <component type="standard" id="fictional_t_test" file="means/ttests/fictional.xml" label="This is a fictional t-test" />
                <component type="standard" id="descriptive" file="descriptive.xml" label="Descriptive Statistics" />
                <component type="standard" id="corr_matrix" file="corr_matrix.xml" label="Correlation Matrix" />
                <component type="standard" id="simple_anova" file="simple_anova.xml" label="Simple Anova" />
        </components>
        

OK, dit was het eerste (onvertaalde, tussen "" staan wat teksten) stapje. RKWard weet nu dat die plugins er zijn. Maar hoe die te gebruiken? Zij moeten in een menu-hiërarchie worden geplaatst:

<hierarchy>
                <menu id="analyse" label="Analysis">
        

Direct onder de <hierarchy> tag, begint u met de beschrijving van in welk <menu> uw plugins moeten komen. In de regel boven zegt u eigenlijk dat uw plugin moet komen in het menu Analyse (niet noodzakelijk direct daar, maar in een submenu). Het menu Analyse is standaard aanwezig in RKWard, dus hoeft het niet helemaal opnieuw te worden aangemaakt. Maar als het nog niet bestond, zou u met het label-attribuut zijn naam geven. Tenslotte zal met de id dit <menu> nog een naam krijgen. Dit is nodig, zodat diverse .pluginmap-bestanden hun plugins in dezelfde menus kunnen plaatsen. Dit gebeurt door te kijken naar een <menu> in de gegeven id. Indien de ID nog niet bestaat wordt een nieuw menu aangemaakt. En anders worden de ingangen toegevoegd aan het bestaande menu.

<menu id="means" label="Gemiddelden">
        

In principe hier hetzelfde: Nu definiëren we een submenu in het menu Analyse. Het moet de naam Gemiddelden krijgen.

<menu id="ttests" label="t-toetsen">
        

En een laatste level in de menu-hierarchie: een submenu van het submenu Gemiddelden.

<entry component="t_test_two_vars" />
        

Nu, eindelijk, is dit het menu waarin we de plugin willen plaatsen. De <entry> tag geeft aan dat dit het is,in plaats van weer een ander submenu. Het component-attribuut verwijst naar de id (naam) die u hierboven aan de component gaf.

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

Voor als u het spoor bijster bent: Dit is nog een submenu van het menu Analyse. Zie het onderstaande schermbeeld. We slaan een en ander over dat niet zichtbaar is, gemarkeerd met [...].

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

Dit zijn de uiteindelijke ingangen, zichtbaar in onderstaande schermbeelden.

<menu id="plots" label="Plots">
                        [...]
                </menu>
        

Natuurlijk kunt u uw plugins ook plaatsen in andere menu's dan het menu Analyse.

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

Zelfs in standaard menu's zoals Bestand. Alles wat nodig is, is een correcte id.

</hierarchy>        
</document>
        

Zo moet u het aanpakken. En dit schermbeeld toont het resultaat:

Duizelt het u? De beste manier om te beginnen, is mogelijk om uit te gaan van de bestaande .pluginmap-bestanden die met de distributie worden geleverd, en die te wijzigen daar waar u dit nodig vindt. En ook: indien u hulp wenst, aarzel dan niet te schrijven naar de development mailing list (Engels).