[rkward-cvs] SF.net SVN: rkward: [2237] branches/KDE4_port/doc
tfry at users.sourceforge.net
tfry at users.sourceforge.net
Sun Nov 18 18:32:15 UTC 2007
Revision: 2237
http://rkward.svn.sourceforge.net/rkward/?rev=2237&view=rev
Author: tfry
Date: 2007-11-18 10:32:15 -0800 (Sun, 18 Nov 2007)
Log Message:
-----------
Correctly install handbooks (I think)
Modified Paths:
--------------
branches/KDE4_port/doc/CMakeLists.txt
Added Paths:
-----------
branches/KDE4_port/doc/rkward/
branches/KDE4_port/doc/rkward/CMakeLists.txt
branches/KDE4_port/doc/rkward/writing_plugins_introduction.docbook
Removed Paths:
-------------
branches/KDE4_port/doc/en/
branches/KDE4_port/doc/rkward/CMakeLists.txt
branches/KDE4_port/doc/rkward/writing_plugins_introduction.docbook
Modified: branches/KDE4_port/doc/CMakeLists.txt
===================================================================
--- branches/KDE4_port/doc/CMakeLists.txt 2007-11-18 18:12:43 UTC (rev 2236)
+++ branches/KDE4_port/doc/CMakeLists.txt 2007-11-18 18:32:15 UTC (rev 2237)
@@ -1,3 +1,2 @@
-ADD_SUBDIRECTORY( en )
+ADD_SUBDIRECTORY (rkward)
-INCLUDE_DIRECTORIES( ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR} ${KDE4_INCLUDE_DIR} ${QT_INCLUDES} )
Copied: branches/KDE4_port/doc/rkward (from rev 2136, branches/KDE4_port/doc/en)
Deleted: branches/KDE4_port/doc/rkward/CMakeLists.txt
===================================================================
--- branches/KDE4_port/doc/en/CMakeLists.txt 2007-10-28 18:03:33 UTC (rev 2136)
+++ branches/KDE4_port/doc/rkward/CMakeLists.txt 2007-11-18 18:32:15 UTC (rev 2237)
@@ -1,16 +0,0 @@
-INCLUDE_DIRECTORIES( ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR} ${KDE4_INCLUDE_DIR} ${QT_INCLUDES} )
-
-
-########### install files ###############
-
-
-
-
-#original Makefile.am contents follow:
-
-#EXTRA_DIST = index.docbook writing_plugins_introduction.docbook menu_hierarchy_example.png \
-# t_test_plugin_example.png
-#
-#KDE_LANG = en
-#KDE_DOCS = rkward
-#
Copied: branches/KDE4_port/doc/rkward/CMakeLists.txt (from rev 2212, branches/KDE4_port/doc/en/CMakeLists.txt)
===================================================================
--- branches/KDE4_port/doc/rkward/CMakeLists.txt (rev 0)
+++ branches/KDE4_port/doc/rkward/CMakeLists.txt 2007-11-18 18:32:15 UTC (rev 2237)
@@ -0,0 +1 @@
+KDE4_CREATE_HANDBOOK (index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en)
Deleted: branches/KDE4_port/doc/rkward/writing_plugins_introduction.docbook
===================================================================
--- branches/KDE4_port/doc/en/writing_plugins_introduction.docbook 2007-10-28 18:03:33 UTC (rev 2136)
+++ branches/KDE4_port/doc/rkward/writing_plugins_introduction.docbook 2007-11-18 18:32:15 UTC (rev 2237)
@@ -1,2422 +0,0 @@
-<?xml version="1.0" ?>
-<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
- <!ENTITY rkward '<application>RKWard</application>'>
- <!ENTITY kapp "&rkward;"><!-- replace rkward here -->
- <!ENTITY % addindex "IGNORE">
- <!ENTITY % English "INCLUDE"><!-- change language only here -->
-
-
- <!-- Do not define any other entities; instead, use the entities
- from kde-genent.entities and $LANG/user.entities. -->
-]>
-
-<book lang="&language;">
-
-<!-- This header contains all of the meta-information for the document such
-as Authors, publish date, the abstract, and Keywords -->
-
-<bookinfo>
-<title>Introduction to Writing Plugins for RKWard</title>
-
-<authorgroup>
-<author>
-<firstname>Thomas</firstname>
-<surname>Friedrichsmeier</surname>
-<affiliation>
-<address><email>tfry AT users DOT sourceforge DOT net</email></address>
-</affiliation>
-</author>
-<!-- Additional authors go here -->
-</authorgroup>
-
-<!-- TRANS:ROLES_OF_TRANSLATORS -->
-
-<copyright>
-<year>2006</year>
-<year>2007</year>
-<holder>Thomas Friedrichsmeier</holder>
-</copyright>
-<!-- Translators: put here the copyright notice of the translation -->
-<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
- and in the FDL itself on how to use it. -->
-<legalnotice>&FDLNotice;</legalnotice>
-
-<date>2007-05-09</date>
-<releaseinfo>0.4.8.00</releaseinfo>
-
-<abstract>
-<para>
-This is a guide to writing plugins for &rkward;.
-</para>
-</abstract>
-
-<keywordset>
-<keyword>KDE</keyword>
-<keyword>R</keyword>
-<keyword>rkward</keyword>
-<keyword>plugins</keyword>
-</keywordset>
-
-</bookinfo>
-
-<chapter id="introduction">
-<title>Introduction</title>
-
-<para>
-Documentation as of &kapp; release 0.4.8.
-</para>
-<para>
-This document describes how to write your own plugins. Note, that at the time of this writing, none of the concepts are set it stone. Therefore, this document should be regarded as an introduction to the current approach, and as a basis for discussion. All sorts of comments are welcome.
-</para>
-<para>
-For questions and comments, please write to the &kapp; development mailing list.
-</para>
-<para>
-<emphasis>You do not need to read this in order to use &kapp;.</emphasis> This document is about extending &kapp;. It is targeted at advanced users, or people willing to help improve &kapp;.
-</para>
-<para>
-Writing a standard plugin is basically a four-step process:
-<itemizedlist>
-<listitem><link linkend="pluginmap">Placing a new Action in the menu-hierarchy</link></listitem>
-<listitem><link linkend="mainxml">Describing the looks and behavior of the plugin-GUI</link></listitem>
-<listitem><link linkend="phptemplate">Defining, how R-code is to be generated from the settings, the user makes in the GUI</link></listitem>
-<listitem><link linkend="pluginhelp">Adding a help page to your plugin</link></listitem>
-</itemizedlist>
-Those will be dealt with in turn.
-</para>
-<para>
-Some advanced concepts may be used in those four steps, but are dealt with in separate chapters, to keep things simple:
-<itemizedlist>
-<listitem><link linkend="logic">GUI logic</link></listitem>
-<listitem><link linkend="embedding">Embedding Plugins into Plugins</link></listitem>
-<listitem><link linkend="plugin_series">Useful concepts for creating many series of similar plugins</link></listitem>
-</itemizedlist>
-</para>
-<para>
-Also, none of the chapters shows all options, but rather only the basic concepts. A complete <link linkend="reference">reference</link> of options is provided separately.
-</para>
-</chapter>
-
-<chapter id="whatareplugins">
-<title>Preliminaries: What are plugins in &kapp;? How do they work?</title>
-<para>
-Of course the first question you might have is: What portions of &kapp; functionality is realized using plugins? Or: What can plugins do?
-</para>
-<para>
-One way to answer this is: Deselect all .pluginmap-files under Settings->Configure &kapp;->Plugins, and see what's missing. A slightly more helpful answer: Most actual statistics functions accessible via the GUI are realized using plugins. Also, you can create fairly flexible GUIs for all kinds of operations using plugins.
-</para>
-<para>
-The basic paradigm behind &kapp; plugins is the one we'll walk you through in this document: An xml-file describes what the GUI looks like. An additional PHP-file is used to generate R syntax from the GUI settings. That is, plugins do not really have to perform any statistical calculations. Rather plugins generate the R syntax needed to run those calculations. The R syntax is then sent to the R backend for evaluation, and typically a result is shown in the output window.
-</para>
-<para>
-Read on in the next chapters to see how this is done.
-</para>
-</chapter>
-
-<chapter id="pluginmap">
-<title>Creating menu entries</title>
-<para>
-When you create a new plugin, you need to tell &kapp; about it. So the first thing to do, is to write a .pluginmap-file (or modify an existing one). The format of .pluginmap is XML. I'll walk you through an example (also of course, be sure you have &kapp; configured to load your pluginmap – Settings->Configure &kapp;->Plugins):
-</para>
-<programlisting>
-<!DOCTYPE rkpluginmap>
-</programlisting>
-<para>
-The doctype is not really interpreted, but set it to "rkpluginmap" anyway.
-</para>
-<programlisting>
-<document base_prefix="" namespace="rkward">
-</programlisting>
-<para>
-The "base_prefix"-attribute can be used, if all your plugins reside in a common directory. Basically, then, you can omit that directory from the filenames specified below. As you will see below, all plugins get a unique identifier. The "namespace" is a way to organize those ids, and make it less likely to create a duplicate identifier accidentally. Internally, basically the namespace and then a "::" gets prepended to all the identifiers you specify below. If unsure, leave these at "" and "rkward".
-</para>
-<programlisting>
- <components>
-</programlisting>
-<para>
-Components? Aren't we talking about plugins? Yes, but in the future, plugins will be no more than a special class of components. What we do here, then, is to register all components/plugins with &kapp;. Let's look at an example entry:
-</para>
-<programlisting>
- <component type="standard" id="independent_samples_t_test" file="means/ttests/independent_samples.xml" label="Independent Samples" />
-</programlisting>
-<para>
-First the "type"-attribute: Leave this to "standard" for now. Further types are not yet implemented. The "id" I've already hinted at. Each component has to be given a unique (in its namespace) identifier. Pick one that is easily recognizable. Avoid spaces and any special characters. Those are not banned, so far, but might have special meanings. With the "file" attribute, you specify where the <link linkend="mainxml">description of the actual plugin itself</link> is located. This is relative to the directory the .pluginmap-file is in, and the "base_prefix" above. Finally, give the component a label. This label will be shown whereever the plugin is placed in the menu (or in the future perhaps in other places as well).
-</para>
-<para>
-Typically a .pluginmap-file will contain several components, so here are a few more:
-</para>
-<programlisting>
- <component type="standard" id="unimplemented_test" file="means/unimplemented.xml" />
- <component type="standard" id="fictional_t_test" file="means/ttests/fictional.xml" label="This is a fictional t-test" />
- <component type="standard" id="descriptive" file="descriptive.xml" label="Descriptive Statistics" />
- <component type="standard" id="corr_matrix" file="corr_matrix.xml" label="Correlation Matrix" />
- <component type="standard" id="simple_anova" file="simple_anova.xml" label="Simple Anova" />
- </components>
-</programlisting>
-<para>
-Ok, this was the first step. &kapp; now knows those plugins exist. But how to invoke them? They need to be placed in a menu-hierarchy:
-</para>
-<programlisting>
- <hierarchy>
- <menu id="analysis" label="Analysis" index="4">
-</programlisting>
-<para>
-Right below the <hierarchy>-tag, you start describing, in which menu, your plugins should go. With the above line, you basically say, that your plugin should be in the "Analysis" menu (not necessarily directly there, but in a submenu). The "Analysis" menu is standard in &kapp;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the "label"-attribute you'd give it its name. The "index" attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
-Finally, the "id" once again identifies this menu. This is needed, so several .pluginmap-files can place their plugins in the same menus. They do this by looking for a menu with the given "id". If the id does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu.
-</para>
-<programlisting>
- <menu id="means" label="Means" index="1">
-</programlisting>
-<para>
-Basically the same thing here: Now we define a submenu to the "Analysis"-menu. It is to be called "Means".
-</para>
-<programlisting>
- <menu id="ttests" label="T-Tests">
-</programlisting>
-<para>
-And a final level in the menu-hierarchy: A sub-menu of the sub-menu "Means". Note, that if you omit the "index" parameter, the new entry will be placed below any already existing ones.
-</para>
-<programlisting>
- <entry component="independent_samples_t_test" />
-</programlisting>
-<para>
-Now, finally, this is the menu, we want to place the plugin in. The <entry>-tag signals, this actually is the real thing, instead of another submenu. The "component"-attribute refers to the "id" you gave the plugin/component above.
-</para>
-<programlisting>
- <entry component="fictional_t_test" />
- </menu>
- <entry component="fictional_t_test" />
- </menu>
- <menu id="frequency" label="Frequency" index="2"/>
-</programlisting>
-<para>
-In case you have lost track: This is another submenu to the "Analysis" menu. See the screenshot below. We'll skip some of what's not visible, marked with [...].
-</para>
-<programlisting>
- [...]
- </menu>
- <entry component="corr_matrix" index="4"/>
- <entry component="descriptive" index="3"/>
- <entry component="simple_anova" index="5"/>
- </menu>
-</programlisting>
-<para>
-These are the final entries visible in the screenshots below. Note, that you don't need to define the entries in the order they should have in the menu. Use the "index"-attribute instead.
-</para>
-<programlisting>
- <menu id="plots" label="Plots" index="5">
- [...]
- </menu>
-</programlisting>
-<para>
-Of course you can also place your plugins in menus other than "Analysis".
-</para>
-<programlisting>
- <menu id="file" label="File" index="0">
- [...]
- </menu>
-</programlisting>
-<para>
-Even in standard-menus such as "File". All you need is the correct "id".
-</para>
-<programlisting>
- </hierarchy>
-</document>
-</programlisting>
-<para>
-That's how to do it. And this screenshot shows the result:
-</para>
-<screenshot>
-<screeninfo>Menu hierarchy created by the code shown above</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="menu_hierarchy_example.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Menu hierarchy created by the code shown above</phrase>
- </textobject>
- </mediaobject>
-</screenshot>
-<para>
-Confused? The easiest way to get started is probably taking some of the existing .pluginmap files shipped with the distribution, and modifying them to your needs. Also, if you need help, don't hesitate to write to the development mailing list.
-</para>
-</chapter>
-
-<chapter id="mainxml">
-<title>Defining the GUI</title>
-<para>
-In the <link linked="pluginmap">previous chapter</link> you've seen how to register a plugin with &kapp;. The most important ingredient was specifying the path to an XML file with a description of what the plugin actually looks like. In this chapter you'll learn how to create this XML file.
-</para>
-<para>
-Once again we'll walk you through an example. The example is a (slightly simplified) version of the independent samples t-test.
-</para>
-<programlisting>
-<!DOCTYPE rkplugin>
-</programlisting>
-<para>
-The doctype is not really interpreted, yet. Set it to rkplugin, anyway.
-</para>
-<programlisting>
-<document>
- <code file="t_test.php"/>
-</programlisting>
-<para>
-All plugins generate some code. Currently the only way to do so is using PHP, as detailed in <link linkend="phptemplate">the next chapter</link>. This defines, where to look for the PHP-code. The filename is relative to the directory the plugin-xml is in.
-</para>
-<programlisting>
- <help file="t_test.rkh"/>
-</programlisting>
-<para>
-It is usually a good idea to also provide a help page for your plugin. The filename of that help page is given, here, relative to the directory, the plugin-xml is in. Writing help pages is documented <link linkend="pluginhelp">here</link>. If you do not provide a help file, omit this line.
-</para>
-<programlisting>
- <dialog label="Independent Samples T-Test">
-</programlisting>
-<para>
-As you know, plugins may have either a dialog or a wizard-interface or both. Here we start definining a dialog-interface. the label-attribute specifies the caption of the dialog.
-</para>
-<programlisting>
- <tabbook>
- <tab label="Basic settings">
-</programlisting>
-<para>
-GUI-elements can be organized using a tabbook. Here we define a tabbook as the first element in the dialog. Use <tabbook>[...]</tabbook> to define the tabbook and then for each page in the tabbook use <tab>[...]</tab>. The "label"-attribute in the <tab>-element allows you to specify a caption for that page of the tabbook.
-</para>
-<programlisting>
- <row id="main_settings_row">
-</programlisting>
-<para>
-The <row> and <column> tags specify the layout of the GUI elements. Here you say, that you'd like to place some elements side-by-side (left to right). The "id"-attribute is not strictly necessary, but we'll use it later on, when adding a wizard interface to our plugin. The first element to place in the row, is:
-</para>
-<programlisting>
- <varselector id="vars"/>
-</programlisting>
-<para>
-Using this simple tag you create a list from which the user can select variables. You have to specify an id for this element, so RKWard knows how to find it. Note that you may NOT use a dot (.) in the "id" string.
-</para>
-<programlisting>
- <column>
-</programlisting>
-<para>
-Next, we nest a <column> inside the row. I.e. the following elements will be place above each other (top-to-bottom), and all will be to the right of the <varselector>.
-</para>
-<programlisting>
- <varslot type="numeric" id="x" source="vars" required="true" label="compare"/>
- <varslot type="numeric" id="y" source="vars" required="true" label="against"/>
-</programlisting>
-<para>
-These elements are the counterpart to the <varselector>. They represent "slots" into which the user can put variables. You will note that the "source" is set to the same value as the "id" of the <varselector>. This means, the <varslot>s will each take their variables from the varselector. The <varslot>s also have to be given an "id". They may have a label, and they may be set to "required". This means that the submit-button will not be enabled until the <varslot> holds a valid value. Finally the "type"-attribute is not interpreted, yet, but it will be used to take care that only the correct types of variables will be allowed in the <varslot>.
-</para>
-<programlisting>
- <radio id="hypothesis" label="using test hypothesis">
- <option value="two.sided" label="Two-sided"/>
- <option value="greater" label="First is greater"/>
- <option value="less" label="Second is greater"/>
- </radio>
-</programlisting>
-<para>
-Here, you define a group of <radio>-exclusive buttons. The group has a "label" and an "id". Each <option> (button) has a label and is assigned a value. This is the value the <radio>-element will return when the option is selected.
-</para>
-<programlisting>
- </column>
- </row>
- </tab>
-</programlisting>
-<para>
-Each tag has to be closed. We've put all the elements we wanted (the two <varslots> and the <radio>) in the <column>. We put all elements we wanted (the <varselector> and the <column> with those elements) in the <row>. And we've put all the elements we wanted into the first page in the <tabbook>. We're not yet done defining the <tabbook> (more pages to come) and of course there's more to come in the <dialog>, too. But this screenshot is basically what we've done so far:
-</para>
-<screenshot>
-<screeninfo>T test plugin</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="t_test_plugin_example.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>T test plugin</phrase>
- </textobject>
- </mediaobject>
-</screenshot>
-<para>
-Note that we have not specified the "Submit", "Close", etc. buttons or the code-view. Those elements get generated automatically. But of course we still have to define the second page of the <tabbook>:
-</para>
-<programlisting>
- <tab label="Options">
- <checkbox id="varequal" label="assume equal variances" value=", var.equal=TRUE"/>
-</programlisting>
-<para>
-By default elements will be placed top-to-bottom like in a <column>. Since that is what we want here, we don't have to explicitly state a <row> or <column>-layout. The first element we define is a checkbox. Just like the <radio><option>s, the checkbox has a "label" and a "value". The "value" is what gets returned, if the checkbox is checked. Of course the checkbox also needs an "id".
-</para>
-<programlisting>
- <frame label="Confidence Interval" id="frame_conf_int">
-</programlisting>
-<para>
-Here's yet another layout-element: In order to signal that the two elements below belong together, we draw a <frame> (box). That frame may have a caption. Since the frame is just a passive layout-element, it does not need an "id", we still define one, here, as we'll refer to it later, when defining an additional wizard interface.
-</para>
-<programlisting>
- <checkbox id="confint" label="print confidence interval" value="1" checked="true"/>
- <spinbox type="real" id="conflevel" label="confidence level" min="0" max="1" initial="0.95"/>
- </frame>
-</programlisting>
-<para>
-Inside the <frame> we place another <checkbox> (using checked="true", we signal that checkbox should be checked by default), and a <spinbox>. The spinbox allows the user to select a value between "min" and "max" with the default/initial value "0.95". Setting the "type" to "real" signals that real numbers are accepted as opposed to type="integer" which would accept integers only.
-</para>
-<programlisting>
- </tab>
- </tabbook>
- </dialog>
-</programlisting>
-<para>
-That's all for the second page of the <tabbook>, all pages in the <tabbook> and all elements in the <dialog>. We're finished defining what the dialog looks like.
-</para>
-<programlisting>
-</document>
-</programlisting>
-<para>
-Finally we close the <document>-tag, and that's it. The GUI is defined. You can save the file now.
-But how does R-syntax get generated from the GUI-settings? I'll deal with that in the <link linkend="phptemplate">next chapter</link>. First, however, we'll look into adding a wizard interface, and some general considerations.
-</para>
-
-<section id="wizard_interface">
- <title>Adding a wizard interface</title>
- <para>
- Actually we don't have to define an additional <wizard>-interface, but here's how that would be done. To add a wizard interface, you'll add a <wizard> tag at the same level as the <dialog> tag:
- </para>
- <programlisting>
- <wizard label="Independent Samples T-Test">
- <page id="firstpage">
- <text>As a first step, select the two variables you want to compare against each other. And specify, which one you theorize to be greater. Select two-sided, if your theory does not tell you, which variable is greater.</text>
- <copy id="main_settings_row/>
- </page>
- </programlisting>
- <para>
- Some of this is pretty self explanatory: We add a <wizard> tag with a label for the wizard. Since a wizard can hold several pages that are shown one after another, we next define the first page, and put an explanatory text note in there. Then we use a <copy>-tag. What this does, is really it saves us having to define yet again, what we already wrote for the <dialog>: The copy tag looks for another tag with the same "id" earlier in the .xml. This happens to be defined in the <dialog> section, and is a <row> in which there are the <varselector>, <varslots> and the "hypothesis" <radio>-control. All of this is copied 1:1 and inserted right at the <copy> element.
- </para>
- <para>
- Now to the second page:
- </para>
- <programlisting>
- <page id="secondpage">
- <text>Below are some advanced options. It's generally safe not to assume the variables have equal variances. An appropriate correction will be applied then. Chosing "assume equal variances" may increase test-strength, however.</text>
- <copy id="varequal"/>
- <text>Sometimes it's helpful to get an estimate of the confidence interval of the difference in means. Below you can specify whether one should be shown, and which confidence-level should be applied (95% corresponds to a 5% level of significance).</text>
- <copy id="frame_conf_int"/>
- </page>
- </wizard>
- </programlisting>
- <para>
- Much of the same thing here. We add some texts, and in between that <copy> further sections from the dialog interface.
- </para>
- <para>
- You may of course make the wizard-interface look very different to the plain dialog, and not use the <copy> tag at all. Be sure, however, to assign corresponding elements the same "id" in both interfaces. This is not only used to transfer settings from the dialog-interface to the wizard-interface and back, when the user switches interfaces (which does not yet happen in the current version of RKWard), but also simplifies writing your code-template (see below).
- </para>
-</section>
-
-<section id="mainxmltips">
- <title>Some considerations on GUI design</title>
- <para>
- This section contains some general considerations on which GUI elements to use where. If this is your first attempt of creating a plugin, feel free to skip over this section, as it isn't relevant to getting a basic GUI working. Come back here, later, to see, whether you can refine your plugin's GUI in some way or another.
- </para>
-
- <section id="radio_vs_checkbox_vs_dropdown">
- <title><radio> vs. <checkbox> vs. <dropdown></title>
- <para>
- The three elements <radio>, <checkbox>, <dropdown>, all serve a similar function: To select one out of several options. Obviously, a checkbox only allows to chose between two options: checked or not checked, so you can't use it, if there are more than two options to chose from. But when to use which of the elements? Some rules of thumb:
- </para>
- <para>
- If you find yourself creating a <radio> or <dropdown> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between "adjust results" and "do not adjust results", or between "remove missing values" and "keep missing values". In this case a <checkbox> is the best choice: It uses little space, will have the least words of labels, and is easiest to read for the user. There are very few situations where you should chose a <radio> over a <checkbox>, when there are only two options. An example of that might be: "Method of calculation: 'pearson'/'spearman'". Here, more methods might be thinkable, and they don't really form a pair of opposites.
- </para>
- <para>
- Chosing between a <radio> and a <dropdown> is mostly a question of space. The <dropdown> has the advantage of using little space, even if there are a lot of options to chose from. On the other hand, a <radio> has the advantage of making all possible choices visible to the user at once, without clicking on the dropdown arrow. Generally, if there are six or more options to chose from, a <dropdown> is preferrable. If there are five or less options, a <radio> is the better choice.
- </para>
- </section>
-</section>
-
-</chapter>
-
-<chapter id="phptemplate">
-<title>Generating R code from GUI settings</title>
-<para>
-Now we have a GUI defined, but we still need to generate some R-code from that. For that, we need another text-file, "code.php", located in the same directory as the <link linkend="mainxml">description.xml</link>. You may or may not be familiar with PHP. Documentation on PHP can be found here: http://www.php.net. But for most purposes you will not need to know much about PHP at all, as we'll only use some very basic features..
-</para>
-<para>
-For the independent samples t-test, the code.php file looks as follows (with comments in between):
-</para>
-<programlisting>
-<?
-</programlisting>
-<para>
-This is a sort of opening tag in PHP. Everything between <? and ?> will be interpreted as PHP-code. Everything outside of these tags will simply be returned as plain text. See below for examples.
-</para>
-<programlisting>
-function preprocess () {
-}
-</programlisting>
-<para>
-The PHP-file is organized into three separate functions: preprocess, calculate, and printout. This is because not all code is needed at all stages. Currently the preprocess-function is not really used in many places.
-</para>
-<programlisting>
-function calculate () {
-?>res <- t.test (<? getRK ("x"); ?>, <? getRK ("y"); ?>, "<? getRK ("hypothesis"); ?>"<? getRK ("varequal"); if (($conflevel = getRK_val ("conflevel")) != "0.95") echo (", conf.level=" . $conflevel); ?>)
-<?
-}
-</programlisting>
-<para>
-This function generates the actual R-syntax to be run from the GUI-settings. Let's look at this in detail:
-First we leave the PHP-mode (?>) and hence return
-</para>
-<screen>
-res <- t.test (
-</screen>
-<para>
-as plain text. Next we need to fill in the value, the user selected as the first variable. Hence we enter PHP-mode again (<?) and call 'getRK ("x");'. This prints out the value of the GUI-element with id "x": our first <varslot>. Next we leave PHP-mode again, print a ', ', and do the same to fetch the value of the element "y" - the second <varslot>. For the hypothesis (the <radio>-group), and the equal variances-<checkbox>, the procedure is very similar.
-</para>
-<para>
-It gets a little more tricky for the confidence level. For reasons of aestethics, we don't want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value with 'getRK', we fetch it silently using 'getRK_val' and assign it to a PHP-variable. Then we check, whether that variable differs from "0.95" and if so print out an additional argument.
-Finally, we leave PHP-mode again, print a last ')', and that's it for the calculate-function.
-</para>
-<programlisting>
-function printout () {
-?>rk.header ("Independent samples t test")
-rk.print (res)
-<?
-}
-</programlisting>
-<para>
-And this was all there is to the printout function in most cases. rk.header () prints a standard headline for the results. You can also add some more information to this, if you like, e.g.:
-</para>
-<programlisting>
-function printout () {
-?>rk.header ("Independent samples t test", parameters=list ("Assume equal variances", <? getRK ("varequal"); ?>, "Confidence level", <? getRK ("conflevel"); ?>))
-rk.print (res)
-<?
-}
-</programlisting>
-<para>
-The list of parameters is given as pairs of "Description", "Value". This will also be printed in a standard way.
-</para>
-<para>
-rk.print () utilizes the R2HTML package to provide HTML formatted output. Another helpful function is rk.results (), which can also output different kinds of result tables. If in doubt, however, just use rk.print (), and be done with.
-</para>
-<para>
-Note that internally, the output is just a plain HTML document at this point of time. Therefore you might be tempted to add custom HTML using cat (). While this will work, please don't do this. The output format may change (e.g. to ODF) in the future, so it's best not to introduce HTML specific code. Rather keep things simple with rk.header (), rk.print (), and rk.results (). If those don't seem to satisfy your formatting needs, contact us on the mailing list for help.
-</para>
-<para>
-Congratulations! You created your first plugin. Read on in the next chapters for more advanced concepts.
-</para>
-
-<section id="phpconventions">
-<title>Conventions, policies, and background</title>
-<para>
-There are many ways to write R code for a certain task, and there are even more ways to generate this R code from PHP. How exactly you do it, is left up to you. Still there are a number of considerations that you should follow, and background information you should understand.
-</para>
-
-<section id="policylocal">
-<title>Understanding the local() environment</title>
-<para>
-More often than not you will have to create one or more temporary R objects in the code generated by your plugin. Normally, you do not want those to be placed in the user's workspace, potentially even overwriting user variables. Hence, all plugin generated code is run in a local() environment (see R help page on function local()). This means, all variables you create are temporary and will not be saved permanently.
-</para>
-<para>
-If the user explicitely asks for a variable to be saved, you will need to assign to that object with the "<<-" operator.
-</para>
-<para>
-One important pitfall is using eval() to evaluate substitutes. Here, you need to note that eval will by default use the current environment for evaluation, i.e. the local one. This will work well most of the times, but if you define any temporary variables in the local environment, and you are trying to fetch user variables of the same name using eval, you will get errors. For example:
-</para>
-<programlisting>
-# "objects" is the name of both a local temporary variable, and a user selected variable
-objects <- substitute (user.var1, user.var2, objects, user.var4)
-# this will fail: objects[3] is "the object named 'objects'", but this now refers to your
-# temporary variable, instead of the user variable
-third <- eval (objects[3])
-# instead, use this:
-third <- eval (objects[3], envir=globalenv())
-</programlisting>
-<para>
-To solve this, specify the evaluation environment explicitely, as shown above. This will generally be globalenv(), i.e. evaluate as if working in the global environment.
-</para>
-</section>
-
-<section id="policyformatting">
-<title>Code formatting</title>
-<para>
-The most important thing is for your generated R code to work. But please also keep an eye on formatting. Some considerations:
-</para>
-<para>
-Normal top-level R statements should be left aligned.
-</para>
-<para>
-Statements in a lower block should be indented with one tab (see example below).
-</para>
-<para>
-If you do very complex calculations, add a comment here and there, esp. to mark up logical sections.
-</para>
-<para>
-For example, generated code might look like this. The same code without indentation or comments would be pretty hard to read, despite its modest complexity:
-</para>
-<programlisting>
-# first determine the wobble and rotation
-my.wobble <- wobble (x, y)
-my.rotation <- wobble.rotation (my.wobble, z)
-
-# boggling method needs to be chosen according to rotation
-if (my.rotation > wobble.rotation.limit (x)) {
- method <- "foo"
- result <- boggle.foo (my.wobble, my.rotation)
-} else {
- method <- "bar"
- result <- boggle.bar (my.wobble, my.rotation)
-}
-</programlisting>
-</section>
-
-<section id="policysimplicity">
-<title>Dealing with complex options</title>
-<para>
-Many plugins can do more than one thing. For instance, the "Descriptive Statistics" plugin can compute mean, range, sum, product, median, length, etc. However, typically the user will only chose to have some of those calculations performed. In this case, please try to keep the generated code as simple as possible. It should only contain portions relevant to the options that are actually selected. To achieve this, here is an example of a common design patterns as you would use it (in PHP):
-</para>
-<programlisting>
-function calculate () { ?>
-x <- <? getRK ("x");
-results <- list () ?>
-<?
- if (getRK_val ("domean")) { ?>
-results$'Mean value' <- mean (x)
-<? }
- if (getRK_val ("domedian")) { ?>
-results$'Median' <- median (x)
-<? }
- if (getRK_val ("dosd")) { ?>
-results$'Standard deviation' <- sd (x)
-<? }
- //...
-}
-</programlisting>
-</section>
-
-</section>
-
-<section id="phptips">
-<title>Tips and tricks</title>
-<para>
-Here are a few assorted tricks which may make writing plugins less tedious:
-</para>
-<para>
-If you need the value of a GUI setting at several places in you plugin's code, consider assigning it to a PHP variable, and using that instead of fetching it again and again with getRK. This is faster, more readable, and less typing all at the same time:
-</para>
-<programlisting>
-function calculate () {
- if (getRK_val ("remove_nas") == "1") {
- $narm = ", na.rm=TRUE";
- } else {
- $narm = ""; // na.rm=FALSE is the default in all functions below
- }
-?>
-# ...
-results$foo <- foo (x<? echo ($narm); ?>)
-results$bar <- bar (x<? echo ($narm); ?>)
-results$foobar <- foobar (x<? echo ($narm); ?>)
-# ...
-<?
-}
-</programlisting>
-</section>
-
-</chapter>
-
-<chapter id="pluginhelp">
- <title>Writing a help page</title>
- <para>
- When your plugin basically works, the time has come to provide a help page. While typically you will not want to explain all the underlying concepts in depth, you may want to add some more explanation for some of the options, and link to related plugins and R functions.
- </para>
- <para>
- You may recall putting this inside your plugin-xml (if you haven't put this in, do so now):
- </para>
- <programlisting>
- <document>
- [...]
- <help file="filename.rkh" />
- [...]
- </document>
- </programlisting>
- <para>
- Where, obviously, you'd replace "filename" with a more appropriate name. Now it's time to create this .rkh file. Here is a self-descriptive example:
- </para>
- <programlisting>
- <!DOCTYPE rkhelp>
- <document>
- <summary>
- In this section, you'll put some short, very basic information about what the plugin does.
- This section will always show up on the very top of the help page.
- </summary>
-
- <usage>
- The usage section may contain a little more practical information. It does not explain all
- the settings in detail (that's done in the "settings" section), however.
-
- To start a new paragraph, insert an empty line, as shown above.
- This line, in contrast, will be in the same paragraph.
-
- In all sections you can insert some simple HTML code, such as <b>bold</b> or
- <i>italic</i> text. Please keep formatting to the minimum needed, however.
-
- The usage section is always the second section shown in a help page.
- </usage>
-
- <section id="sectionid" title="Generic section" short_title="Generic">
- If you need to, you can add additional sections between the usage and settings sections.
- However, usually, you will not need this while documenting plugins. The "id"-attribute
- provides an anchor point to jump to this section from the navigation menu. The "short_title"
- attribute provides a short title to use in the navigation bar. This is optional, by default
- the main "title" will be used both as a heading to the section, and as the link name in the
- navigation bar.
-
- In any section you may want to insert links to further information. You do this by adding
-
- <link href="URL">link name</link>
-
- Where URL could be an external link such as http://rkward.sourceforge.net .
- Several special URLs are supported in the help pages:
-
- <link href="rkward://page/path/page_id"/>
-
- This links to a top level rkward help page (not for a plugin).
-
- <link href="rkward://component/[namespace/]component_id"/>
-
- This links to the help page of another plugin. The [namespace/] part may be omitted
- (in this case, rkward is assumed as the standard namespace, e.g.:
- <link href="rkward://component/import_spss"/> or
- <link href="rkward://component/rkward/import_spss"/> are equivalent).
- The component_id is the same that you specified in the <link linkend="pluginmap">.pluginmap</link>.
-
- <link href="rkward://rhelp/rfunction"/>
-
- Links to the R help page on "rfunction".
-
- Note that the link names will be generated automatically for these types of links.
- </section>
-
- <settings>
- <caption id="id_of_tab_or_frame"/>
- <setting id="id_of_elementa">
- Description of the GUI element identified by the given id
- </setting>
- <setting id="id_of_elementb" title="description">
- Usually the title of the GUI element will be extracted from the
- <link linkend="mainxml">XML definition of the plugin</link>, automatically. However,
- for some GUI elements, this description may not be enough to identify them, reliably.
- In this case, you can add an explicit title using the "title" attribute.
- </setting>
- <setting id="id_of_elementc">
- Description of the GUI element identified by "id_of_elementc"
- </setting>
- [...]
- </settings>
-
- <related>
- The related section typically just contains some links, such as:
-
- <ul>
- <li><link href="rkward://rhelp/mean"/></li>
- <li><link href="rkward://rhelp/median"/></li>
- <li><link href="rkward://component/related_component"/></li>
- </ul>
- </related>
-
- <technical>
- The technical section (optional, always last) may contain some technical details of the plugin
- implementation, which are of interest only to RKWard developers. This is particularily relevant
- for plugins that are designed to be embedded in many other plugins, and could detail, which
- options are available to customize the embedded plugin, and which code sections contain which
- R code.
- </technical>
- </document>
- </programlisting>
-</chapter>
-
-
-<chapter id="logic">
-<title>GUI logic</title>
-<para>
-All the basic concepts of creating a plugin for &kapp; have been described in the previous chapters. Those basic concepts should be sufficient for many - if not most - cases. However, sometimes you want more control over how your plugin's GUI behaves.
-</para>
-<para>
-For instance, suppose you want to extend the t-test example used in this documentation to allow both: comparing a variable against another variable (as shown), and comparing a variable against a constant value. Now, one way of doing this would be to add a radio-control that switches between the two modes, and adding a spinbox to enter the constant value to compare against. Consider this simplified example:
-</para>
-<programlisting>
-<!DOCTYPE rkplugin>
-<document>
- <code file="code.php"/>
-
- <dialog label="T-Test">
- <row>
- <varselector id="vars"/>
- <column>
- <varslot id="x" type="numeric" source="vars" required="true" label="compare"/>
- <radio id="mode" label="Compare against">
- <option value="variable" checked="true" label="another variable (select below)"/>
- <option value="constant" label="a constant value (set below)"/>
- </radio>
- <varslot id="y" type="numeric" source="vars" required="true" label="variable"/>
- <spinbox id="constant" initial="0" label="constant" />
- </column>
- </row>
- </dialog>
-</document>
-</programlisting>
-<para>
-So far so good, but there are a number of problems with this GUI. First, both the varslot and the spinbox are always shown, whereas only one of the two is really used. Worse, the varslot always requires a valid selection, even if you compare against a constant. Obviously, if we create a multi-purpose GUI like this, we want more flexibility. Enter: the <logic>-section (inserted at the same level as <code>, <dialog>, or <wizard>).
-</para>
-<para>
-<programlisting>
- [...]
- <code file="code.php"/>
-
- <logic>
- <convert id="varmode" mode="equals" sources="mode.string" standard="variable" />
- <convert id="constmode" mode="equals" sources="mode.string" standard="constant" />
-
- <connect client="y.required" governor="varmode" />
- <connect client="y.visible" governor="varmode" />
-
- <connect client="constant.required" governor="constmode" />
- <connect client="constant.visible" governor="constmode" />
- </logic>
-
- <dialog label="T-Test">
- [...]
-</programlisting>
-</para>
-<para>
-The first two lines inside the logic section are <conver> tags. Those basically provide two new boolean (on or off, true or false) properties, which can be used later on. The first property ("varmode") is true, whenever the upper radio-button is selected and the second whenever the lower radio-button is selected. How is this done?
-</para>
-<para>
-First, under sources, the "source" properties to work on are listed (in this case only one each; you could list several as sources="mode.string;somethingelse", then varmode would only be true, if both mode.string and somethingelse are equal to the string "variable"). Note that in this case we don't just write "mode" (as we would in getRK("mode"), but "mode.string". This is actually the internal way a radio control works: It has a property "string", which holds its string value. getRK ("mode") is just a shorthand, and equivalent to getRK ("mode.string"). See the reference for all properties of the different GUI elements.
-</para>
-<para>
-Second, we set the mode of conversion to mode="equals". This means, we want to check, whether the sources are equal to a certain value. Finally standard is the value to compare against, so with standard="variable", we check whether the property mode.string is equal to the string "variable" (the value of the upper radio option). If it is equal, then the property varmode is true, else it is false.
-</para>
-<para>
-The next line is basically the same, but reversed. Here we define a property ("constmode") which becomes true, if the second radio option is selected.
-</para>
-<para>
-Now to the real stuff: We <connect> the "varmode" property to two different properties. Firstly, to y.required. This specifies, whether the varslot "y" is required or not. Secondly, to y.visible, which controls whether the varslot "y" is shown or not. Hence, if the upper radio-option is selected, the varslot "y" is required, and visible. Else it is not required and hidden.
-</para>
-<para>
-We do just the reverse for the spinbox. So in effect, either the varslot is shown and required, <emphasis>or</emphasis> the spinbox is shown and required - depending on which option is selected in the radio control. The GUI is changing itself according to the radio option. Try the example, if you like.
-</para>
-<para>
-Once again, for a complete list of properties, refer to the <link linkend="reference">reference</link>. One more property, however, is special in that all GUI elements have it: "enabled". This is slightly less drastic that "visible". It does not show/hide the GUI element, but only enables/disables it. Disabled elements are typically shown grayed out, and do not react to user input.
-</para>
-</chapter>
-
-<chapter id="embedding">
-<title>Embedding Plugins into Plugins</title>
-<para>
-When writing plugins, you will often find that you're creating a number of plugins that only differ in some respects, but have a lot more in common. For instance, for plotting, there are a number of generic R options that can be used with mostly all types of plots. Should you create a GUI and PHP-template for those over and over again?
-</para>
-<para>
-Obviously that would be quite a hassle. Fortunately, you don't have to do that. Rather you create the common functionality once, and later you can embed it into several plugins. In fact it is possible to embed any plugin into any other plugin, even if the original author of the embedded plugin never thought, somebody would want to embed their plugin into another one.
-</para>
-<section id="embedding_dialog">
-<title>Embedding inside a dialog</title>
-<para>
-Ok, enough said. How does it work? Simple: Just use the <embed> tag. Here's a stripped down example:
-</para>
-<programlisting>
-<dialog>
- <tabbook>
- <tab [...]>
- [...]
- </tab>
- <tab label="Plot Options">
- <embed id="plotoptions" component="rkward::plot_options"/>
- </tab>
- <tab [...]>
- [...]
- </tab>
- </tabbook>
-</dialog>
-</programlisting>
-<para>
-What happens here, is that the entire GUI or the plot options plugin (except of course for the standard elements like submit-button, etc.) is embedded right into your plugin (try it!).
-</para>
-<para>
-As you can see the syntax of the <embed>-tag is fairly simple. It takes an id as most elements. The parameter component specifies which plugin to embed, as defined in the <link linkend="pluginmap">.pluginmap</link> file ("rkward::plot_options" is the result of concatenating the namespace "rkward", a separator "::", and the name of the component "plot_options").
-</para>
-</section>
-<section id="embedding_code">
-<title>Code generation when embedding</title>
-<para>
-So far so good, but what about the generated code? How are the code for the embedding and embedded plugin merged? In the embedding plugin's PHP-code, simply write something like this:
-</para>
-<programlisting>
-function printout () {
-[...] ?>
-myplotfunction ([...]<? getRK ("plotoptions.code.printout"); ?>)
-<? [...]
-}
-</programlisting>
-<para>
-So essentially, we're fetching the code generated by the embedded plugin just like we're fetchting any other GUI setting. Here the string "plotoptions.code.printout" can be deparsed to: "The printout section of the generated code of the element with the id plotoptions" (plotoptions is the id we gave for the <embed>-tag above). And yes, if you want advanced control, you can even fetch the values of individual GUI elements inside the embedded plugin (but not the other way around, as the embedded plugin does not know anything about its surroundings).
-</para>
-</section>
-<section id="embedding_wizard">
-<title>Embedding inside a wizard</title>
-<para>
-If your plugin provides a wizard GUI, embedding works basically in the same way. You'll generally use:
-</para>
-<programlisting>
- <wizard [...]>
- [...]
- <page id="page12">
- [...]
- </page>
- <embed id="plotoptions" component="rkward::plot_options"/>
- <page id="page13">
- [...]
- </page>
- [...]
- </wizard>
-</programlisting>
-<para>
-If the embedded plugin provides a wizard interface, its pages will be inserted right between page12 and page13 of your plugin. If the embedded plugin provides a dialog interface only, a single new page will be added between your pages page12 and page13. The user will never notice.
-</para>
-</section>
-<section id="embedding_as_button">
-<title>Less embedded embedding: Further options button</title>
-<para>
-While embedding is cool, you should be careful not to overdo it. Too many functions inside a GUI just make it hard to find the relevant options. Of course, sometimes you may want to embed a great deal of options (like all the options to plot ()), but as those are really optional, you don't want them prominently in your GUI.
-</para>
-<para>
-An alternative is to embed those options "as a button":
-</para>
-<programlisting>
-<dialog>
- <tabbook>
- [...]
- <tab label="Options">
- [...]
- <embed id="plotoptions" component="rkward::plot_options" as_button="true" label="Specify plotting options"/>
- </tab>
- [...]
- </tabbook>
-</dialog>
-</programlisting>
-<para>
-In this case, a single push button will be added to your plugin, labelled "Specify plotting options". When you press that button, a separate dialog will come up, with all the options of the embedded plugin. Even while this embedded GUI is not visible most of the time, you can fetch its settings just as described <link linkend="embedding_code">above</link>.
-</para>
-<para>
-<emphasis>Caution:</emphasis> Probably the "button" approach should only ever be used for plugins that can never be invalid (for missing/bad settings). Otherwise the user would not be able to submit the code, but might have a hard time finding out, the reason for that is hidden behind some button.
-</para>
-</section>
-<section id="embedding_incomplete">
-<title>Embedding/defining incomplete plugins</title>
-<para>
-Some plugins - and as a matter of fact, the plot_options used as an example above, is one of them - are not complete by themselves. They simply do not have the GUI elements to select some important values. They are meant to be used only embedded into other plugins.
-</para>
-<para>
-In how far is the plot_options plugin incomplete? Well, for some option settings, it needs to know the name of the objects/expressions for the x and y axes (actually it will do fine if it only has either, but it needs at least one to function properly). However, it does not have a mechansim of selecting those objects, or entering them any other way. So how does it know about them?
-</para>
-<para>
-In the logic section of the plot_options plugin there are two additional lines, not covered, yet:
-</para>
-<programlisting>
- <logic>
- <external id="xvar" />
- <external id="yvar" />
-
- [...]
- </logic>
-</programlisting>
-<para>
-This defines two additional properties in the plot_options plugin, whose sole purpose is to be connected to some (yet unknown) properties of the embedding plugin. In the plot_options plugin those two properties are simply used like any other, and for instance there are calls to getRK("xvar") in the plot_options PHP template.
-</para>
-<para>
-Now, for the incomplete plugin there is no way of knowing, where it will be embedded, and what the relevant settings in the embedding plugin will be called. So we need to add two additional lines in the embedding plugin's logic section as well:
-</para>
-<programlisting>
- <logic>
- [...]
-
- <connnect client="plotoptions.xvar" governor="xvarslot.available" />
- <connnect client="plotoptions.yvar" governor="yvarslot.available" />
- </logic>
-</programlisting>
-<para>
-This is nothing new in principle, we've covered <connect> statements in the <link linkend="logic">chapter of GUI logic</link>. You simply connect the values in two varlots (called "xvarslot" and "yvarslot" in this example) to the receiving "external" properties of the embedded plugin. That's it. Everything else is taken care of automatically.
-</para>
-</section>
-</chapter>
-
-<chapter id="plugin_series">
-<title>Dealing with many similar plugins</title>
-<para>
-Sometimes, you may wish to develop plugins for a series of similar functions. As an example, consider the distribution plots. These generate fairly similar code, and of course it's desirable to make the graphical interfaces look similar to each other. Finally large sections of the help files can be identical. Only a few parameters are different for each plugin.
-</para>
-<para>
-The naive approach to this is to develop one plugin, then basically copy and paste the entire contents of the .php, .xml, and .rkh files, then changing the few portions that are different. However, what if sometime later you find a spelling mistake that has been copied and pasted to all plugins? What if you want to add support for a new feature? You'd have to visit all plugins again, and change each single one. A tiresome and tedious process.
-</para>
-<para>
-A second approach would be to use <link linkend="embedding">embedding</link>. However, in some cases this does not lend itself well to the problem at hand, mostly because the "chunks" you can embed are sometimes too large to be useful, and it places some constraints on the layout. For these cases, the concepts <link linkend="include_php">including .php files</link> <link linkend="include_xml">including .xml files</link> and <link linkend="snippets">snippets</link> can be very useful (but see the <link linkend="include_snippets_vs_embedding">thoughts on when it is preferrable to use embedding</link>).
-</para>
-<para>
-One word of caution, before you begin reading, though: These concepts can help making it simpler to deal with many similar plugins, and can improve maintainability and readability of those plugins. However, overdoing it can easily lead to the reverse effect. Use with some caution.
-</para>
- <section id="include_php">
- <title>Using the PHP include statement</title>
- <para>
-Perhaps one of the most important features of PHP is that you can easily include one script file inside another. The value of this becomes immediately obvious, if some sections of your PHP code are similar across plugins. You can simply define those sections in a separate .php file, and include this in all the plugin .php files. For example, as in:
- </para>
- <programlisting>
-<?
-// this is a file called "common_functions.php"
-
-function doCommonStuff () {
- // perhaps fetch some options, etc.
- // ...
-?>
-# This is R code you want in several different plugins
-<?
-}
-?>
- </programlisting>
- <programlisting>
-<?
-// this is one of your regular plugin .php files
-
-// include the common functions
-include ("common_functions.php");
-
-function calculate () {
- // do something
- // ...
-
- // insert the common code
- doCommonStuff ();
-}
-?>
- </programlisting>
- <para>
-Note that sometimes it's even more useful to reverse this, and define the "skeleton" of preproces(), calculate(), and printout() functions is a common file, and make these call back for those part which are different across plugins. E.g.:
- </para>
- <programlisting>
-<?
-// this is a file called "common_functions.php"
-
-function calculate () {
- // do some things which are the same in all plugins
- // ...
-
- // add in something that is different across plugins
- getSpecifics ();
-
- // ...
-}
-?>
- </programlisting>
- <programlisting>
-<?
-// this is one of your regular plugin .php files
-
-// include the common functions
-include ("common_functions.php");
-
-// note: no calculate() function is defined in here.
-// it in the common_functions.php, instead.
-
-function getSpecifics () {
- // print some R code
-}
-?>
- </programlisting>
- <para>
-One issue you should be aware of when using this technique is variable scoping. See the PHP manual on the keyword "global".
- </para>
- <para>
-This technique is heavily used in the distribution plot and distribution CLT plot plugins, so you may want to look there for examples.
- </para>
- </section>
-
- <section id="include_xml">
- <title>Including .xml files</title>
- <para>
-Basically the same feature of including files that is standard in PHP is also available for use in the .xml and .rkh files. At any place in these files you can place an <include> tag as shown below. The effect is that the entire contents of that XML file (to be precise: everything within the <document> tag of that file) is included verbatim at this point in the file. Note that you can only include another XML file.
- </para>
- <programlisting>
-<document>
- [...]
- <include file="another_xml_file.xml"/>
- [...]
-</document>
- </programlisting>
- <para>
-The attribute "file" is the filename relative to the directory the current file is located in.
- </para>
- </section>
-
- <section id="snippets">
- <title>Using <snippets></title>
- <para>
-While including files as shown in the <link linkend="include_xml">previous section</link> is fairly powerful, it become most useful when used in combination with <snippets>. Snippets are really smaller sections which you can insert at another point in the file. An example illustrates this best:
- </para>
- <programlisting>
-<document>
- <snippets>
- <snippet id="note">
- <frame>
- <text>
- This will be inserted at two places in the GUI
- </text>
- </frame>
- </snippet>
- </snippets>
- <dialog label="test">
- <column>
- <insert snippet="note"/>
- [...]
- <insert snippet="note"/>
- </column>
- </dialog>
-</document>
- </programlisting>
- <para>
-Hence, you define the snippet at one place at the top of the xml file, and then you <insert> it at any place(s) you wish.
- </para>
- <para>
-While this example is not too useful in itself, think about combining this with an <include>d .xml file. Note, that you can also place snippets for the .rkh file in the same file. You'd simply <include> the file there as well, and <insert> the relevant snippet:
- </para>
- <programlisting>
-<!-- This is a file called "common_snippets.xml" -->
-<document>
- <snippet id="common_options">
- <spinbox id="something" [...]/>
- [...]
- </snippet>
- <snippet id="common_note">
- <text>An important note for this type of plugin</text>
- </snippet>
-
- <snippet id="common_help">
- <setting id="something">This does something</setting>
- [...]
- </snippet>
-</document>
- </programlisting>
- <programlisting>
-<!-- This is the .xml file of the plugin -->
-<document>
- <snippets>
- <!-- Import the common snippets -->
- <include file="common_snippets.xml"/>
- </snippets>
-
- <dialog label="test2">
- <insert snippet="common_note"/>
- <spinbox id="something_plugin_specific" [...] />
- <insert snippet="common_options"/>
- </dialog>
-</document>
- </programlisting>
- <para>
-Similar to <link linkend="include_php">inclusion in PHP</link>, the reverse approach is often even more useful:
- </para>
- <programlisting>
-<!-- This is a file called "common_layout.xml" -->
-<document>
- <column>
- <insert snippet="note">
- [...]
- <insert snippet="plugin_parameters">
- </column>
- [...]
-</document>
- </programlisting>
- <programlisting>
-<!-- This is the .xml file of the plugin -->
-<document>
- <snippets>
- <snippet id="note">
- <text>The note used for this specific plugin</text>
- </snippet>
-
- <snippet id="plugin_parameters">
- <frame label="Parameters specific to this plugin">
- [...]
- </frame>
- </snippet>
- </snippets>
-
- <dialog label="test3">
- <include file="common_layout.xml"/>
- </dialog>
-</document>
- </programlisting>
- <para>
-Finally, it is also possible to <insert> snippets into other snippets, provided that: a) there is only one level of nesting, and b) the <snippets> section is placed at the top of the file (before a nested snippet is inserted); this is because <insert> statements are resolved from top to bottom.
- </para>
- </section>
-
- <section id="include_snippets_vs_embedding">
- <title><include> and <snippets> vs. embedding</title>
- <para>
-At first glance, <include> and <snippets> provides functionality rather similar to <link linkend="embedding">embedding</link>: It allows to reuse some portions of code across plugins. So what's the difference between these approaches, and when should you use which?
- </para>
- <para>
-The key difference between these concepts is that embeddable plugins are a more tight bundle. They combine a complete GUI, code to generate R code from this, and a help page. In contrast, include and insert allow much more fine grained control, but at the price of less modularity.
- </para>
- <para>
-That is, a plugin embedding another plugin will typically not need to know much about the internal details of the embedded plugin. A prime example is the plot_options plugin. Plugins wishing to embed this do not necessarily need to know about all the options provided, or how they are provided. This is a good thing, as otherwise a change in the plot_options plugin might make it necessary to adjust all plugins embedding this (a lot). In contrast, include and insert really exposes all the internal details, and plugins using this will - for example - need to know the exact ids and perhaps even the type of the elements used.
- </para>
- <para>
-Hence the rule of thumb is this: include and insert are great if the relevant options are only needed for a clearly limited group of plugins. Embedded plugins are better, if the group of plugins it may be useful to is not clearly defined, and if the functionality can easily be modularized. Another rule of thumb: If you can put the common portions into a single "chunk", then do so, and use embedding. If you need lots of small snippets to define the common portions - well, use <snippets>. A final way to look at it: If all plugins provide <emphasis>highly</emphasis> similar functionality, includes and inserts are probably a good idea. If they merely share one or two common "modules", embedding is likely better.
- </para>
- </section>
-</chapter>
-
-<chapter id="specialized_plugins">
-<title>Concepts for use in specialized plugins</title>
-<para>
-This chapter contains information on some topics that are useful only to certain classes of plugins.
-</para>
-
-<section id="preview_plots">
- <title>Preview functionality for graphing plugins</title>
- <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 <preview>-checkbox to your <link linkend="mainxml">GUI definition</link>, and adjusting the <link linkend="phptemplate">generated code</link> for the preview. We will deal with both in turn.
- </para>
- <para>
-Adding a <preview>-checkbox is simple. Just place the following somewhere in your GUI. It will take care of all the behind-the-scenes magic of creating a preview device, updaing the preview whenever the setting have changed, etc. Example:
- </para>
- <programlisting>
-<document>
- [...]
- <dialog [...]>
- [...]
- <preview id="preview"/>
- [...]
- </dialog>
- [...]
-</document>
- </programlisting>
- <para>
-And that's it for the GUI definition.
- </para>
- <para>
-Adjusting the PHP template is a little more work. You will have to create a new function called "preview" in addition to the "preprocess", "calculate", etc. functions. This function should generate the code needed to produce the plot, and only that. Esp. no printing of headers, rk.graphics.on(), or similar calls. Below is an example of the typical pattern that you will use:
- </para>
- <programlisting>
-<?php
-function preprocess () {
- // the "somepackage" is needed to create the plot
-?>
-require (somepackage)
-<? [...]
-}
-
-function calculate () {
- // empty in this example
-}
-
-function printout () {
- // all the real work is moved to a custom defined function doPrintout (), below
-
- doPrintout (true); // true in this case means: We want all the headers that should be printed in the output
-}
-
-function preview () {
- // we call all stages of the general code. Only the printout () function need to be slightly different
- preprocess ();
- calculate ();
- doPrintout (false);
-}
-
-function doPrintout ($final) {
- // this function takes care of generating the code for the printout() section. If $final is set to true,
- // it generates the full code, including headers. If $final is set to false, only the essentials will
- // be generated.
-
- if ($final) { ?>
-rk.header ("An example plot")
-
-rk.graph.on ()
-< }
- // only the following section will be generated for $final==false
-?>
-try ({plot (5, 5)})
-< if ($final) { ?>
-rk.graph.off ()
- }
-<?
-}
-?>
- </programlisting>
- <para>
-That's it, your plugin should now be preview-enabled.
- </para>
-</section>
-
-<section id="contextualized_plugins">
- <title>Context-dependent plugins</title>
- <para>
-So far we have assumed, all plugins are always meaningful, and all placed in the main menu. However, some plugins are meaningful only (or additionally) in a certain context. For instance a plugin to export the contents of an R X11 graphics device is obviously most useful, when placed in the menu of an X11 device, not in the main menubar. Also, such a plugin should know about the device number that it should operate on, without having to ask the user about this.
- </para>
- <para>
-We call such plugins context-dependent. Correspondingly, in the <link linkend="pluginmap">.pluginmap file</link>, they are not (or not only) placed in the main <hierarchy> but rather into a <context> element. So far only two different contexts are supported (more will come later): x11 and file import. We'll deal with those in turn. Even if you are only interested in the import context, please also read the section on the x11 context, as this is slightly more elaborate.
- </para>
-
- <section id="context_x11">
- <title>X11 device context</title>
- <para>
-To use a plugin in the context of an x11 device - that is place it in the menu bar of the window you get when you call "x11 ()" in the cosonle, first declare it as usual in the <link linkend="pluginmap">.pluginmap file</link>:
- </para>
- <programlisting>
-<document [...]>
- <components>
- [...]
- <component id="my_x11_plugin" file="my_x11_plugin.xml" label="An X11 context plugin"/>
- [...]
- </components>
- </programlisting>
- <para>
-However, you do not need to define it in the hierarchy (you can, if it is also meaningful as a top-level plugin):
- </para>
- <programlisting>
- <hierarchy>
- [...]
- </hierarchy>
- </programlisting>
- <para>
-Instead, add a definition of the "x11" context, and add it to the menus there:
- </para>
- <programlisting>
- <context id="x11">
- [...]
- <menu id="edit">
- [...]
- <entry id="my_x11_plugin"/>
- </menu>
- </context>
-</document>
- </programlisting>
- <para>
-In the <link linkend="logic">logic section of the plugin xml</link>, you can now declare two <external> properties: "devnum" and "context". Context (if declared) will be set to "x11" when the plugin is invoked in this context. "devnum" will be set to the number of the graphics device to operate on. And that's all.
- </para>
- </section>
-
- <section id="context_import">
- <title>Import data context</title>
- <para>
-Before reading this section, please make sure to read the section on the <link linkend="context_x11">X11 device context</link>, as that explains the basic concepts.
- </para>
- <para>
-The "import" context is used to declare import file filter plugins. You simply place those in a context with id="import" in the .pluginmap file. However, there is one additional twist when declaring these plugins: In order to offer a unified file selection dialog for all supported file types, you need to declare one additional bit of information on your component:
- </para>
- <programlisting>
-<document [...]>
- <components>
- [...]
- <component id="my_xyz_import_plugin" file="my_xyz_import_plugin.xml" label="Import XYZ files">
- <attribute id="format" value="*.xyz *.zyx" label="XYZ data files"/>
- </component>
- [...]
- </components>
- <hierarchy>
- [...]
- </hierarchy>
- <context id="import">
- [...]
- <menu id="import">
- [...]
- <entry id="my_xyz_import_plugin"/>
- </menu>
- </context>
- [...]
-</document>
- </programlisting>
- <para>
-The attribute line simply says, that the associate filename extensions for XYZ files are *.xyz or *.zyx, and that the filter should be labelled "XYZ data files" in the file selection dialog.
- </para>
- <para>
-You can declare two <external> properties in your plugin. "filename" will be set to the selected file name, and "context" will be set to "import".
- </para>
- </section>
-</section>
-
-</chapter>
-
-<appendix id="reference">
-<title>Reference</title>
-
-<section id="propertytypes"><title>Types of properties / Modifiers</title>
-<para>
-At some places in this introduction we've talked about "properties" of GUI elements or otherwise. In fact there are several different types of properties. Usually you do not need to worry about this, as you can use common sense to connect any property to any other property. However, internally, there are different types of properties. What this matters for, is when fetching some special values in the PHP-template. In getRK ("id") statements you can also specify some so called "modifiers" like so: getRK ("id.modifier"). This modifier will affect, in which way the value is printed. Read on for the list of properties, and the modifiers they each make available:
-</para>
-<variablelist>
-<varlistentry>
-<term>String properties</term>
-<listitem>The most simple type of property, used to simply hold a piece of text. It does not provide any modifiers. If you attempt to fetch modified values from the PHP template, it will return the usual value, and a warning will be written to the terminal you're running rkward from.</listitem>
-</varlistentry>
-<varlistentry>
-<term>Boolean properties</term>
-<listitem>Properties that can either be on or off, true or false. For instance the properties created by <convert>-tags, also the property accompanying a <checkbox> (see below). The following values will be returned according to the given modifier:
- <variablelist>
- <varlistentry>
- <term>No modifier ("")</term>
- <listitem>By default the property will return the string "TRUE", if it is true, and "FALSE" otherwise. Boolean properties attached to a checkbox behave slightly differently, and return the strings you specified in the "value" and "value_unchecked" attributes.</listitem>
- </varlistentry>
- <varlistentry>
- <term>"true"</term>
- <listitem>Return the string as if the property was true, even if it is false</listitem>
- </varlistentry>
- <varlistentry>
- <term>"false"</term>
- <listitem>Return the string as if the property was false, even if it is true</listitem>
- </varlistentry>
- <varlistentry>
- <term>"not"</term>
- <listitem>This actually returns another Boolean property, which is the reverse of the current (i.e. false if true, true if false)</listitem>
- </varlistentry>
- <varlistentry>
- <term>"numeric"</term>
- <listitem>Return the string "1" if the property is true, or "0" if it is false</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term>Integer properties</term>
-<listitem>A property designed to hold an integer value (but of course it still returns a numeric character string to the PHP-template). It does not accept any modifiers. Used in <spinbox>es (see below)</listitem>
-</varlistentry>
-<varlistentry>
-<term>Real number properties</term>
-<listitem>A property designed to hold a real number value (but of course it still returns a numeric character string to the PHP-template). It does not accept any modifiers. Used in <spinbox>es (see below)</listitem>
-</varlistentry>
-<varlistentry>
-<term>RObject properties</term>
-<listitem>A property designed a selection of one or more R objects. Used most porminently in varselectors and varslots. The following values will be returned according to the given modifier:
- <variablelist>
- <varlistentry>
- <term>No modifier ("")</term>
- <listitem>By default the property will the full name of the selected object. If more than one object is selected, the object names will be separated by linebreaks ("\n").</listitem>
- </varlistentry>
- <varlistentry>
- <term>"shortname"</term>
- <listitem>Like above, but returns only short name(s) for the object(s). For instance an object inside a list would only be given the name it has inside the list, without the name of the list.</listitem>
- </varlistentry>
- <varlistentry>
- <term>"label"</term>
- <listitem>Like above, but returns the &kapp; label(s) of the object(s) (if no label availabe, this is the same as shortname)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term>Code properties</term>
-<listitem>A property held by plugins that generated code. This is important for embedding plugins, in order to embed the code generated by the embedded plugin into the code generated by the embedding (top-level) plugin. The following values will be returned according to the given modifier:
- <variablelist>
- <varlistentry>
- <term>No modifier ("")</term>
- <listitem>Returns the full code, i.e. the sections "preprocess", "calculate", "printout", and (but not "preview") concatenated to one string.</listitem>
- </varlistentry>
- <varlistentry>
- <term>"preprocess"</term>
- <listitem>Returns only the preprocess section of the code</listitem>
- </varlistentry>
- <varlistentry>
- <term>"calculate"</term>
- <listitem>Returns only the calculate section of the code</listitem>
- </varlistentry>
- <varlistentry>
- <term>"printout"</term>
- <listitem>Returns only the printout section of the code</listitem>
- </varlistentry>
- <varlistentry>
- <term>"preview"</term>
- <listitem>Returns the preview section of the code</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-</variablelist>
-</section>
-
-<section id="globalxmlelements">
- <title>General purpose elements to be used in any XML file (.xml, .rkh, .pluginmap)</title>
- <variablelist>
- <varlistentry>
- <term><snippets></term>
- <listitem>Allowed as a direct child of the <document> node and only there. Should be placed near the top of the file. See <link linkend="snippets">section on using snippets</link>. Only one <snippets> element may be present. Optional, no attributes.</listitem>
- </varlistentry>
- <varlistentry>
- <term><snippet></term>
- <listitem>Defines a single snippet. Allowed only as a direct child of the <snippets/> element. Attributes:
- <variablelist>
- <varlistentry>
- <term><id></term>
- <listitem>An identifier string for the snippet. Required.</listitem>
- </varlistentry>
- </variablelist></listitem>
- </varlistentry>
- <varlistentry>
- <term><insert></term>
- <listitem>Insert the contents of a <snippet>. Allowed anywhere. Attributes:
- <variablelist>
- <varlistentry>
- <term><snippet></term>
- <listitem>The identifier string of the snippet to insert. Required.</listitem>
- </varlistentry>
- </variablelist></listitem>
- </varlistentry>
- <varlistentry>
- <term><include></term>
- <listitem>Include the contents of another xml file (everything inside the <document> element of that file). Allowed anywhere. Attributes:
- <variablelist>
- <varlistentry>
- <term><file></term>
- <listitem>The filename, relative to the directory, the current file is in. Required.</listitem>
- </varlistentry>
- </variablelist></listitem>
- </varlistentry>
- </variablelist>
-</section>
-
-<section id="xmlelements"><title>Elements to be used in the XML description of the plugin</title>
-<para>Properties held by the elements are listed in a <link linkend="elementproperties">separate section</link>.</para>
-
-<section id="generalelements"><title>General elements</title>
-<variablelist>
-<varlistentry>
-<term><document></term>
-<listitem>Needs to be present in each description.xml-file as the root-node. No special function. No attributes</listitem>
-</varlistentry>
-<varlistentry>
-<term><code></term>
-<listitem>Defines where to look for the PHP template to the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
- <variablelist>
- <varlistentry>
- <term><file></term>
- <listitem>Filename of the PHP template, relative to the directory the plugin-xml is in</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><help></term>
-<listitem>Defines where to look for the help file for the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
- <variablelist>
- <varlistentry>
- <term><file></term>
- <listitem>Filename of the help file, relative to the directory the plugin-xml is in</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><copy></term>
-<listitem>Can be used as a child (direct or indirect) of the main layout elements, i.e. <dialog> and <wizard>. This is used to copy an entire block a xml elements 1:1. Attributes:
- <variablelist>
- <varlistentry>
- <term><id></term>
- <listitem>The id to look for. The <copy> tag will look for a previous XML element that has been given the same id, and copy it including all descendent elements.</listitem>
- </varlistentry>
- <varlistentry>
- <term><copy_element_tag_name></term>
- <listitem>In some few cases, you will want an almost literal copy, but change the tag-name of the element to copy. The most important example of this is, when you want to copy an entire <tab> from a dialog interface to the <page> of a wizard interface. In this case, you'd set coyp_elemnent_tag_name="page" to do this conversion automatically.</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-</variablelist>
-</section>
-
-<section id="interfaceelements"><title>Interface definitions</title>
-<variablelist>
-<varlistentry>
-<term><dialog></term>
-<listitem>Defines a dialog-type interface. Place the GUI-definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Caption for the dialog</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><wizard></term>
-<listitem>Defines a wizard-type interface. Place the GUI-definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Accepts only <page> or <embed>-tags as direct children. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Caption for the wizard</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-</variablelist>
-</section>
-
-<section id="layoutelements"><title>Layout elements</title>
-<para>All elements in this section accept an attribute id="identifierstring". This attribute is optional for all elements. It can be used, for example, to hide/disable the entire layout element and all the elements contained therein (see <link linkend="logic">chaper GUI logic</link>). The id-string may not contain "." (dot) or ";" (semicolon), and should generally be limited to alphanumeric characters and the underscore ("_"). Only the additional attributes are listed.</para>
-<variablelist>
-<varlistentry>
-<term><page></term>
-<listitem>Defines a new page inside a wizard. Only allowed as a direct child of a <wizard> element.</listitem>
-</varlistentry>
-<varlistentry>
-<term><row></term>
-<listitem>All direct children of a "row" tag will be placed left-to-right.</listitem>
-</varlistentry>
-<varlistentry>
-<term><column></term>
-<listitem>All direct children of a "column" tag will be placed top-to-bottom.</listitem>
-</varlistentry>
-<varlistentry>
-<term><stretch></term>
-<listitem>By default, elements in the GUI take up all the space that's available. For instance, if you have two columns side by side, the left one is packed with elements, but the right one only contains a lonely <radio>, the <radio> control will expand vertically, even though it does not really need the available space, and it will look ugly. In this case you really want to add a "blank" below the <radio>. For this, use the <stretch> element. It will simply use up some space. Don't overuse this element, usually it's a good idea for GUI elements to get all the available space, only sometimes will the layout become spaced out. The <stretch> element does not take any arguments, not even an "id". Also you can place no children inside the <stretch> element (in other words, you'll only ever use it as "<stretch/>")</listitem>
-</varlistentry>
-<varlistentry>
-<term><frame></term>
-<listitem>Draws a frame/box around its direct children. Can be used to visually group related options. Layout inside a frame is top-to-bottom, unless you place a <row> inside. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Caption for the frame (optional)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><tabbook></term>
-<listitem>Organizes elements in a tabbook. Accepts only <tab>-tags as direct children.</listitem>
-</varlistentry>
-<varlistentry>
-<term><tab></term>
-<listitem>Defines a page in a tabbook. Place the GUI-definition for the tab inside this tag. May be used only as a direct child of a <tabbook> tag. A <tabbook> should have at least two defined tabs. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Caption for the tab page (required)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><text></term>
-<listitem>Shows the text enclosed in this tag in the GUI. Linebreaks are interpreted as hard linebreaks! Attributes:
- <variablelist>
- <varlistentry>
- <term><type></term>
- <listitem>Type of the text. One of "normal", "warning" or "error". This influences the look of the text (optional, defaults to normal)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-</variablelist>
-</section>
-
-<section id="activeelements"><title>Active elements</title>
-<para>All elements in this section accept an attribute id="identifierstring". This attribute is required for all elements. Only the additional attributes are listed. The id-string may not contain "." (dots).</para>
-<variablelist>
-<varlistentry>
-<term><varselector></term>
-<listitem>Provides a list of availabe objects from which the user can select one or more. Requires one or more <varslot>s as a counterpart to be useful. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the varselector (optional, defaults to "Select variable(s)")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><varslot></term>
-<listitem>Used in conjunction with a "varselector" to allow the user to select one or more variables. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the varslot (recommended, defaults to "Variable:")</listitem>
- </varlistentry>
- <varlistentry>
- <term><source></term>
- <listitem>The varselector to fetch the selection from (required, unless you connect manually)</listitem>
- </varlistentry>
- <varlistentry>
- <term><required></term>
- <listitem>Whether - for submitting the code - it is required that this varslot holds a valid value. See <link linkend="elementproperties">required-property</link> (optional, defaults to false)</listitem>
- </varlistentry>
- <varlistentry>
- <term><multi></term>
- <listitem>Whether the varslot holds only one (default, "false"), or several objects</listitem>
- </varlistentry>
- <varlistentry>
- <term><min_vars></term>
- <listitem>Only meaningful if multi="true": Minimum number of vars to be selected for the selection to be considered valid (optional, defaults to "1")</listitem>
- </varlistentry>
- <varlistentry>
- <term><min_vars_if_any></term>
- <listitem>Only meaningful if multi="true": Some varslots may be considered valid, if, for instance, the varslot is either empty, or holds at least two values. This specifies how many variables have to be selected if any at all (2 in the example). (optional, defaults to "1")</listitem>
- </varlistentry>
- <varlistentry>
- <term><max_vars></term>
- <listitem>Only meaningful if multi="true": Maximum number of variables to select (optional, defaults to "0", which means no maximum)</listitem>
- </varlistentry>
- <varlistentry>
- <term><classes></term>
- <listitem>If you specify one or more R classnames (separated by spaces (" ")), here, the varslot will only accept objects belonging to those classes (otional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and R has <emphasis>a lot</emphasis> of different classes!)</listitem>
- </varlistentry>
- <varlistentry>
- <term><types></term>
- <listitem>If you specify one or more variables types (separated by spaced (" ")), here, the varslot will only accept objects of those types. Valid types are "unknown", "number", "string", "factor", "invalid". (Optional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and rkward does not always know the type of a variable)</listitem>
- </varlistentry>
- <varlistentry>
- <term><num_dimensions></term>
- <listitem>The number of dimensions, an object needs to have. "0" (the default) means, any number of dimensions is acceptable. (optional, defaults to "0")</listitem>
- </varlistentry>
- <varlistentry>
- <term><min_length></term>
- <listitem>The minimum length, an object needs to have in order to be acceptable. (optional, defaults to "0")</listitem>
- </varlistentry>
- <varlistentry>
- <term><max_length></term>
- <listitem>The maximum length, an object needs to have in order to be acceptable. (optional, defaults to the largest integer number representable on the system)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><radio></term>
-<listitem>Defines a group of radio-exclusive buttons (only one can be selected at a time). Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the radio control (recommended, defaults to "Select one:")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><dropdown></term>
-<listitem>Defines a group of options of which one and only one can be selected at the same time, using a dropdown list. This is functionaly equivalent to a <radio>, but looks different. Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the dropdown list (recommended, defaults to "Select one:")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><option></term>
-<listitem>Can only be used as a direct child of a <radio> or <dropdown> element. Represents one selectable option in a radio control or dropdown list. Specifying the "id" parameter for the <option> elements is optional (and in fact it's recommended, not to set an "id", unless you plan to really use it to disable single options). Only the parent element (<radio> or <dropdown>) needs one. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the option (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><value></term>
- <listitem>The string value the parent element will return if this option is checked/selected (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><checked></term>
- <listitem>Whether the option should be checked/selected by default "true" or "false". Only one button in a <radio> may be set to checked="true". If no option is set to checked, the first option in the parent element will be checked/selected automatically. (optional, default to "false")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><checkbox></term>
-<listitem>Defines a checkbox, i.e. a single option that can either be set to on or off. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the checkbox (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><value></term>
- <listitem>The value the checkbox will return if checked (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><value_unchecked></term>
- <listitem>The value that will be returned if the checkbox is not checked (optional, defauls to "", i.e. an empty string)</listitem>
- </varlistentry>
- <varlistentry>
- <term><checked></term>
- <listitem>Whether the option should be checked by default "true" or "false" (optional, default to "false")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><input></term>
-<listitem>Defines a free text input field. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the input field (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><initial></term>
- <listitem>Initial text of the text field (optional, defaults to "", i.e. an empty string)</listitem>
- </varlistentry>
- <varlistentry>
- <term><size></term>
- <listitem>One of "small", "medium", or "large". "large" defines a multi-line input field, "small", and "medium" are single line fields (optional, defaults to "medium")</listitem>
- </varlistentry>
- <varlistentry>
- <term><required></term>
- <listitem>Whether - for submitting the code - it is required that this input is not empty. See <link linkend="elementproperties">required-property</link> (optional, defaults to false)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><browser></term>
-<listitem>An element designed to select a single filename (or directory name). Note that this field will take any string, even though it is meant to be used for files, only:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the browser (optinal, defaults to "Enter filename")</listitem>
- </varlistentry>
- <varlistentry>
- <term><initial></term>
- <listitem>Initial text of the browser (optional, defaults to "", i.e. an empty string)</listitem>
- </varlistentry>
- <varlistentry>
- <term><type></term>
- <listitem>One of "file", "dir", or "savefile". To select an existing file, existing directory, or non-existing file, respectively (optional, defaults to "file")</listitem>
- </varlistentry>
- <varlistentry>
- <term><filter></term>
- <listitem>File type filter, e.g. ("*.txt *.csv" for .txt and .csv files. Try not to induce limits unless absolutely needed, though) (optional, defaults to "", i.e. all files)</listitem>
- </varlistentry>
- <varlistentry>
- <term><required></term>
- <listitem>Whether - for submitting the code - it is required that the field is not empty. Note that this does not necessarily mean, the selected filename is valid! See <link linkend="elementproperties">required-property</link> (optional, defaults to true)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><saveobject></term>
-<listitem>An element designed to select the name of an R object to save to (i.e. generally not already existing, in contrast to a varslot):
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the input (optinal, defaults to "Save to:")</listitem>
- </varlistentry>
- <varlistentry>
- <term><initial></term>
- <listitem>Initial text of the input (optional, defaults to "my.data")</listitem>
- </varlistentry>
- <varlistentry>
- <term><required></term>
- <listitem>Whether - for submitting the code - it is required that the field holds a permissible object name. See <link linkend="elementproperties">required-property</link> (optional, defaults to true)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><spinbox></term>
-<listitem>A spinbox in which the user can select a numeric value, using either direct keyboard input or small up/down arrows. Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label for the spinbox (recommend, default to "Enter value:")</listitem>
- </varlistentry>
- <varlistentry>
- <term><min></term>
- <listitem>The lowest value the user is allowed to enter in the spinbox (optional, defaults to the lowest value technically representable in the spinbox)</listitem>
- </varlistentry>
- <varlistentry>
- <term><max></term>
- <listitem>The largest value the user is allowed to enter in the spinbox (optional, defaults to the highest value technically representable in the spinbox)</listitem>
- </varlistentry>
- <varlistentry>
- <term><initial></term>
- <listitem>The initial value shown in the spinbox (optional, defaults to "0")</listitem>
- </varlistentry>
- <varlistentry>
- <term><type></term>
- <listitem>One of "real" or "integer". Whether the spinbox will accept real numbers or only integers (optional, defaults to "real")</listitem>
- </varlistentry>
- <varlistentry>
- <term><default_precision></term>
- <listitem>Only meaningful if the spinbox is of type="real". Specifies the default number of decimal places shown in the spinbox (only this many trailing zeros will be shown). When the user presses the up/down arrows, this decimal place will be changed. The user may still be able to enter values with a higher precision, however (see below) (optional, defaults to "2")</listitem>
- </varlistentry>
- <varlistentry>
- <term><max_precision></term>
- <listitem>The maximum number of digits that can be meaningfully represented (optional, defaults to "8")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><formula></term>
-<listitem>This advanced element allows the user to select a formula/set of interactions from selected variables. For instance for a GLM, this element can be used to allow the user to specify the interaction-terms in the model. Attributes:
- <variablelist>
- <varlistentry>
- <term><fixed_factors></term>
- <listitem>The id of the varslot holding the selected fixed factors (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><dependent></term>
- <listitem>The id of the varslot holding the selected dependent variable (required)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><embed></term>
-<listitem>Embed a different plugin into this one (see <link linkend="embedding">chapter on embedding</link>). Attributes:
- <variablelist>
- <varlistentry>
- <term><component></term>
- <listitem>The registered name of the component to embed (see <link linkend="pluginmap">chapter on registering components</link> (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><as_button></term>
- <listitem>If set to "true", only a pushbutton will be placed in the embedding GUI, the embedded GUI will only be shown (in a separate window) when the pushbutton is pressed (optional, default is "false")</listitem>
- </varlistentry>
- <varlistentry>
- <term><label></term>
- <listitem>Only meaningful if as_button="true": The label of the button (recommend, default is "Options")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-<varlistentry>
-<term><preview></term>
-<listitem>Checkbox to toggle preview functionality (see <link linkend="preview_plots">chapter on graph previews</link>). Attributes:
- <variablelist>
- <varlistentry>
- <term><label></term>
- <listitem>Label of the box (optional, default is "Preview")</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-</variablelist>
-</section>
-
-<section id="logicelements"><title>Logic section</title>
-<variablelist>
-<varlistentry>
-<term><logic></term>
-<listitem>The containing element for the logic section. All elements below are allowed only inside the <logic> element. Only one <logic> element is allowed per document, as a direct child of the <document> element. The logic section applies to both <dialog> and <wizard> GUIs in the same way.</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><external></term>
-<listitem>Creates a new (string) property that is supposed to be connected to an outside property if the plugin gets embedded. See <link linkend="embedding_incomplete">section on "incomplete" plugins</link>. Attributes:
- <variablelist>
- <varlistentry>
- <term><id></term>
- <listitem>The id of the new property (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><default></term>
- <listitem>The default string value of the new property, i.e. the value used, if the property is not connected to an outside property (optional, defaults to an empty string)</listitem>
- </varlistentry>
- </variablelist></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><set></term>
-<listitem>Set a property to a fixed value (of course, if you additionally connect the property to some other property, the value does not remain fixed). For instance, if you embed a plugin, but want to hide some of its elements, you might set the visibility property of those elements to false. Useful esp. for embedded/embedding plugins. Attributes:
- <variablelist>
- <varlistentry>
- <term><id></term>
- <listitem>The id of the property to set (required)</listitem>
- </varlistentry>
- <varlistentry>
- <term><to></term>
@@ Diff output truncated at 100000 characters. @@
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