[rkward-cvs] SF.net SVN: rkward: [1879] trunk/rkward

[tfry at users.sourceforge.net]

Revision: 1879
          http://svn.sourceforge.net/rkward/?rev=1879&view=rev
Author:   tfry
Date:     2007-05-07 15:09:58 -0700 (Mon, 07 May 2007)

Log Message:
-----------
Start documenting includes and snippets

Modified Paths:
--------------
    trunk/rkward/TODO
    trunk/rkward/doc/en/writing_plugins_introduction.docbook

Modified: trunk/rkward/TODO
===================================================================
--- trunk/rkward/TODO	2007-05-07 21:27:04 UTC (rev 1878)
+++ trunk/rkward/TODO	2007-05-07 22:09:58 UTC (rev 1879)
@@ -32,6 +32,7 @@
 Compilation / technical
 	- Incorporate FreeBSD patches http://www.freshports.org/math/rkward/files.php?message_id=200609172111.k8HLBiob081349@repoman.freebsd.org
 	- cleanup DISABLE_RKWINDOWCATCHER (either get rid of it, or do it right)
+	- when linking against the R libraries, use the full path
 
 UI-stuff
 	- find/create a set of menu icons (https://sourceforge.net/mailarchive/message.php?msg_id=37891606)

Modified: trunk/rkward/doc/en/writing_plugins_introduction.docbook
===================================================================
--- trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-05-07 21:27:04 UTC (rev 1878)
+++ trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-05-07 22:09:58 UTC (rev 1879)
@@ -837,6 +837,145 @@
 </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>
+	<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>
+	</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 you wish.
+	</para>
+	<para>
+While this example is not too useful in itself, think about combining this with an <include>d .xml file:
+	</para>
+	<programlisting>
+	</programlisting>
+	<programlisting>
+	</programlisting>
+	<para>
+Similar to <link linkend="include_php">inclusion in PHP</link>, the reverse approach is often even more useful:
+	</para>
+	<programlisting>
+	</programlisting>
+	<programlisting>
+	</programlisting>
+	</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>
+	</para>
+	</section>
+</chapter>
+
 <chapter id="specialized_plugins">
 <title>Concepts for use in specialized plugins</title>
 <para>


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.