Note
This section discusses adding preview functionality to plugins creating output / HTML printouts. It is recommended that you read the separate section on plot previews, before this section.
Creating a preview of HTML output is almost the same procedure as creating a plot preview. In this case, simply make sure that the preview() generates the relevant rk.print()/rk.results() commands. It is generally a good idea to omit the header statements in the preview, however. Here is a stripped-down example:
<!-- In the plugin's XML file -->> <dialog label="Import CSV data" > <browser id="file" type="file" label="File name"/> <!-- [...] -->> <preview id="preview" mode="output"/> </dialog>>
Note the specification of mode="output"
in the <preview> element.
// In the plugin's JS file function preview () { // generates the code used for preview printout (true); } function printout (is_preview) { // only generates a header if is_preview==false if (!is_preview) { new Header ("This is a caption").print (); } echo ('rk.print (result)'); }
Note
This section discusses adding preview functionality to plugins creating (importing) data. It is recommended that you read the separate section on plot previews, before this section.
Creating a preview of imported data (any type of data that rk.edit() can handle), is very similar to creating a plot preview. The following stripped down example should help illustrate how to create a data preview:
<!-- In the plugin's XML file -->> <dialog label="Import CSV data" > <browser id="file" type="file" label="File name"/> <!-- [...] -->> <preview id="preview" active="true" mode="data"/> </dialog>>
Note that the <preview> element specifies mode="data"
this time. active="true"
simply makes the preview active by
default.
// In the plugin's JS file function preview () { // generates the code used for preview calculate (true); } function calculate (is_preview) { echo ('imported <- read.csv (file="' + getString ("file") /* [+ options] */); if (is_preview) { echo ('preview_data <- imported\n'); } else { echo ('.GlobalEnv$' + getString ("name") + ' >- imported\n'); } } function printout () { // [...] }
Again, the preview() function generates almost the same R code as the calculate() function, so we create a helper function doCalcuate() to factor out the common parts. The most important thing to note is that you will have to assign the imported data to a object called
preview_data
(inside the current - local - environment). Everything else will happen automatically (roughly speaking, RKWard will call rk.edit(preview_data), wrapped inside a call to .rk.with.window.hints()).
Note
While previews are a great feature, they do consume resources. In the case of data previews, there may be cases, where previews can cause significant performance issues. This could be
for importing huge datasets (which are just too large to be opened for editing in RKWard's editor window), but also "normal" datasets could be mis-imported, creating a huge number of rows or columns. It is very much recommended that you limit the preview_data
to a dimension that provides a useful preview, without the danger of
creating noticable performance issues (e.g. 50 rows by 50 columns should be more than enough in most cases).
The <preview> element can be used to create previews for any type of "document" window that can be attached to RKWard's workplace. In addition to plots and data windows, this includes HTML files, R scripts, and object summary windows. For the latter ones, you will have to use <preview mode="custom">.
If you have read the sections describing plot preview and data previews, you should have a general idea on the procedure, but "custom" previews require slightly more manual work behind the scenes. The most important R function to look at is rk.assign.preview.data(), here. The following short listing shows what your generated (preview) R code could look like for a plugin creating a text file output:
## To be generated in the preview() code section of a plugin pdata <- rk.get.preview.data("SOMEID") if (is.null (pdata)) { outfile <- rk.get.tempfile.name(prefix="preview", extension=".txt") pdata <- list(filename=outfile, on.delete=function (id) { unlink(rk.get.preview.data(id)$filename) }) rk.assign.preview.data("SOMEID", pdata) } try ({ cat ("This is a test", pdata$filename) rk.edit.files(file=pdata$filename) })
Here you should get the value SOMEID
from the id
property of the <preview>-element. I.e. using getString ("preview.id") in the plugin's .js file.