rk.plugin.skeleton | R Documentation |
Generate skeletons for RKWard plugins
Description
With this function you can write everything from a basic skeleton structure to a complete functional plugin,
including several
components/dialogs. You should always define one main component (by xml
, js
,
rkh
etc.) before you provide
additional features by components
.
Usage
rk.plugin.skeleton(
about,
path = tempdir(),
provides = c("logic", "dialog"),
scan = c("var", "saveobj", "settings", "preview"),
unused.vars = FALSE,
guess.getter = FALSE,
xml = list(),
js = list(),
pluginmap = list(),
rkh = list(),
overwrite = FALSE,
tests = TRUE,
lazyLoad = TRUE,
create = c("pmap", "xml", "js", "rkh", "desc", "clog"),
suggest.required = TRUE,
components = list(),
dependencies = NULL,
edit = FALSE,
load = FALSE,
show = FALSE,
gen.info = TRUE,
hints = TRUE,
indent.by = rk.get.indent(),
internal = FALSE
)
Arguments
about |
Either an object of class XiMpLe.node with descriptive information on the plugin and its authors
(see link[XiMpLe:rk.XML.about]{rk.XML.about} for details),
or a character string with the name of the plugin package.
If the latter, no DESCRIPTION file will be created.
|
path |
Character sting,
path to the main directory where the skeleton should be created.
|
provides |
Character vector with possible entries of "logic" ,
"dialog" or "wizard" , defining what
sections the GUI XML file should provide even if dialog ,
wizard and logic are NULL .
These sections must be edited manually and some parts are therefore commented out.
|
scan |
A character vector to trigger various automatic scans of the generated GUI XML file. Valid enties are:
"var" Calls rk.JS.scan to define all needed variables in the calculate() function
of the JavaScript file. These variables will be added to variables defined by the js option,
if any (see below).
"saveobj" Calls rk.JS.saveobj to generate code to save R results in the printout()
function of the JavaScript file. This code will be added to the code defined by the js option,
if any (see below).
"settings" Calls rk.rkh.scan to generate <setting> sections for each relevant GUI element in
the <settings> section of the help file. This option will be overruled if you provide that section manually
by the rkh option (see below).
"preview" Calls rk.JS.scan to search for <preview> nodes in the XML code.
An according preview() function will be added to the JS code if needed. Will be overwritten by a
preview function that was defined by the js option.
|
unused.vars |
Logical,
if TRUE all variables found by scan are being defined, even if they are not used in the
JavaScript code. By default only matching variables will be kept. This option should only be used for debugging.
|
guess.getter |
Logical,
if TRUE try to get a good default getter function for JavaScript
variable values (if scan is active). This will use some functions which were added with RKWard 0.6.1,
and therefore
raise the dependencies for your plugin/component accordingly. Nonetheless,
it's recommended.
|
xml |
A named list of options to be forwarded to rk.XML.plugin ,
to generate the GUI XML file.
Not all options are supported because some don't make sense in this context. Valid options are:
"dialog" , "wizard" , "logic" and "snippets" .
If not set,
their default values are used. See rk.XML.plugin for details.
|
js |
A named list of options to be forwarded to rk.JS.doc ,
to generate the JavaScript file.
Not all options are supported because some don't make sense in this context. Valid options are:
"require" , "results.header" , "header.add" , "variables" ,
"globals" , "preprocess" ,
"calculate" , "printout" , "doPrintout" ,
"preview" and "load.silencer" .
If not set,
their default values are used. See rk.JS.doc for details.
|
pluginmap |
A named list of options to be forwarded to rk.XML.pluginmap ,
to generate the pluginmap file.
Not all options are supported because some don't make sense in this context. Valid options are:
"name" , "namespace" (see also internal ),
"hierarchy" and "require" .
If not set,
their default values are used. See rk.XML.pluginmap for details.
|
rkh |
A named list of options to be forwarded to rk.rkh.doc ,
to generate the help file.
Not all options are supported because some don't make sense in this context. Valid options are:
"summary" , "usage" , "sections" , "settings" ,
"related" and "technical" .
If not set,
their default values are used. See rk.rkh.doc for details.
|
overwrite |
Logical,
whether existing files should be replaced. Defaults to FALSE .
|
tests |
Logical, whether directories and files for plugin tests should be created.
Defaults to TRUE . A new testsuite file will only be generated if none is present
(overwrite is ignored).
|
lazyLoad |
Logical,
whether the package should be prepared for lazy loading or not. Should be left TRUE ,
unless you have very good reasons not to.
|
create |
A character vector with one or more of these possible entries:
"pmap" Create the .pluginmap file.
"xml" Create the plugin .xml XML file skeleton.
"js" Create the plugin .js JavaScript file skeleton.
"rkh" Create the plugin .rkh help file skeleton.
"desc" Create the DESCRIPTION file.
"clog" Create the ChangeLog file (only if none exists).
Default is to create all of these files. Existing files will only be overwritten if overwrite=TRUE .
|
suggest.required |
Logical,
if TRUE R package dependencies in about will be added to the Suggests:
field of the DESCRIPTION file, otherwise to the Depends: field.
|
components |
A list of plugin components. See rk.XML.component for details.
|
dependencies |
An object of class XiMpLe.node to be pasted as the <dependencies> section,
See rk.XML.dependencies for details. Skipped if NULL .
|
edit |
Logical,
if TRUE RKWard will automatically open the created files for editing, by calling rk.show.files .
This applies to all files defined in create .
|
load |
Logical, if TRUE and "pmap" in create ,
RKWard will automatically add the created .pluginmap file
to its menu structure by calling rk.load.pluginmaps . You can then try the plugin immediately.
|
show |
Logical, if TRUE and "pmap" in create ,
RKWard will automatically call the created plugin after
it was loaded (i.e.,
this implies and also sets load=TRUE ). This will only work on the main component, though.
|
gen.info |
Logical,
if TRUE comment notes will be written into the genrated documents,
that they were generated by rkwarddev and changes should be done to the script.
You can also provide a character string naming the very rkwarddev script file that generates this plugin and its main component,
which will then also be added to the comment.
|
hints |
Logical,
if TRUE and you leave out optional entries (like dependencies=NULL ), dummy sections will be added as comments.
|
indent.by |
A character string defining the indentation string to use.
|
internal |
Logical,
a simple switch to build an internal plugin for official distribution with RKWard. If set to TRUE :
The plugin will have its namespace set to "rkward" .
The <about> info will also be available in the main component.
require.defaults of rk.XML.pluginmap will be set to FALSE .
No DESCRIPTION or NAMESPACE file will be written.
|
Value
Character string with the path to the plugin root directory.
See Also
Introduction to Writing Plugins for RKWard
Examples
## Not run:
# a simple example with only basic information
about.info <- rk.XML.about(
name="Square the circle",
author=c(
person(given="E.A.", family="Dölle",
email="doelle@eternalwondermaths.example.org", role="aut"),
person(given="A.", family="Assistant",
email="alterego@eternalwondermaths.example.org", role=c("cre","ctb"))
))
rk.plugin.skeleton(about.info)
# a more complex example, already including some dialog elements
about.info <- rk.XML.about(
name="Square the circle",
author=c(
person(given="E.A.", family="Dölle",
email="doelle@eternalwondermaths.example.org", role="aut"),
person(given="A.", family="Assistant",
email="alterego@eternalwondermaths.example.org", role=c("cre","ctb"))
),
about=list(
desc="Squares the circle using Heisenberg compensation.",
version="0.1-3",
date=Sys.Date(),
url="http://eternalwondermaths.example.org/23/stc.html",
license="GPL",
category="Geometry"),
dependencies=list(
rkward.min="0.5.3",
rkward.max="",
R.min="2.10",
R.max=""),
package=list(
c(name="heisenberg", min="0.11-2", max="",
repository="http://rforge.r-project.org"),
c(name="DreamsOfPi", min="0.2", max="", repository="")),
pluginmap=list(
c(name="heisenberg.pluginmap", url="http://eternalwondermaths.example.org/hsb"))
)
test.dropdown <- rk.XML.dropdown("mydrop",
opts=list("First Option"=c(val="val1"),
"Second Option"=c(val="val2", chk=TRUE)))
test.checkboxes <- rk.XML.row(rk.XML.col(
list(test.dropdown,
rk.XML.cbox(label="foo", val="foo1", chk=TRUE),
rk.XML.cbox(label="bar", val="bar2"))
))
test.vars <- rk.XML.vars("select some vars", "vars go here")
test.tabbook <- rk.XML.dialog(rk.XML.tabbook("My Tabbook", tab.labels=c("First Tab",
"Second Tab"), children=list(test.checkboxes, test.vars)))
rk.plugin.skeleton(about.info, xml=list(dialog=test.tabbook),
overwrite=TRUE)
## End(Not run)