rk.plugin.skeleton: Generate skeletons for RKWard plugins

In rkward-community/rkwarddev: A Collection of Tools for RKWard Plugin Development

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="[e-mail]", role="aut"),
    person(given="A.", family="Assistant",
      email="[e-mail]", 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="[e-mail]", role="aut"),
    person(given="A.", family="Assistant",
      email="[e-mail]", 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)

rkward-community/rkwarddev documentation built on May 9, 2022, 3:02 p.m.