Us adonareu immediatament que el flux de treball és molt diferent: al contrari d'escriure directament codi XML, no comenceu amb la definició <document>, sinó directament amb els elements del connector que us agradaria tenir al diàleg. Podeu assignar cada element d'interfície, ja siguin caselles de selecció, menús desplegables, «varslots» o qualsevol altra cosa, a objectes individuals de l'R, i després combinar aquests objectes amb la IGU real. El paquet té funcions per a cada etiqueta XML que es pot utilitzar per a definir la IGU del connector, i la majoria fins i tot tenen el mateix nom, només amb el prefix rk.XML.*. Per exemple, la definició d'una variable <varselector> i dos elements <varslot> per a la variable "x" i "y" de l'exemple de prova t es pot fer mitjançant:

variables <- rk.XML.varselector(id.name="vars")
var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE, id.name="x")
var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE, id.name="y")
                

El detall més interessant probablement és source=variables: Una característica destacada del paquet és que totes les funcions poden generar ID automàtics, de manera que no us heu de molestar pensant o recordant en valors d'id per a referir-vos a un element específic del connector. Senzillament, podeu donar els objectes R com a referència, ja que totes les funcions que necessiten un ID d'algun altre element també poden llegir-lo des d'aquests objectes. rk.XML.varselector() és una mica especial, ja que normalment no té contingut específic per a crear un ID (pot, però només si especifiqueu una etiqueta), de manera que hem d'establir un nom d'ID. Però rk.XML.varslot() no necessitaria els arguments id.name, així que això seria suficient:

variables <- rk.XML.varselector(id.name="vars")
var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE)
var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE)
                

Per tal de tornar a crear el codi d'exemple fins aquest punt, haureu d'establir tots els valors d'ID manualment. Però com que el paquet facilitarà les nostres vides, a partir d'ara ja no ens preocuparà.

Si voleu veure com es veu el codi XML de l'element definit si l'exporteu a un fitxer, només podeu cridar l'objecte pel seu nom. Per tant, si heu anomenat «var.x» en la vostra sessió R, hauríeu de veure quelcom com això:

<varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
                

Algunes etiquetes només són útils en el context d'altres. Per tant, per exemple, no trobareu una funció per a l'etiqueta <option>. En lloc d'això, tant els botons d'opció com les llistes desplegables es defineixen incloent les seves opcions com una llista amb nom, on els noms representen les etiquetes que es mostraran en el diàleg, i el seu valor és un vector amb nom que pot tenir dues entrades, val per al valor d'una opció i el booleà chk per a especificar si aquesta opció està marcada de manera predeterminada.

test.hypothesis <- rk.XML.radio("using test hypothesis",
        options=list(
                "Two-sided"=c(val="two.sided"),
                "First is greater"=c(val="greater"),
                "Second is greater"=c(val="less")
        )
)
                

El resultat quedarà així:

<radio id="rad_usngtsth" label="using test hypothesis">
        <option label="Two-sided" value="two.sided" />
        <option label="First is greater" value="greater" />
        <option label="Second is greater" value="less" />
</radio>
                

Tot el que falta als elements de la pestanya «Configuració bàsica» és la casella de selecció per a mostres aparellades, i l'estructuració de tots aquests elements en files i columnes:

check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))
                

rk.XML.cbox() és una excepció rara on el nom de la funció no conté el nom complet de l'etiqueta, per a desar algun tecleig per a aquest element utilitzat sovint. Això és el que basic.settings conté ara:

<row id="row_vTFSPP10TF">
        <varselector id="vars" />
        <column id="clm_vrsTFSPP10">
                <varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
                <varslot id="vrsl_against" label="against" i18n_context="compare against" source="vars" types="number" required="true" />
                <radio id="rad_usngtsth" label="using test hypothesis">
                        <option label="Two-sided" value="two.sided" />
                        <option label="First is greater" value="greater" />
                        <option label="Second is greater" value="less" />
                </radio>
                <checkbox id="chc_Pardsmpl" label="Paired sample" value="1" value_unchecked="0" />
        </column>
