[rkward-cvs] SF.net SVN: rkward:[3926] trunk/rkward/doc/rkwardplugins
m-eik at users.sourceforge.net
m-eik at users.sourceforge.net
Tue Oct 11 19:12:37 UTC 2011
Revision: 3926
http://rkward.svn.sourceforge.net/rkward/?rev=3926&view=rev
Author: m-eik
Date: 2011-10-11 19:12:37 +0000 (Tue, 11 Oct 2011)
Log Message:
-----------
updated screenshots and corrected the plugin docs
Modified Paths:
--------------
trunk/rkward/doc/rkwardplugins/index.docbook
trunk/rkward/doc/rkwardplugins/menu_hierarchy_example.png
trunk/rkward/doc/rkwardplugins/t_test_plugin_example.png
Modified: trunk/rkward/doc/rkwardplugins/index.docbook
===================================================================
--- trunk/rkward/doc/rkwardplugins/index.docbook 2011-10-11 17:23:06 UTC (rev 3925)
+++ trunk/rkward/doc/rkwardplugins/index.docbook 2011-10-11 19:12:37 UTC (rev 3926)
@@ -1571,6 +1571,8 @@
<sect1 id="rkdev_example"><title>Practical example</title>
<para>To get you an idea how <quote>scripting a plugin</quote> looks like, compared to the direct approach you have seen in the previous chapters, we'll create the full t-test plugin once again -- this time only with the R functions of the <quote>rkwarddev</quote> package.</para>
+ <tip><para>The package will add a new GUI dialog to RKWard in the <quote>File</quote> menu, called <quote>RKWard Plugin Skeleton</quote>. Like the name suggests, you can create plugin skeletons for further editing with it. This dialog itself was in turn generated by an <quote>rkwarddev</quote> script which you can find in the <quote>demo</quote> directory of the installed package and package sources, as an additional example. You can also run it by calling <function>demo("skeleton_dialog")</function></para></tip>
+
<sect2 id="rkdev_gui"><title>GUI description</title>
<para>You will imediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <document> definition, but directly with the plugin elements you'd like to have in the dialog. You can assign each interface element -- be it checkboxes, dropdown menus, variable slots or anything else -- to individual R objects, and then combine these objects to the actual GUI. The package has functions for <link linkend="interfaceelements">each XML tag</link> that can be used to define the plugin GUI, and most of them even have the same name, only with the prefix <quote>rk.XML.</quote>. For example, defining a <varselector> and two <varslot> elements for the <quote>x</quote> and <quote>y</quote> variable of the t-test example can be done by:</para>
<programlisting>
@@ -1589,7 +1591,7 @@
<programlisting>
<varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
</programlisting>
- <para>Some tags are only useful in the context of others. Therefore, for instance, you won't find a function for the <option> tag. Instead, both radio buttons and dropdown lists are defined including their options as a named list, where the names represent the labels to be shown in the dialog, and their value is a named vector which can have two entries, <quote>val</quote> for the value of an options and the boolean <quote>chk</quote> to specify if this options is checked by default.</para>
+ <para>Some tags are only useful in the context of others. Therefore, for instance, you won't find a function for the <option> tag. Instead, both radio buttons and dropdown lists are defined including their options as a named list, where the names represent the labels to be shown in the dialog, and their value is a named vector which can have two entries, <quote>val</quote> for the value of an option and the boolean <quote>chk</quote> to specify if this option is checked by default.</para>
<programlisting>
test.hypothesis <- rk.XML.radio("using test hypothesis",
options=list(
@@ -1607,7 +1609,7 @@
<option label="Second is greater" value="less" />
</radio>
</programlisting>
- <para>All that's missing from the elements of the <quote>Basic settings</quote> tab is the checkbox for paired samples, and the structuring of all of these elements in rows and column:</para>
+ <para>All that's missing from the elements of the <quote>Basic settings</quote> tab is the checkbox for paired samples, and the structuring of all of these elements in rows and columns:</para>
<programlisting>
check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))
@@ -1628,7 +1630,7 @@
</column>
</row>
</programlisting>
- <para>In a similar manner, the next lines will create R objects for the elements of the <quote>Options</quote> tab, introducing the functions for spinboxes, frames an stretch:</para>
+ <para>In a similar manner, the next lines will create R objects for the elements of the <quote>Options</quote> tab, introducing functions for spinboxes, frames and stretch:</para>
<programlisting>
check.eqvar <- rk.XML.cbox("assume equal variances", value="1", un.value="0")
conf.level <- rk.XML.spinbox("confidence level", min=0, max=1, initial=0.95)
@@ -1664,10 +1666,11 @@
<sect2 id="rkdev_jscode"><title>JavaScript code</title>
<para>Until now, using the <quote>rkwarddev</quote> package might not seem to have helped so much. This is going to change right now.</para>
<para>First of all, just like we didn't have to care about IDs for elements when defining the GUI layout, we don't have to care about JavaScript variable names in the next step. If you want more control, you can write plain JavaScript code and have it pasted to the generated file. But it's probably much more efficient to do it the <quote>rkwarddev</quote> way.</para>
- <para>Most notably you don't have to define any variable yourself, as <function>rk.plugin.skeleton()</function> can scan you XML code and automatically define all variables you will plobably need -- for instance, you wouldn't bother to include a checkbox if you don't use its value or state afterwards (btw, you can also scan existing XML files). So we can start writing the actual R code generating JS immediately.</para>
- <para>The package has some functions for JS code constructs that are commonly used in RKWard plugins, like the <function>echo()</function> function or <function>if() {...} else {...}</function> conditions. There are some differences between JS and R, e.g., <function>paste()</function> in R uses the comma to combine its parts, whereas <function>echo()</function> in JS uses <quote>+</quote>, and lines must end with a semicolon. By using the R functions, you can almost forget about these differences and keep writing R code.</para>
+ <para>Most notably you don't have to define any variable yourself, as <function>rk.plugin.skeleton()</function> can scan your XML code and automatically define all variables you will probably need -- for instance, you wouldn't bother to include a checkbox if you don't use its value or state afterwards. So we can start writing the actual R code generating JS immediately.</para>
+ <tip><para>The function <function>rk.JS.scan()</function> can also scan existing XML files for variables.</para></tip>
+ <para>The package has some functions for JS code constructs that are commonly used in RKWard plugins, like the <function>echo()</function> function or <function>if() {...} else {...}</function> conditions. There are some differences between JS and R, e.g., for <function>paste()</function> in R you use the comma to concatenate character strings, whereas for <function>echo()</function> in JS you use <quote>+</quote>, and lines must end with a semicolon. By using the R functions, you can almost forget about these differences and keep writing R code.</para>
<para>These functions can take different classes of input objects: Either plain text, R objects with XML code like above, or in turn results of some other JS functions of the package. In the end, you will allways call <function>rk.paste.JS()</function>, which behaves similar to <function>paste()</function>, but depending on the input objects it will replace them with their XML ID, JavaScript variable name or even complete JavaScript code blocks.</para>
- <para>For the t-test example, we need two JS objects: One to calculate the results, and one to print it in the <function>printout()</function> function:</para>
+ <para>For the t-test example, we need two JS objects: One to calculate the results, and one to print them in the <function>printout()</function> function:</para>
<programlisting>
JS.calc <- rk.paste.JS(
echo("res <- t.test (x=", var.x, ", y=", var.y, ", hypothesis=\"", test.hypothesis, "\""),
@@ -1678,8 +1681,8 @@
JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
</programlisting>
- <para>As you can see, <quote>rkwarddev</quote> also provides an R implementation of the <function>echo()</function> function. It returns exactly one character string with a valid JS version of itself. You might also notice that all of the R objects here are the ones we created earlier. They will automatically be replaced with their variable names, so this should be quite intuitive. Whenever you need just this replacement, the function <function>id()</function> can be used, which also will return exatly one character string from all the objects it was given.</para>
- <para>The function name <function>ite()</function> is an abbreviation for "if, then, else", and these three conditional statements are exactly what its three optional arguments are for. Maybe it's best to just look at the above <quote>JS.calc</quote> object, which now contains a character string with this content:</para>
+ <para>As you can see, <quote>rkwarddev</quote> also provides an R implementation of the <function>echo()</function> function. It returns exactly one character string with a valid JS version of itself. You might also notice that all of the R objects here are the ones we created earlier. They will automatically be replaced with their variable names, so this should be quite intuitive. Whenever you need just this replacement, the function <function>id()</function> can be used, which also will return exatly one character string from all the objects it was given (you could say it behaves like <function>paste()</function> with a very specific object substitution).</para>
+ <para>The function name <function>ite()</function> is an abbreviation for <quote>if, then, else</quote>, and these three conditional statements are exactly what its three optional arguments are for -- although our example only uses two, so we're dealing with three <quote>if, then</quote> conditions here. Maybe it's best to just look at the above <quote>JS.calc</quote> object, which now contains a character string with this content:</para>
<programlisting>
echo("res <- t.test (x=" + vrslCompare + ", y=" + vrslAgainst + ", hypothesis=\"" + radUsngtsth + "\"");
if(chcPardsmpl) {
@@ -1701,6 +1704,7 @@
<sect2 id="rkdev_rkh"><title>Help page</title>
<para>This section is very short as well: <function>rk.plugin.skeleton()</function> can't write a whole help page from the information it has. But it can scan the XML document also for elements which probably deserve a help page entry, and automatically create a help page template for our plugin. All we have to do afterwards is to write some lines for each listed section.</para>
+ <tip><para>The function <function>rk.rkh.scan()</function> can also scan existing XML files to create a help file skeleton.</para></tip>
</sect2>
<sect2 id="rkdev_plugin_generator"><title>Generate the plugin files</title>
@@ -1718,11 +1722,11 @@
edit=TRUE,
show=TRUE)
</programlisting>
- <para>The files will be created in a temporal directory by default. The last three options are not necessary, but very handy: <markup>load=TRUE</markup> will automatically add the new plugin to &kapp;s configuration (since it's in a temp dir, it wil also automatically be removed again after&kapp; was restarted), <markup>edit=TRUE</markup> will open all created files for editing in &kapp; editor tabs, and <markup>show=TRUE</markup> will attemt to directly launch the plugin, so you can expect what it looks like without a klick. You might consider adding <markup>overwrite=TRUE</markup> if you're about to run your script repeatedly (e.g. after changes to the code), as by default no files will be overwritten.</para>
- <para>The result object <quote>plugin.dir</quote> contains the path to the directory in which the plugin was created. This can be useful in combination with the function <function>rk.build.package()</function>, to build an actual R package to share your plugin with others.</para>
+ <para>The files will be created in a temporal directory by default. The last three options are not necessary, but very handy: <markup>load=TRUE</markup> will automatically add the new plugin to &kapp;s configuration (since it's in a temp dir and hence will cease to exist when &kapp; is closed, it will automatically be removed again by &kapp; during its next start), <markup>edit=TRUE</markup> will open all created files for editing in &kapp; editor tabs, and <markup>show=TRUE</markup> will attemt to directly launch the plugin, so you can examine what it looks like without a klick. You might consider adding <markup>overwrite=TRUE</markup> if you're about to run your script repeatedly (e.g. after changes to the code), as by default no files will be overwritten.</para>
+ <para>The result object <quote>plugin.dir</quote> contains the path to the directory in which the plugin was created. This can be useful in combination with the function <function>rk.build.package()</function>, to build an actual R package to share your plugin with others -- e.g. by sending it to the RKWard development team to be added to our plugin repository.</para>
</sect2>
<sect2 id="rkdev_ttest_script"><title>The full script</title>
- <para>So, to recapitulate all of the above, here's the full script to create the working t-test example. Adding to the already explained code, it also loads the package if needed, and it uses the <function>local()</function> environment, so all the objects will not be created in your global environment (except for <quote>plugin.dir</quote>):</para>
+ <para>To recapitulate all of the above, here's the full script to create the working t-test example. Adding to the already explained code, it also loads the package if needed, and it uses the <function>local()</function> environment, so all the objects will not be created in your global environment (except for <quote>plugin.dir</quote>):</para>
<programlisting>
require(rkwarddev)
Modified: trunk/rkward/doc/rkwardplugins/menu_hierarchy_example.png
===================================================================
(Binary files differ)
Modified: trunk/rkward/doc/rkwardplugins/t_test_plugin_example.png
===================================================================
(Binary files differ)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the rkward-tracker
mailing list