http://docs.kde.org/
Prev Next

Chapter 5. Generating R code from GUI settings

Table of Contents

Using JavaScript in RKWard plugins
preprocess()
calculate()
printout()
Conventions, policies, and background
Understanding the local() environment
Code formatting
Dealing with complex options
Tips and tricks

Using JavaScript in RKWard plugins

Now we have a GUI defined, but we still need to generate some R code from that. For that, we need another text file, code.js, located in the same directory as the description.xml. You may or may not be familiar with JavaScript (or, to be technically precise: ECMA-script). Documentation on JS can be found in abundance, both in printed form, and on the Internet (e.g.: https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide). But for most purposes you will not need to know much about JS at all, as we will only use some very basic features.

Tip

After reading this chapter, have a look at the rkwarddev package as well. It provides some R functions to create JavaScript code commonly used in RKWard. It can also autodetect variables used in a plugin XML file and create basic JavaScript code from that for you to start with.

Note

Plugin .js files are assumed to be UTF-8 encoded. Be sure to check you editor's encoding, if using any non-ascii characters.

For the two variable t-test, the code.js file looks as follows (with comments in between):

preprocess()

function preprocess () {
}

The JS file is organized into three separate functions: preprocess(), calculate(), and printout(). This is because not all code is needed at all stages. Currently the preprocess-function is not really used in many places (typically you will omit it altogether).

calculate()

function calculate () {
	echo ('res <- t.test (x=' + getString ("x") + ', y=' + getString ("y") + ', hypothesis="' + getString ("hypothesis") + '"' + getString ("varequal"));
	var conflevel = getString ("conflevel");
	if (conflevel != "0.95") echo (', conf.level=' + conflevel);
	echo (')\n');
}

This function generates the actual R syntax to be run from the GUI settings. Let's look at this in detail: The code to be used is generated using echo() statement. Looking at the echo() statement step by step, the first part of it is 

res <- t.test (

as plain text. Next we need to fill in the value, the user selected as the first variable. We fetch this using getString ("x"), and append it to the string to be “echoed”. This prints out the value of the GUI-element with id="x": our first <checkbox>. Next, we append a ', ', and do the same to fetch the value of the element "y" - the second <checkbox>. For the hypothesis (the <radio> group), and the equal variances <checkbox>, the procedure is very similar.

Note that instead of concatenating the output snippets with “+”, you can also use several echo() statements. Everything is printed on a single line. To produce a line break in the generated code, insert a "\n" in the echoed string. In theory, you can even produce many lines with a single echo-statement, but please keep it to one line (or less) of generated code per echo().

Note

Besides getString(), there are also functions getBoolean(), which will try to return the value as a logical (suitable for using in an if()-statement), and getList(), which will try to return list-like data in a JS Array(). We will show examples of those, later.

When looking at existing plugins, you will also find plenty of plugins using getValue(), instead of getString(), and in fact the two are almost identical. However using getString(), getBoolean() and getList() is the recommended practice since version 0.6.1.

It gets a little more tricky for the confidence level. For reasons of aesthetics, we do not want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value unconditionally, we first fetch into a variable. Then we check, whether that variable differs from "0.95" and if so print out an additional argument. Finally, we echo a closing bracket and a line break: ")\n". That is all for the calculate function.

printout()

function printout () {
	echo ('rk.header (' + i18n ("Two Variable t-Test") + ')\n');
	echo ('rk.print (res)\n');
}

And this was all there is to the printout function in most cases. rk.header() prints a standard headline for the results. Note that in the .js files, you have to mark up all translatable strings by hand, using i18n(), or some alternative commands. More on this in the chapter on internationalization. You can also add some more information to this, if you like, e.g.: 

function printout () {
	new Header (i18n ("Two Variable t-Test"))
	          .addFromUI ("varequal")
	          .add (i18n ("Confidence level"), getString ("conflevel"))  // Note: written like this for illustration purposes. More automatic:
	//        .addFromUI ("conflevel")
	          .print ();
echo ('rk.print (res)\n');
}

rk.print() utilizes the R2HTML package to provide HTML formatted output. Another helpful function is rk.results(), which can also output different kinds of result tables. If in doubt, however, just use rk.print(), and be done with. The JS class Header is a JS level helper to generate a call to rk.header() (just take a look at the generated R code). In some cases you may want to call echo ('rk.header (...)') directly to print a header for your output.

Note that internally, the output is just a plain HTML document at this point of time. Therefore you might be tempted to add custom HTML using rk.cat.output(). While this will work, please do not do this. The output format may change (e.g. to ODF) in the future, so it is best not to introduce HTML specific code. Rather keep things simple with rk.header(), rk.print(), rk.results(), and -- if needed -- rk.print.literal(). If those do not seem to satisfy your formatting needs, contact us on the mailing list for help.

Congratulations! You created your first plugin. Read on in the next chapters for more advanced concepts.