</row>
                

De manera similar, les línies següents crearan objectes R per als elements de la pestanya «Opcions», introduint funcions per a «spinboxes» (botons de selecció de valors), «frames» i «stretch»:

check.eqvar <- rk.XML.cbox("assume equal variances", value="1", un.value="0")
conf.level <- rk.XML.spinbox("confidence level", min=0, max=1, initial=0.95)
check.conf <- rk.XML.cbox("print confidence interval", val="1", chk=TRUE)
conf.frame <- rk.XML.frame(conf.level, check.conf, rk.XML.stretch(), label="Confidence Interval")
                

Tot el que hem de fer ara és reunir els objectes en un «tabbook», i col·locar-lo en una secció «dialog»:

full.dialog <- rk.XML.dialog(
        label="Two Variable t-Test",
        rk.XML.tabbook(tabs=list("Basic settings"=basic.settings, "Options"=list(check.eqvar, conf.frame)))
)
                

També podem crear la secció de l'assistent amb les seves dues pàgines utilitzant els mateixos objectes, de manera que els seus ID s'extrauran per a les etiquetes <copy>:

full.wizard <- rk.XML.wizard(
                label="Two Variable t-Test",
                rk.XML.page(
                        rk.XML.text("As a first step, select the two variables you want to compare against
                                each other. And specify, which one you theorize to be greater. Select two-sided,
                                if your theory does not tell you, which variable is greater."),
                        rk.XML.copy(basic.settings)),
                rk.XML.page(
                        rk.XML.text("Below are some advanced options. It is generally safe not to assume the
                                variables have equal variances. An appropriate correction will be applied then.
                                Choosing \"assume equal variances\" may increase test-strength, however."),
                        rk.XML.copy(check.eqvar),
                        rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
                                the difference in means. Below you can specify whether one should be shown, and
                                which confidence-level should be applied (95% corresponds to a 5% level of
                                significance)."),
                        rk.XML.copy(conf.frame)))
                

Això és per a la IGU. El document global es combinarà al final amb rk.plugin.skeleton().

Fins ara, l'ús del paquet rkwarddev podria no haver ajudat tant. Això canviarà ara mateix.

En primer lloc, de la mateixa manera que no ens havien d'importar els ID dels elements en definir la disposició de la IGU, no ens haurà d'importar els noms de les variables JavaScript en el pas següent. Si voleu més control, podeu escriure codi JavaScript net i enganxar-lo al fitxer generat. Però probablement és molt més eficient fer-ho de la manera del rkwarddev.

El més notable és que no haureu de definir cap variable, ja que rk.plugin.skeleton() pot explorar el codi XML i definir automàticament totes les variables que probablement necessitareu; per exemple, no us molestareu a incloure una casella de selecció si després no utilitzeu el seu valor o estat. Així que podem començar a escriure el codi R real que genera JS immediatament.

El paquet té algunes funcions per a construccions de codi JS que s'utilitzen habitualment en connectors del RKWard, com la funció echo() o les condicions if() {...} else {...}. Hi ha algunes diferències entre el JS i l'R, p. ex., per a paste() a l'R utilitzeu la coma per concatenar les cadenes de caràcters, mentre que per a echo() en el JS utilitzeu «+», i les línies han d'acabar amb un punt i coma. Mitjançant l'ús de les funcions R, gairebé podeu oblidar-vos d'aquestes diferències i continuar escrivint codi R.

Aquestes funcions poden prendre diferents classes d'objectes d'entrada: text net, objectes R amb codi XML com a dalt, o al seu torn resultats d'altres funcions JS del paquet. Al final, sempre cridareu rk.paste.JS(), el qual es comporta de manera similar a paste(), però depenent dels objectes d'entrada els reemplaçarà amb el seu ID XML, el nom de variable JavaScript o fins i tot blocs de codi JavaScript complets.

Per a l'exemple de la prova t, necessitem dos objectes JS: un per a calcular els resultats, i un per a imprimir-los a la funció printout():

JS.calc <- rk.paste.JS(
        echo("res <- t.test (x=", var.x, ", y=", var.y, ", hypothesis=\"", test.hypothesis, "\""),
        js(
                if(check.paired){
                        echo(", paired=TRUE")
                },
                if(!check.paired && check.eqvar){
                        echo(", var.equal=TRUE")
                },
                if(conf.level != "0.95"){
                        echo(", conf.level=", conf.level)
                },
                linebreaks=TRUE
        ),
        echo(")\n"),
        level=2
)

JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
                

Com podeu veure, el rkwarddev també proporciona una implementació R de la funció echo(). Torna exactament una cadena de caràcters amb una versió JS vàlida d'ella mateixa. També us podeu adonar que tots els objectes R aquí són els que hem creat abans. Se substituiran automàticament pels seus noms de variables, per la qual cosa això hauria de ser bastant intuïtiu. Sempre que necessiteu aquest reemplaçament, es pot utilitzar la funció id(), que també retornarà exactament una cadena de caràcters de tots els objectes que s'han indicat (podríeu dir que es comporta com paste() amb una substitució d'objecte molt específica).

La funció js() és un embolcall que permet utilitzar les condicions if(){...} else {...} de l'R com les que esteu acostumat a fer. Es traduiran directament al codi JS. També conserva alguns operadors com <, >= o ||, de manera que podeu comparar lògicament els objectes R sense la necessitat de posar cometes la major part del temps. Mirem l'objecte «JS.calc» resultant, que ara conté una cadena de caràcters amb aquest contingut:

echo("res <- t.test (x=" + vrslCompare + ", y=" + vrslAgainst + ", hypothesis=\"" + radUsngtsth + "\"");
        if(chcPardsmpl) {
                echo(", paired=TRUE");
        } else {}
        if(!chcPardsmpl && chcAssmqlvr) {
                echo(", var.equal=TRUE");
        } else {}
        if(spnCnfdnclv != "0.95") {
                echo(", conf.level=" + spnCnfdnclv);
        } else {}
        echo(")\n");
                

Aquesta secció és molt curta: no cal escriure cap .pluginmap, ja que es pot generar automàticament amb rk.plugin.skeleton(). La jerarquia del menú es pot especificar mitjançant l'opció pluginmap:

[...]
        pluginmap=list(
                name="Two Variable t-Test",
                hierarchy=list("analysis", "means", "t-Test"))
        [...]
                        

Aquesta secció també és molt curta: rk.plugin.skeleton() no pot escriure una pàgina d'ajuda completa a partir de la informació que té. Però també pot explorar el document XML cercant elements que probablement mereixen una entrada de pàgina d'ajuda, i crear automàticament una plantilla de pàgines d'ajuda per al nostre connector. Tot el que hem de fer després és escriure algunes línies per a cada secció llistada.

Ara ve el pas final, en el qual lliurarem tots els objectes generats a rk.plugin.skeleton():

plugin.dir <- rk.plugin.skeleton("t-Test",
        xml=list(
                dialog=full.dialog,
                wizard=full.wizard),
        js=list(
                results.header="Two Variable t-Test",
                calculate=JS.calc,
                printout=JS.print),
        pluginmap=list(
                name="Two Variable t-Test",
                hierarchy=list("analysis", "means", "t-Test")),
        load=TRUE,
        edit=TRUE,
        show=TRUE)
                        

Els fitxers es crearan en un directori temporal predeterminat. Les últimes tres opcions no són necessàries, però són molt útils: load=TRUE afegirà automàticament el connector nou a la configuració del RKWard (ja que està en un directori temporal i, per tant, deixarà d'existir quan es tanqui el RKWard, s'eliminarà automàticament de nou pel RKWard durant l'inici següent), edit=TRUE obrirà tots els fitxers creats per a editar-los a les pestanyes de l'editor del RKWard, i show=TRUE intentarà llançar directament el connector, de manera que podreu examinar com es veu sense un clic. Podríeu considerar afegir overwrite=TRUE si executareu l'script repetidament (p. ex., després dels canvis al codi), ja que de manera predeterminada no se sobreescriuran fitxers.

L'objecte resultant «plugin.dir» conté el camí al directori on es va crear el connector. Això pot ser útil en combinació amb la funció rk.build.package(), per a construir un paquet R real per a compartir el vostre connector amb altres; p. ex., per enviant-lo a l'equip de desenvolupament del RKWard per a afegir-lo al nostre repositori de connectors.

Per a recapitular tot l'anterior, aquí hi ha l'script complet per a crear l'exemple de prova t que funciona. Afegint el codi ja explicat, també carrega el paquet si cal, i utilitza l'entorn local(), de manera que tots els objectes creats no acabaran a l'espai de treball actual (excepte el «plugin.dir»):

require(rkwarddev)

local({
        variables <- rk.XML.varselector(id.name="vars")
        var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE)
        var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE)
        test.hypothesis <- rk.XML.radio("using test hypothesis",
                options=list(
                        "Two-sided"=c(val="two.sided"),
                        "First is greater"=c(val="greater"),
                        "Second is greater"=c(val="less")
                )
        )
        check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
        basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))

        check.eqvar <- rk.XML.cbox("assume equal variances", value="1", un.value="0")
        conf.level <- rk.XML.spinbox("confidence level", min=0, max=1, initial=0.95)
        check.conf <- rk.XML.cbox("print confidence interval", val="1", chk=TRUE)
        conf.frame <- rk.XML.frame(conf.level, check.conf, rk.XML.stretch(), label="Confidence Interval")

        full.dialog <- rk.XML.dialog(
                label="Two Variable t-Test",
                rk.XML.tabbook(tabs=list("Basic settings"=basic.settings, "Options"=list(check.eqvar, conf.frame)))
        )

        full.wizard <- rk.XML.wizard(
                        label="Two Variable t-Test",
                        rk.XML.page(
                                rk.XML.text("As a first step, select the two variables you want to compare against
                                        each other. And specify, which one you theorize to be greater. Select two-sided,
                                        if your theory does not tell you, which variable is greater."),
                                rk.XML.copy(basic.settings)),
                        rk.XML.page(
                                rk.XML.text("Below are some advanced options. It is generally safe not to assume the
                                        variables have equal variances. An appropriate correction will be applied then.
                                        Choosing \"assume equal variances\" may increase test-strength, however."),
                                rk.XML.copy(check.eqvar),
                                rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
                                        the difference in means. Below you can specify whether one should be shown, and
                                        which confidence-level should be applied (95% corresponds to a 5% level of
                                        significance)."),
                                rk.XML.copy(conf.frame)))

        JS.calc <- rk.paste.JS(
                echo("res <- t.test (x=", var.x, ", y=", var.y, ", hypothesis=\"", test.hypothesis, "\""),
                js(
                        if(check.paired){
                        echo(", paired=TRUE")
                        },
                        if(!check.paired && check.eqvar){
                        echo(", var.equal=TRUE")
                        },
                        if(conf.level != "0.95"){
                        echo(", conf.level=", conf.level)
                        },
                        linebreaks=TRUE
                ),
                echo(")\n"), level=2)

        JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)

        plugin.dir <<- rk.plugin.skeleton("t-Test",
                xml=list(
                        dialog=full.dialog,
                        wizard=full.wizard),
                js=list(
                        results.header="Two Variable t-Test",
                        calculate=JS.calc,
                        printout=JS.print),
                pluginmap=list(
                        name="Two Variable t-Test",
                        hierarchy=list("analysis", "means", "t-Test")),
                load=TRUE,
                edit=TRUE,
                show=TRUE,
                overwrite=TRUE)
})