Previews for data, output and other results

Previews of (HTML) output

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)');
	}
		

Previews of (imported) data

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).

Custom previews

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.