Package ‘gWidgetsWWW’ July 2, 2014 Version 0.0-23 Title Toolkit implementation of the gWidgets API for use with web pages Author John Verzani Maintainer John Verzani <[email protected]> Depends R (>= 2.11.0), methods, proto, filehash, digest, rjson Suggests Extends canvas, RSVGTipsDevice, SVGAnnotation, webvis Description Port of the gWidgets API to program dynamic websites. Can be used with R's dynamic help web server to serve local files. This provides a convenient means to make local GUIs for users without concern for external GUI toolkits. Also, in combination with RApache,http://biostat.mc.vanderbilt.edu/rapache/index.html, this framework can be used to make public websites powered by R. The Ext JavaScript libararies (www.extjs.com) are used to create and manipulate the widgets dynamically. License GPL (>= 3) URL http://gwidgets.r-forge.r-project.org/ LazyLoad FALSE Repository CRAN Date/Publication 2012-06-09 10:18:19 NeedsCompilation no 1 2 gWidgetsWWW-package R topics documented: gWidgetsWWW-package . .2 gcanvas . 11 ggooglemaps . 13 gprocessingjs . 15 gsvg............................................. 18 gwebvis . 20 gWidgetsWWW-helpers . 21 gWidgetsWWW-undocumented . 22 gw_browseEnv . 22 gw_package . 22 localServerStart . 23 Index 25 gWidgetsWWW-package Toolkit implementation of gWidgets for WWW Description Port of gWidgets API to WWW using RApache and the ExtJS javascript libraries. Details This package ports the gWidgets API to WWW, allowing the authoring of interactive webpages within R commands. The webpages can be seen locally through a local server or viewed through the internet:The local version is installed with the package and uses R’s internal web server for serving help pages. The server version requires the RApache module for Apache to be installed and configured. (More later.) The webpages themselves use the excellent Extjs toolkit (www.sencha.com) to render the widgets. This toolkit is installed with the package. The gWidgets API is meant to be multi-toolkit. For its other implementations (gWidgetsRGtk2, gWidgetsQt, gWidgetstcltk) the main methods are defined in the gWidgets package, with toolkit packages providing the link between the graphical widget library and R. The gWidgetsWWW is different, it is a more-or-less faithful implementation of the API, but this is not enforced by using the gWidgets pacakge. This was chosen, as there are some significant differences between an in- teractive desktop GUI and a webpage. As the differences are not great, this file documents differences from the API. We defer to the gWid- gets documentation for more detail. (However, this package is not compatible with the gWidgets package so reading that documentation is best done with a separate R process.) gWidgetsWWW-package 3 Overview: The gWidgetsWWW package at one level maps R\/ commands to javascript commands. Basically it just pastes together a bunch of javascript commands to send to the browser. A more sophisticated treatment (like pyjamas for python) would compile the R code into javascript, but that does not happen here. This package is a simple mapping. The communication between R\/ and the browser works as follows. Before a page is rendered, it can be constructed using the gWidget constructors and methods. When the top-level window is shown (via its print method), the javascript code to produce the page is created. This javascript code takes advantage of the freely available Ext libraries which greatly enhance the base javascript language. This code should be contained in or sourced into a web page so that it can be rendered in a browser. The gWidgetsWWW package provides several examples of how this works. The interactivity of a GUI is created through httpxmlrequests back to the RApache server. Each page load creates a unique session to store the state. This allows data to be passed from the web page back to an R process and back without needed to reload an entire page. In fact, reloading a page creates a new session. What is missing is a way to initiate a request from R\/ to the web page and then back to R. As such, the state of the web page is constantly passed back to the R\/ session. That is, when a control is updated, such as when a radio button is clicked, there is a call back into R\/ to set that value. This allows handlers in R to be aware of the state of the web page. On the downside, this may cause a lag in performance. Installation: To run the local version of gWidgetsWWW no installation is necessary beyond installing the pack- age. The command localServerStart can be used to load a script. Installation for the server requires several steps: a) installing RApache, b) installing gWidgetsWWW c) configuring RApache for gWidgetsWWW, and d) creating some webpages Installing RApache is documented at the RApache website. Installing gWidgetsWWW is straight- forward. To configure RApache for gWidgetsWWW, a sample configuration is included in the templates di- rectory. There are several variables to configure. The defaults work with a recent version of Ubuntu, so it can be as easy as simply copying the file into the appropriate place for the web server to read it. The Ext libraries are included in the basehtml/ext directory. Ext has a dual-license model, of- fering an open source LGPL license along with a per-developer, royalty-free commercial license. The standard configuration reads these files from where the R package is installed. (This may need adjustment), so no installation is necessary. To complete the installation, the gWidgetsWWW package provides some stock icons in the basehtml/images directory.. As with the extjs libraries, these can be installed whereever, but the default configuration finds them where R installs the package. The author would very much appreciate that a coherent set 4 gWidgetsWWW-package of icons be contributed. Web pages can be made in two ways. Once can use a brew template and call back into R to generate the page. However, it is much easier to write a standalone R script and call that. For local installs, the function localServerOpen is used to open a file. For server installs, the script need only be put into the proper directory. (This is /var/www/gWidgetsWWW in the default configura- tion.) The script is loaded by calling the proper URL, which takes the form: servername/gWidgetsWWWrun/scriptname, where servername is the http:///www.yourhost.com bit, gWidgetsWWWrun is the default name for the invocation and scriptname the file in the directory (or directories) specified to search through. The scripts themselves have a pretty standard structure: there must be a global gwindow instance (corresponding to the main web page, or which there can only be on), gWidgetsWWW commands for layout, and finally a call to the visible<- method of gwindow to print out the javascript com- mands generated by the package. The Examples directory has many examples. (Try localServerOpen("Examples/ex-index.R", pacakge="gWidgetsWWW") to see.) Sessions: gWidgetsWWW uses sessions to store data when a web page is loaded. Sessions are simply R environments. HTML itself is stateless, so some means is necessary to keep track of data between interactions. The use of AJAX allows pieces of a page to be updated without the entire page, mak- ing pages appear much more responsive. This involves callbacks into a R process that are executed within the environment stored for the session. The environments do not remember which packages are loaded, so if your callback requires a pack- age beyond the base and gWidgetsWWW you will need to include the appropriate require com- mand in the callback. Sometimes the database driver will complain. Likely this is due to the database not being locked while a transaction is being completed. The sessions are stored by default in files under a directory using filehash. This has the advantage of being easy to remove using regular cron jobs, but may be slower than other forms of storage. This is all a bit of a hack, so any report of bugs is appreciated. Containers: We now describe implementation of the basic widgets in gWidgetsWWW beginning with the con- tainers. A primary difference in gWidgetsWWW over gWidgets for other toolkits is the restriction to only one top-level window, which maps to the webpage. Subwindows are possible though. These are constructed with the same constructor, but one passes in the top-level window to the parent argu- ment. The window object is a bit different than other gWidgets implementations, as the object is not rendered until the web page is ready to display. This rendering is done through the visible<- gWidgetsWWW-package 5 method. (In particular, the constructor’s visible argument is ignored.) After rendering, new wid- gets can be added but it doesn’t happen by the same process and may not work as desired. To be on the safe side, you can add child widgets and make them not visible to begin. The default handler is assigned to the unload signal which is called when a page is left. One thing to remember, is that web pages in gWidgetsWWW will lose state when reloaded. For windows, only the svalue<- method, for adjusting the title, is defined. There are a few proto properties to adjust the page. The property doLoadingText can be set to FALSE to suppress the "loading" message whenever a handler is being called. The default means of each window being a webpage can be overridden by specifying a value of ..renderTo, as in w = gwindow(); w$..renderTo = "someId" for some HTML object with appropriate id. The ggroup container accepts the horizontal and spacing arguments, but does not use the use.scrollwindow argument (spacing can not be done after rendering with the svalue<- method though). When adding a child component (which is done when a ggroup instance is used as a parent container) the expand argument is not used, nor is the anchor argument of gWidgets.