Previews for data, output and other results

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

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

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.