Introduction to Writing Plugins for RKWard

Thomas Friedrichsmeier

Meik Michalke

Revision 0.6.2.00 (2014-10-13)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This is a guide to writing plugins for RKWard.


Table of Contents

1. Introduction
2. Preliminaries: What are plugins in RKWard? How do they work?
3. Creating menu entries
4. Defining the GUI
Defining a dialog
Adding a wizard interface
Some considerations on GUI design
<radio> vs. <checkbox> vs. <dropdown>
5. Generating R code from GUI settings
Using JavaScript in RKWard plugins
preprocess()
calculate()
printout()
Conventions, policies, and background
Understanding the local() environment
Code formatting
Dealing with complex options
Tips and tricks
6. Writing a help page
7. Logic interactions between GUI elements
GUI logic
Scripted GUI logic
8. Embedding Plugins into Plugins
Use cases for embedding
Embedding inside a dialog
Code generation when embedding
Embedding inside a wizard
Less embedded embedding: Further Options button
Embedding/defining incomplete plugins
9. Dealing with many similar plugins
Overview on different approaches
Using the JS include statement
Including .xml files
Using <snippets>
<include> and <snippets> vs. <embed>
10. Concepts for use in specialized plugins
Plugins than produce a plot
Drawing a plot to the output window
Adding preview functionality
Generic plot options
A canonical example
Context-dependent plugins
X11 device context
Import data context
Querying R for information
Referencing the current object
Repeating (a set of) options
"Driven" optionsets
Alternatives: When not to use optionsets
11. Handling dependencies and compatibility issues
RKWard version compatibility
R version compatibility
Dependencies on R packages
Dependencies on other RKWard .pluginmaps
An example
12. Author, license and version information
13. Share your work with others
External plugins
Why external plugins?
Structure of a plugin package
File hierarchy
Building the plugin package
14. Plugin development with the rkwarddev package
Overview
Practical example
GUI description
JavaScript code
Plugin map
Help page
Generate the plugin files
The full script
A. Reference
Types of properties/Modifiers
General purpose elements to be used in any XML file (.xml, .rkh, .pluginmap)
Elements to be used in the XML description of the plugin
General elements
Interface definitions
Layout elements
Active elements
Logic section
Properties of plugin elements
Embeddable plugins shipped with the official RKWard release
Elements for use in .pluginmap files
Elements for use in .rkh (help) files
Functions available for GUI logic scripting
B. Troubleshooting during plugin development
C. License

List of Tables

A.1. Standard embeddable plugins