[rkward/work/generalized_preview] doc/rkwardplugins: Add documentation for output previews

[Thomas Friedrichsmeier]

Git commit 8cdfa65dd1b3d09aaecfe5c5bdad8041f7cedb40 by Thomas Friedrichsmeier.
Committed on 11/01/2016 at 14:17.
Pushed by tfry into branch 'work/generalized_preview'.

Add documentation for output previews

M  +39   -1    doc/rkwardplugins/index.docbook

http://commits.kde.org/rkward/8cdfa65dd1b3d09aaecfe5c5bdad8041f7cedb40

diff --git a/doc/rkwardplugins/index.docbook b/doc/rkwardplugins/index.docbook
index 2252f96..ba82f83 100644
--- a/doc/rkwardplugins/index.docbook
+++ b/doc/rkwardplugins/index.docbook
@@ -1331,7 +1331,7 @@ This chapter contains information on some topics that are useful only to certain
 	</sect2>
 	<sect2 id="preview_plots">
 		<title>Adding preview functionality</title>
-		<note><para>This section discusses adding preview functionality to plugins producing plots. There are separate sections on <link linkend="preview_data">previews of (imported) data</link>, or <link linkend="preview_custom">custom previews</link>. However, it is recommended that you read this section first, as the approach is similar in each case.</para></note>
+		<note><para>This section discusses adding preview functionality to plugins producing plots. There are separate sections on <link linkend="preview_output">previews of (HTML) output</link>, <link linkend="preview_data">previews of (imported) data</link>, and <link linkend="preview_custom">custom previews</link>. However, it is recommended that you read this section first, as the approach is similar in each case.</para></note>
 		<para>
 			A very useful feature for all plugins generating a plot/graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <command><preview></command> check box to your <link linkend="mainxml">GUI definition</link>, and adjusting the <link linkend="jstemplate">generated code</link> for the preview.
 		</para>
@@ -1443,6 +1443,44 @@ This chapter contains information on some topics that are useful only to certain
 	}
 		</programlisting>
 	</sect2>
+	<sect2 id="preview_output">
+		<title>Previews of (HTML) output</title>
+		<note><para>This section discusses adding preview functionality to plugins creating output / HTML printouts. It is recommended that you read the separate section on <link linkend="preview_plots">plot previews</link>, before this section.</para></note>
+		<para>
+			Creating a preview of HTML output is almost the same procedure as creating a plot preview. In this case, simply make sure that the <command>preview()</command> generates the relevant
+			<command>rk.print()/rk.results()</command> commands. It is generally a good idea to omit the header statements in the preview, however. Here is a stripped-down example:
+		</para>
+		<programlisting>
+	<!-- 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>>
+		</programlisting>
+		<para>
+			Note the specification of <parameter>mode="output"</parameter> in the <command><preview></command> element.
+		</para>
+		<programlisting>
+	// In the plugin's JS file
+	function preview () {
+		// generates the code used for preview
+		doPrintout (true);
+	}
+
+	function printout () {
+		// generates the code used for real
+		doPrintout (false);
+	}
+
+	function doPrintout (is_preview) {
+		if (!is_preview) {
+			new Header ("This is a caption").print ();
+		}
+		echo ('rk.print (result)');
+	}
+		</programlisting>
+	</sect2>
 	<sect2 id="preview_data">
 		<title>Previews of (imported) data</title>
 		<note><para>This section discusses adding preview functionality to plugins creating (importing) data. It is recommended that you read the separate section on <link linkend="preview_plots">plot previews</link>, before this section.</para></note>