http://docs.kde.org/
 Next

Introduction to Writing Plugins for RKWard

Thomas Friedrichsmeier

Meik Michalke

Revision 0.7.4 (2022-04-24)

Copyright © 2006-2022 Thomas Friedrichsmeier

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
Controlling the order of 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 that produce a plot
Drawing a plot to the output window
Adding preview functionality
Generic plot options
A canonical example
Previews for data, output and other results
Previews of (HTML) output
Previews of (imported) data
Custom previews
Context-dependent plugins
X11 device context
Import data context
Querying R for information
Referencing the current object or current file
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. Plugin translations
General considerations
i18n in RKWard's xml files
i18n in RKWard's js files and sections
i18n and quotes
Translation maintainance
Writing plugin translations
13. Author, license and version information
14. Share your work with others
External plugins
Why external plugins?
Structure of a plugin package
File hierarchy
Building the plugin package
15. Plugin development with the rkwarddev package
Overview
Practical example
GUI description
JavaScript code
Plugin map
Help page
Generate the plugin files
The full script
Adding help pages
Translating plugins
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