IDs

If you have a closer look you can also see one of the packages’ automatic features: The node objects automatically received ID values, allthough we didn’t specify any. By default, allmost all functions supporting IDs have id.name="auto" set, which as we’ve seen will not cause the ID to become "auto", but a generated value. Usually an auto-ID is combined of the abbreviated node type and the abbreviated label given. So here, our <frame> node labelled »Example XML object« got the ID frm_ExmplXML. If we wanted a node to have some specific ID, we can use the id.name argument:

rk.XML.cbox(label="Check me!", id.name="specificID")

## <checkbox id="specificID" label="Check me!" value="true" />

Now, the fact that these nodes are actually objects of class XiMpLe.node gives us direct access to their attributes, including the ID:

myCheckbox <- rk.XML.cbox(label="Check me!")
XMLAttrs(myCheckbox)[["id"]]

## [1] "chc_Checkme"

Again, mere mortals probably won’t use this directly, but this makes it easy for functions read the IDs of XML nodes and use them. For example, if you wanted to define a varselector and a varslot, so the latter can take objects from the former, you need to give the varselector an ID and define that as the source in the varslot. If you wrote XML directly, you would give the source attribute the actual ID. With this package, you can do that too, but there is a much more elegant solution: Give the whole XML object and let the function extract the ID itself:

(myVarselector <- rk.XML.varselector(id.name="my_vars"))

## <varselector id="my_vars" />

(myVars <- rk.XML.varslot(label="Chose a variable", source=myVarselector))

## <varslot id="vrsl_Chosvrbl" label="Chose a variable" source="my_vars" />

So basically you define an XML object and then re-use this single object throughout your plugin script, be it for actual XML generation or, as in this case, only for getting its ID. This means, in other words, you can tell the varslot »take variables from this object«, you don’t have to worry about IDs at all. Just remember how you named an object and you can do all kinds of things with it.

This context dependent object handling will become even more useful when we get to the JavaScript part.

From single elements to a dialog

Once you have an idea which elements you would like to see in your dialog, and have also created individual XML objects of them, you finally have to put them all together to form the full dialog XML. This is done by rk.XML.dialog(), in the same manner that rk.XML.frame() was used. To get the layout into the desired structure, use rk.XML.row() and rk.XML.col() to group elements into rows and columns, as nested as you see fit:

(myDialog <- rk.XML.dialog(
    rk.XML.row(
        myVarselector,
        rk.XML.col(myVars, myFrame)
    ),
    label="Example dialog"
))

## <dialog label="Example dialog">
##  <row id="row_vCCEXMLEXM">
##      <varselector id="my_vars" />
##      <column id="clm_vCCEXMLEXM">
##          <varslot id="vrsl_Chosvrbl" label="Chose a variable" source="my_vars" />
##          <frame label="Example XML object" id="frm_ExmplXML">
##              <checkbox id="chc_Checkme" label="Check me!" value="true" />
##              <checkbox id="chc_Nocheckm" label="No, check me!!!" value="true" checked="true" />
##          </frame>
##      </column>
##  </row>
## </dialog>

Now, wouldn’t it be nice to see how that looks like in RKWard? Well, you can:

rk.plugin.skeleton(
    about="Example plugin",
    xml=list(dialog=myDialog),
    load=TRUE,
    show=TRUE
)

## For file names ‘Example plugin’ was renamed to ‘Exampleplugin’.
## Created directory /tmp/RtmpeP21pI/Exampleplugin.
## Created directory /tmp/RtmpeP21pI/Exampleplugin/R.
## Created directory /tmp/RtmpeP21pI/Exampleplugin/inst/rkward/plugins.
## Created directory /tmp/RtmpeP21pI/Exampleplugin/inst/rkward/tests/Exampleplugin.
## For filenames ‘Example plugin’ was renamed to ‘Exampleplugin’.
## For filenames ‘Example plugin’ was renamed to ‘Exampleplugin’.
## For filenames ‘Example plugin’ was renamed to ‘Exampleplugin’.
## For filenames ‘Example plugin’ was renamed to ‘Exampleplugin’.
## [1] "/tmp/Rtmp9gdThb/Exampleplugin"

