gWidgetsWWW2-package: Base class for all Ext objects

In jverzani/gWidgetsWWW2: Toolkit implementation of the gWidgets API for use with web pages

Description

The GComponent class provides the base class for all widgets.

GWidget is the base class for widget objects. See GContainer for the base class for container objects. Both derive from the GComponent class.

This package uses the Rook package of Jeffrey Horner to allow R programmers to easily create interactive web pages from within an R session.

Details

The basic setup of gWidgetsWWW2 involves a set of constructors and S3 methods for manipulating the constructed objects. The constructors return a reference class object. The S3 methods then simply pass arguments along to the appropriate reference class method. Of course, these may be called directly, but for portability of gWidgets code to other toolkits this is not recommended. However, for methods that are only implemented in a given toolkit, such reference method calls becomes necessary and desirable. In documenting the reference class objects just those exposed methods which must be called as reference methods are mentioned.

The GComponent class is used to define methods common to all the widgets. This class also includes methods for processing callbacks. This is different in gWidgetsWWW2. The basic idea is that JavaScript is used to make a callback into the session containing (using the session id to find the correct evaluation environment). Passed along are an object id (to find the signaling object), a signal (to look up the handlers assigned to that object for the given signal) and possibly some extra parameters. The latter are there to bypass the transport calls that are used to synchronize the widget state from the browser with the R session data. These transport calls are asynchronous so may not have been processed when the handler call is processed.

The lookup used above requires each widget to be registered in a toplevel object which is unique to a page. This toplevel object is found from the session id, which then looks up the object from the passed in object id. This toplevel object is passed into a widget via either the container argument or the parent argument. In addition to routing requests to handlers, the toplevel object also is used to send back JavaScript commands to the browser. The method add_js_queue is all that is needed for this. A convenience method call_Ext provides an alternative. For this method one specifies a method name and named arguments that are converted to a JavaScript object to parameterize the method call. Somewhat reverse to this is calling an R object from JavaScript. The method call_rpc is used for this, where in the JavaScript code one uses jRpc to initiate the call and add_public_method to register that an object's method is available to be called in this manner.

Methods related to the handler code are add_handler, invoke_handler, handler_widget, connect_to_toolkit, transport_fun, process_transport, param_defn, before_handler

The basic reference class interface is meant to be implemented by all gWidgets implementations. The forthcoming gWidgets2 will expect that. So gWidgets2WWW – if that ever happens – will use the basic interface, but for now gWidgetsWWW2 does only for the most part.

Installation:

There is a choice of web server. For serving local pages, the Rook package can use R's httpd server.

For serving pages to a wider world one can

* open R's httpd server's port to the wider world (not recommended)

Just call the load_app command on a script and the page will render.

* proxy this through something, like nginx

We follow the steps in J Horner's gist (https://gist.github.com/6d09536d871c1a648a84)

1) install nginx: sudo apt-get install nginx 2) configure nginx by adding this to /etc/nginx/sites-enabled/default (in the servef bit)

location /custom proxy_pass http://localhost:19000/custom;

* run scripts under rapache

For nginx

Methods

add_args(..., overwrite = TRUE)

add new arguments. Will overwrite. Pass in lists of arguments through ...

add_async_javascript_callback(url, callback, data = list(), data_type = c("json", "xml", "html", "script", "text"))

##' add ajax call complete with handler to call ##' ##' @param url url to call. Quote it if it is a string ##' @param callback string containing javascript callback. Might be ##' callRhandler to work with gWidgets. Arguments are data, textStatus ##' and jqXHR. ##' @param data named list of values to pass back to ajax call ##' @param data_type type of data coming back

add_js_callback(signal, callback, ...)

Add a javascript callback. The value of 'this' refers to the object this is called from

add_js_queue(cmd)

Add command to JavaScript queue

add_public_method(x)

Add a method name to the public methods, so that jRpc can call back intoR.

add_R_callback(signal, ...)

Add a callback into for the Ext signal. Return callback idas a list.

before_handler(signal, params)

Hook that can be called prior to observer call. Might be useful to set value without relying on transport call to arrive first. Return value – a named list – is passed to observers as components of h

block_handler(ID)

Block a handler by ID

block_handlers()

Block all handlers.

call_Ext(meth, ...)

Write JavaScript of ext method call for this object. The ... values will be coerced to JavaScript stings through coerceToJSString, allowing the call to be as 'R'-like as possible, e.g.: call_Ext('setValue', 'some value'). Here the string will be quoted through ourQuote. To avoid that wrap within the String function, as in call_Ext('setValue', String('some value')).

call_rpc(meth, val)

The jRpc call back from JavaScript into R passes a method name and arguments to the object. This calls the method

cb_args(signal)

Callback arguments, may be overridden in a subclass

coerce_to(val, ...)

if coerce_with property present, call function on value

connect_to_toolkit_signal(signal, ...)

Connect signal of toolkit to notify observer

destroy()

destroy component

ext_apply(value)

Call ext apply with value a list containing config options. This is called after write-constructor, prior to that call use add_args or arg$append.

flush_js_queue()

Flush commands in JavaScript queue

get_callback_object()

Return object for callback. Defaults to get_id(), but can be subclassed

get_cookies()

Return list of cookies

get_id()

ID of object. There is DOM id store in id property and Ext object id returned by this

handler_widget()

Widget to assign handler to

initialize(container = NULL, parent = NULL, ...)

Initialize widget. @param toplevel required or found

invoke_change_handler(...)

Generic change handler invoker.

invoke_handler(signal, ...)

Invoke observers listening to signal

param_defn(signal)

Define different parameter definitions based on the signal

process_dot_args(...)

Helper function

process_transport(value, ...)

R Function to process the transport. Typically just sets 'value', but may do more. In the above example, where var param = value: this.getText() was from transport_fun we would get the text for value

remove_handler(ID)

remove a handler by ID

remove_handlers()

Remove all observers

set_cookie(key, value)

Set a cookie

set_height(px)

Set height in pixels

set_size(val)

Set size, specified as width or c(width, height) or list(width,height)

set_tooltip(tip)

Set tooltip for widget

setup(container, handler, action = NULL, ext.args = NULL, ...)

Set up widget

set_width(px)

Set width in pixels

transport_fun()

javascript function for transport web -> R. Creates an object param. This is a string to be passed to the javascript queue withing the transport function call E.g. var param = value: this.getText()

unblock_handler(ID)

unblock a handler by ID

unblock_handlers()

unblock blocked observer. May need to be called more than once to clear block

write_change_transport()

Write change handler, instead of transport

write_constructor()

Write out constructor.

write_ext_object(cls, args)

Write out an Ext object converting args

write_transport()

Writes out JavaScript for transport function

initialize(container = NULL, parent = NULL, ...)

Initialize widget. @param toplevel required or found

Author(s)

John Verzani [e-mail]

jverzani/gWidgetsWWW2 documentation built on Feb. 9, 2020, 5:18 p.m.