gWidgetsWWW-package {gWidgetsWWW} | R Documentation |
Port of gWidgets API to WWW using RApache and the ExtJS javascript libraries.
This package ports the gWidgets API to WWW, allowing the creation of interactive webpages.
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 a small webserver run the the tcltk package. This is modified from that accompanying the Rpad package
The server version requires RApache to be installed and configured.
The webpages themselves use the Ext toolkit (www.extjs.com) to render the widgets. This toolkit must be installed separately and configured to work. A copy of these libraries is included.
As gWidgets is meant to be multi-toolkit, this file documents differences from the API, of which there are many. However, this package is not compatible with the gWidgets package so reading that documentation is best done with a separate R process.
Overview:
The gWidgetsWWW package at one level maps R/ commands to
javascript commands. 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.
Prior to version 0.8.0, gWidgetsWWW used RPad to provide interactivity. This opened up the security risk that RPad has. One can run Rpad from a virtual machine to reduce the risk, but still a user could issue any R command they wanted. The RApache backend end severely limits what a user can request from an R process. Basically they can assign a variable and initiate a handler that a gWidgetsWWW script defines. Still be careful when processing user input, as that can open security risks, as it does with all web programming.
Installation:
To run the local version of gWidgetsWWW no installation is necessary.
Installation for the server requires several steps: a) installing RApache, b)
installing gWidgetsWWW c) configuring RApache for gWidgetsWWW,
d) installing the extjs libraries, e) installing the gWidgetsWWW
icons on the web browsers path and f) creating some webpages
Installing RApache is documented at the RApache website. Installing
gWidgetsWWW is straightforward.
To configure RApache for gWidgetsWWW, a sample configuration is
included in the templates directory. There are several variables to
configure. As well, one can use to show pages one of two ways.
The Ext
libraries are included in the basehtml/ext
directory. Or more recent copies may be downloaded from
www.extjs.com. Ext has a dual-license model, offering an open
source LGPL license along with a per-developer, royalty-free
commercial license. The gWidgetsWWW package makes no
assumptions about where this library is installed, as you configure
it in the RApache configuration, but they must be accessible through a URL.
To complete the installation, the gWidgetsWWW package provides
some stock icons. As with the extjs libraries, these can be installed
whereever, but where they are installed must be specified in the
RApache configuration. These image files are in the basehtml/images
directory.
Web pages can be made in two ways. Either using brew templates to call
back into R to make standalone pages. The Examples directory has a
template and an example. Or, one can use a script to source in R files
where the filename is part of the url the user specifies. This allows
the webpage designer to only use gWidgets commands to produce webpages
– no HTML needed.
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, making 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
package beyond the base and gWidgetsWWW you will need to include
the appropriate require
command 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:
The gwindow
container is treated differently in
gWidgetsWWW than in gWidgets. There can be only one
top-level window, as this maps to a webpage. Subwindows are possible
though. These are constructed with the same constructor, but one
passes in the top-level window to the parent
argument. The
window object is a bit different than other gWidgets
implementations, as the object isn't rendered until the web page is
ready to display. This rendering is done through the print
method. In particular, the visible
argument is ignored. After
rendering, new widgets 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.
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. These are useful for alignment.
Additionally, the addSpring
and addSpace
methods are not
defined.
The gframe
container simply adds a title to a ggroup
instance. This can be adjusted with the svalue<-
method.
The gexpandgroup
container extends the gframe
container
by making the title clickable. When clicked the container will toggle
between a hidden and visible state. When hidden only the title is
visible. This can be done programatically through the
visible<-
method.
The glayout
container lays out its children in a grid. There is
no ability to adjust how a child is layed out in the parent cell
through the anchor
arugment. When adding a child to this
container one specifies the location using the [
method and
specifies the container to the constructor as in this example:
f <- glayout(cont = g); f[1,1] <- (b <- gbutton("hi", cont=f))
The gnotebook
container does not implement all the features
expected. The tab.pos
argument only accepts values of 1 and 3
for top and bottom placement of tabs. The close.buttons
argument is not yet implemented. Adding child components is done by
specifying the notebook object to the constructor's container
argument. When done, the extra argument label
is used to
specify the tab label. The svalue<-
method can be used to set
the tab by index, the names
and names<-
method set the
tab names. The dispose
method deletes the current tab.
Tje gformlayout
widget is used to layout widgets using
glayout
is imlemented.
Widgets:
The glabel
widget has no handler, and is not editable. HTML
markup is allowed, but may not work if not escaped. The
font<-
method can be used to adjust font properties. This
method takes a vector of values with corresponding names being the CSS
property.
The gbutton
widget: Can accept a gaction
object to
define the click handler. Pass in the action to the action
component and NULL
for the handler
argument.
The ghtml
widget shows urls in the window. The url should point
to a basic web page or be HTML formatted text. Some browsers will
process this text before it gets to R, so it may be best to source in
the file that contains HTML formatted text.
The gcheckbox
widget has no method to change the label ([<-
,
names<-
)
The gcheckboxgroup
widget has no [<-
method.
The gradio
widget has no [<-
method.
The gslider
widget has a tooltip that indicates the value of
the widget. The [<-
method to set the values to choose from is not implemented.
The gspinbutton
widget is implemented if Ext 3.0 is
installed. However, the trigger icons may not appear. The widget is responsive to arrow keys to cycle through the specified values. The [<-
method to set the values to choose from is not implemented.
The gedit
widget: The transport occurs on the "blur" signal
– when the focus leaves the widget basically. The gedit
widget does not have the [<-
method. However, if this is
desired (for type ahead) the gcombobox
widget can be used. By
default, this widget has a "trigger" icon indicating to the user
that it looks like a combobox, but this will not be drawn if the
property ..hideTrigger
is set to TRUE
, as in obj
= gcombobox(...); obj$..hideTrigger <- TRUE
. In a similar way, one
can specify "typeAhead" by setting obj$..typeAhead <-
TRUE
. The handler addHandlerKeystroke
returns the numeric
value of the key that is pressed in the key
component of the
first argument, h
. This is supposed to be a UNICODE value. If
one adds the arguments "key='e.ENTER'" (say ENTER could be
BACKSPACE, ..) or "charCode=65", where 65 is "A" or "a" then a check
is made at the browser level before calling back into R.
The gtext
widget: The transport occurs on the "blur" signal –
when the focus leaves the widget basically.
The gimage
widget filename
and dirname
referring
to url's not to local files. There is no handler
defined for
this widget.
The gcombobox
widget has an items
argument which can be
a data vector, or a data frame with one, two, three, or perhaps more
columns. This should have two or more values. If a data vector or
one-column data frame, then it should be a vector of values. If a two
or more column data frame, then the first column will be the value,
the second column (if present) will be used to generate an image. If
the values are identified as URL, or have that class the image will be
downloaded, otherwise it will be assumed to be a character string
identifying a stock icon. Finally, the third column (if present) will
be used for a tooltip. For the real ambitious, the $tpl()
method of the widget can be used to markup the combobox text and
(perhaps) include other columns of the items
argument. The
template should use the names "value","text","iconurl" and "qtip" for
the first four columns, where the "text" column is the "value" column
repeated.
The gcalendar
widget formatting may be unrealiable. The
conversion from Ext to R format for dates may be locale dependent and
this hasn't been investigated.
The ggraphics
widget is a link to the gWidgetsWWW
gcanvas
widget. This is used slightly differently than an
interactive graphics device – how ggraphics
is meant to be
used, but is similar to how a non-interactive device is used. The
canvas grahics device allows graphics to be written using
JavaScript, so they render natively in a canvas widget in a
browser. Not all browsers implement this relatively modern widget.
The gsvg
widget creates a space in a page to use the
RSVGTipsDevice to display graphics within a web page.
The gfilebrowse
widget needs writing
The gtable
widget: when using [<-
to replace values,
indices don't work and when replacing data frame the replacement must
have same number of columns, each with the same type; has no
names<-
method to set column names. Only addHandlerClick
and
addHandlerDoubleclick
are working. The filtering feature
(specified through filter.FUN
say) is not implemented. The
icon.FUN
should return either url's or stock icon names.
The gdf
widget is implemented but limited. The widget
recognizes certain data types and provides different means to edit the
values. However, there is no capacity to add rows or columns. (One
could start with more rows and columns than needed and then trim.) As
the column types come from the items
argument, this must be
provided. The widget does not gracefully handle NA
values
(items[complete.cases(items),]
is used). Thi scan be worked
around, but isn't automated. For numeric values NaN
is
recongized. For character, logical or factors vectors, one could use
"NA"
or ""
. The widget does not show the data frames
row names. One could add these to items
first as a character
vector to edit. and then take them off again.
The gtree
widget needs writing.
The gaction
widget creates "actions" which can be used in
menubars and attached to buttons. The methods svalue<-
and
enabled<-
can be used to set the label and the en/dis able the
items.
The gmenu
widget has no methods to replace or access the
elements of the menu. However, the leaves of the menu items should be
gaction
elements, rather than lists as with the other gwidgets
implementations. This allows one to call enabled<-
to disable,
and svalue
to change the text.
At this time, support for popup menus via add3rdMousePopupMenu
and addPopupMenu
is not implemented.
The gtoolbar
widget is subsumed in the gmenu
widget. The
gaction
constructor can be used to create menubar elements.
The gstatusbar
widget is slightly different from the
gWidgets API, where there is a stack of status messages. The
intial text stays until overridden via an svalue call. Subsequent
svalue calls are transient, lasting for about 10 seconds.
The gseparator
widget only works for horizontal lines, and
simply uses the HR
tag within the ghtml
widget.
The ggooglemaps
widget allows one to integrate google
maps into an application. It is working for the local server, but
may not work on a server install. This constructor is
gWidgetsWWW specific and is documented in its own help file.
Dialogs:
The galert(title = "", message = "", delay=3)
dialog is specific to
gWidgetsWWW. It creates a quick alert that pops down from the
top of the web page. It has a title
and message
argument
for the message and delay
in seconds to specify the time the
dialog appears.
The other dialogs have a parent
argument that must be
specified. This allows handlers, etc. to be registered. Visually, the
dialogs will appear to "pop-up" from the component specified.
The gmessage
dialog produces a modal dialog similar to the
javascript alert
dialog.
The gconfirm
widget works. The handler is called on the
"ok" selection.
The ginput
works. The handler is called on okay. The value of the input component contains the text typed into the box.
As an alternative to gconfirm
and ginput
a subwindow can
be used. These are created by the gwindow
constructor when the
container
argument is specified.
icons:
The funtion getStockIcons
returns a vector of these icons. The
names
of this vector may be used to define icons in some of the
widgets. The return values are url's of the stock icons.
The function addStockIcons
can be used to add to this list. These
should be added before the GUI is rendered so that they will be
available to the GUI's components.
Methods:
The svalue
method should work as with gWidgets.
The svalue<-
method should work as with gWidgets.
The add
method for containers (implicitly called by
constructors) is implemented (but may behave differently) for
containers after they are rendered.
The enabled<-
method is used to disable/enable a widget for
user input.
The dispose<-
method only hides the widget, rather than
destroy the widget.
The focus<-
method should work as expected to set the focus
to the widget.
The visible<-
method should unhide a child widget that was
hidden via dispose<-
. There is no visible=FALSE
state
for widgets when the GUI is initially drawn.
The [
method method for many constructors is not fully implemented.
The [<-
method method likely won't use the i,j indexing arguments
The names<-
method method is only partially implemented.
The size<-
method can be called with either c(width)
or c(width, height)
. The default sizing for many widgets is
"auto", which will fill the width of the page. This will make
horizontal=TRUE
not behave as expected.
The print
method for windows (gwindow) will print out the
javascript to produce the page. This is how a page gets rendered to
the web browser.
The tooltip<-
method will set a tooltip for the widget. The
value may be a string; a character vector; a URL which returns a
string (URLs are
identified by the function isURL
); or a list with components
title
and message
, where the title component is a string
and the message component a character vector.
Handlers:
The interactivity between the web browser GUI and R is provided by
handlers which respond to GUI signals sent when an event occurs. For
instance, when the mouse clicks on a button, a mousedown signal is
sent. The gWidgetsWWW
code – through the essential Rpad
package – allows R/ functions to be used as handlers. These
functions create JavaScript code to update the the web browser. The
gWidgetsWWW package takes the methods of gWidgetsWWW and
produces the JavaScript code, so the R/ programmer need only know
how to program in R.
Handlers in gWidgetsWWW are slightly different than in other
implementations of gWidgets. As with others, the first argument to the
handler, traditionally h
, is a list with components obj
,
referring to the widget; action
, referring to the value passed
into the action
argument; and occasionally others.
Handlers are added to the widget through the handler
argument
of the constructor, or using one of the addHandlerXXX
methods. The constructor assigns a default signal (or more) to bind
the handler to. More control is given by the addHandlerXXX
methods. If you want to bind to a different signal (after having read
the Ext documentation say) the method addHandler
allows the
specification of a signal.
Handlers may not evaluate within the scope of the function, as one would expect. This should be addressed. If not fixed, then one can use global variables within the handler.
Handlers write out javascript to be interpreted by the web browser. No
other output to STDOUT should be inside the handler body. That is,
don't use print
or cat
.
Drag and Drop:
The Ext
library has some built in drag and drop
support. Otherwise, drag and drop is not currently supported.
Compound widgets:
At this time the constructors of the compound widgets
gdfnotebook
, gvarbrowser
, ggraphicsnotebook
,
ggenericwidget
are not implemented.
proto:
The proto package is used as the backend for this package, rather than the gWidgets package. This was done as much for variety than any other reason. The user of gWidgetsWWW need not be aware of this, but it does allow some undocumented access to the underlying widgets.
A few examples. First, many of the widgets have properties that are
set during the construction of the widget, but are not specified by
the arugments to the constructor. This is due to the EXT libraries
having more options, than are given by gWidgets. For instance,
in the gcombobox
function the properties ..hideTrigger
and ..emptyText
can be set. The ..hideTrigger
values is
a logical value, and it TRUE
will render the widget without an
arrow indicating to the user this is a combobox. This can be useful
for setting values that will appear as the user types. In the API for
gWidgets
the [<-
method for gedit
should cause
something similar to happen, but it doesn't. The ..emptyText
argument is there to set the initial text of the box in gray to
suggest to the user what to do.
The double dots are reserved for properties of methods of the widget that are instance specific, hence the funny names.
Another way to modify a widget is to set the method
..ExtCfgOptions
. This should be a function which returns a
list. The named components of the list map to the properties of the
EXT constructor. (See that API for things you may want). These values
will override any others set by gWidgetsWWW. The conversion will
quote values of type character
. If this is undesired, use the
class String
returned by the String
function.
The above two examples set properties of the object. These only effect
the rendering if set prior to rendering. To affect the widget after
rendering, one can create JavaScript to be sent back to the
browser. This can only occur during a handler. Most of the
gWidgetsWWW
methods eventually call a function ending in
JS
. For instance, svalue<-
calls the proto method
setValue
which in turn calls setValueJS
. The latter can
be overridden, or can be added to by setting a method for
..setValueJS
. This should cat
out javascript code.
If you do this, and think your code should be integrated into the main code, please share it.
John Verzani <gwidgetsrgtk@gmail.com>
gWidgets