Allthough until now all we did was to outline the XML description of our plugin-to-become, rkwarddev can already generate a full plugin. load=TRUE makes sure that RKWard recognizes the new plugin immediately after it was created, and show=TRUE will even make it pop up, too:

Not so bad for less than 20 short lines of code. This makes dialog design both very efficient and flexible: Imagine you want to re-arrange the order of elements, or experiment with completely different tabbook layouts, all you need to do is to change the rk.XML.dialog() call and run rk.plugin.skeleton() again (with overwrite=TRUE). If you don’t specify a directory explicitly, all will be written to a temporary directory. As seen in the example output, the return value of rk.plugin.skeleton() is allways the root directory of the created plugin.

Looking at the attribute xml=list(dialog=myDialog), we can assume that

1. there’s more than a dialog we can provide
   Further valid options are wizard, logic and snippets
2. there’s more to define than just the xml of a plugin
   Further arguments include js, pluginmap, rkh and components, among others

Of course, this plugin doesn’t really do anything useful. In fact, it doesn’t matter how you treat the buttons and boxes, the R code below won’t change a bit, because we didn’t provide any JavaScript code to deal with those events.

Defining variables

We just created the XML dialog, which in turn of course includes all the elements (and their IDs) we need to care about. Or the other way round: For each element in the dialog it is pretty safe to assume that it should have some effect on the outcome. So for a start, rkwarddev can »scan« the dialog object¹, collect all relevant IDs and define them as JavaScript variables automatically. Try this for a demonstration:

cat(rk.JS.scan(myDialog))

## 
##  var vrslChosvrbl = getValue("vrsl_Chosvrbl");
##  var chcCheckme = getValue("chc_Checkme");
##  var chcNocheckm = getValue("chc_Nocheckm");

Notice that only the varslot and both checkboxes show up – rk.JS.scan() distinguishes between relevant and irrelevant IDs, e.g. a row or column is no GUI element of interest here. By the way, if you defined the frame as checkable=TRUE, its ID would be extracted as well.

You might also notice that the JavaScript variable names differ from the XML IDs. For once, that way they’re harder to confuse with each other, and there’s also some conventions which characters are allowed. But to cut things short, we don’t have to worry about the variable names, just like we didn’t have to care about the XML IDs before. We don’t even have to call rk.JS.scan() ourselves, as rk.plugin.skeleton() will do so where appropriate, if the option scan includes "var", which by default is the case.

This means, once more we can concentrate on what the plugin shall actually do, perhaps some calculation of a kind.

Shortcut functions

The common task here is to check for certain dialog events (like unchecking the checkbox labelled »foo«), and then generate the according R code (like foo=FALSE). The question remains, if we don’t know the actual variable names, how can we check for events of certain dialog elements in the JavaScript code? The answer to that is: We generate the code using rkwarddev’s special JavaScripting functions and paste it with rk.paste.JS(). That way, we can use the created XML objects once again, as reference to which element we actually mean.

echo("# Value of the checkbox is: ", myCheckbox, "\n")

## [1] "echo(\"# Value of the checkbox is: \" + chcCheckme + \"\\n\");"

ite("foo", "bar", "baz")

##  if(foo) {
##      bar
##  } else {
##      baz
##  }

ite(myCheckbox,
    ite(myVars,
        echo("result <- ", myVars, "\n"),
        echo("# huh?\n")
    ),
    ite(myCheckbox2,
        echo("## ouch!\n")
    )
)

##  if(chcCheckme) {
##      if(vrslChosvrbl) {
##          echo("result <- " + vrslChosvrbl + "\n");
##      } else {
##          echo("# huh?\n");
##      }
##  } else if(chcNocheckm) {
##      echo("## ouch!\n");
##  }

cat(js(
    if(myCheckbox){
        if(myVars){
            echo("result <- ", myVars, "\n")
        } else {
            echo("# huh?\n")
        }
    } else if(myCheckbox2){
        echo("## ouch!\n")
    }
))

## if(chcCheckme) {
##      if(vrslChosvrbl) {
##          echo("result <- " + vrslChosvrbl + "\n");   
##      } else {
##          echo("# huh?\n");   
##      }   
##  } else if(chcNocheckm) {
##      echo("## ouch!\n"); 
##  }

mySpinbox <- rk.XML.spinbox(label="Set a value")
cat(js(
    if(myCheckbox == "true"){
        if(myVars){
            echo("result <- ", myVars, "\n")
        } else {
            echo("# huh?\n")
        }
    } else if(mySpinbox >= 0.3){
        echo("## a huge value!\n")
    }
))

## if(chcCheckme == "true") {
##      if(vrslChosvrbl) {
##          echo("result <- " + vrslChosvrbl + "\n");   
##      } else {
##          echo("# huh?\n");   
##      }   
##  } else if(spnSetavalu >= 0.3) {
##      echo("## a huge value!\n"); 
##  }

myCalculation <- rk.paste.JS(js(
    if(myCheckbox){
        if(myVars){
            echo("result <- ", myVars, "\n")
        } else {
            echo("# huh?\n")
        }
    } else if(myCheckbox2){
        echo("## ouch!\n")
    }
))
rk.plugin.skeleton(
    about="Example plugin",
    xml=list(dialog=myDialog),
    js=list(calculate=myCalculation),
    load=TRUE,
    show=TRUE,
    overwrite=TRUE
)

## For file names ‘Example plugin’ was renamed to ‘Exampleplugin’.
## For file names ‘Example plugin’ was renamed to ‘Exampleplugin’.
## For file names ‘Example plugin’ was renamed to ‘Exampleplugin’.
## For file names ‘Example plugin’ was renamed to ‘Exampleplugin’.
## For file names ‘Example plugin’ was renamed to ‘Exampleplugin’.
## [1] "/tmp/Rtmpk8Onz5/Exampleplugin"
## Warnmeldung:
## tests: Skipping existing file /tmp/Rtmpk8Onz5/Exampleplugin/inst/rkward/tests/testsuite.R. 

Summary and usage sections

For those global sections (as well as for links, technical information etc.), the package has designated functions:

(mySummary <- rk.rkh.summary("Perform some cool anaylsis."))

## <summary>
##  Perform some cool anaylsis.
## </summary>

(myUsage <- rk.rkh.usage("Check some boxes to add your data ..."))

## <usage>
##  Check some boxes to add your data ...
## </usage>

Help on GUI elements

Helpful information on individual GUI elements are added directly to the element definition. Think of it as some kind of literate programming, since the documentation becomes part of the code, so hopefully you don’t forget to change it if you change your code:

mySpinbox <- rk.XML.spinbox(
    label="Set a value",
    help="If you spin this, the result will change.",
    component="Value setters"
)

The help argument must be used in combination with the component of your plugin where this element belongs to. Both is not being added to the XML code or even the resulting object, but to an internal environment of the running R session, where rkwarddev will look for it when help pages are being build. In case you need to check its value, you might use the appropriate getter function:

rk.get.rkh.prompter(component="Value setters", id=mySpinbox)

## $help
## [1] "If you spin this, the result will change."

In the end, you can add all of the help stuff to your plugin. The information you added to the XML objects is automatically detected and fetched if you keep "rkh" in the scan option of rk.plugin.skeleton(), which by default is the case. Global help objects must be given as a named list to its rkh option:

rk.plugin.skeleton(
    about="Example plugin",
    xml=list(
        dialog=myDialog
    ),
    js=list(
        calculate=myCalculation
    ),
    rkh=list(
        summary=mySummary,
        usage=myUsage
    ),
    load=TRUE,
    show=TRUE,
    overwrite=TRUE
)

Now the plugin has a working Help button which opens a page in the help browser: