framework.shinylightFrameworkStart {shinylight}

JavaScript function: Starts the Shinylight Framework, if you want to use it.

Description

The Shinylight Framework allows you to declare all your functions in R and have a nice-looking web front end for your code without having to write any JavaScript.

You should never need to call this function yourself; if you do not provide your own index.html, the default Shinylight one will be used that will call this function on page load.

Using the Shinylight Framework entails calling the slServer function with the interface argument set to list(getSchema=schema), where schema is defined in the following section.

Arguments

options

object [optional] An optional object containing options to modify the behaviour of the framework.

options.createFileInput

function [optional] A function to create an element that uploads a file, as required for toolkit.loadFileButton.

The Schema

It is a list with the following members:

functions

a list of functions (keyed by their names), each of which is a list with the following members:

params

a list of the main parameters the function accepts. The keys are the parameter names and the values are keys into the schema's params list.

optiongroups

a vector of keys into the schema's optiongroups list giving other parameters to this function.

functiongroups

optional: the menu structure for the functions menu. Each item in the list is either a function name (a string referencing a key in the functions list) or a list representing a submenu. Submenu keys are the name to be displayed in the list, which can be overridden in the app.json file's functions object, just like providing localized names for functions.

params

a list of the parameters the functions take, each of which is a list with the following members:

type

either a key into the schema's types list, giving the type of this parameter or the values it can take, or one of a set of standard types:

'b'

Boolean

'f'

Floating point

'u8'

8-bit unsigned integer

'color'

Colour

'subheader'

Vector of settings the user can choose for each column using selectors in the subheader row. This is usually used to select units (for example percent-by-weight versus parts-per-million) for the columns.

data

a key into the schema's data list, giving initial or example data for this parameter.

types

a list of types with keys referened from the schema's params lists's type values. The values are a list with the following members:

kind

Mandatory; one of:

'enum'

Enumeration type

'column'

A column from the input grid

values

A vector of permitted values (only if kind='enum')

factors

Only if kind='enum' and this enum is used as the unit type for some column; a vector of factors to multiply column data by if the unit is changed by the user. Must have the same number of elements as the values vector. For every n, factors[[n]] of unit values[[n]] must be equal. For example, if values=c('mm', 'cm', 'inch') then factors could be c(25.4, 2.54, 1.0).

subtype

Only if kind='column'. The type of data that can be entered into the column. Currenly only 'f' works well.

unittype

Optional and only if kind='column'. The name of an enum type defining the units that the data in this column can be expressed in.

data

A list of initial data with which table columns and controls will be populated. Can be a single value or vector (or list) as appropriate.

optiongroups

A list of option groups. Each one is a set of parameters that can be added as a block to functions that want them. Each element is a list with the following keys:

type

The same as for param's type: either a key into the schema's types list or one of the standard types ('b', 'u8', 'f' or 'color').

initial

The initial value for this option.

There is one special key in the optiongroups list; this is the framework key. This is reserved for options that apply to the framework itself, not to any of your functions. So far, the only option it has is autorefresh=list(type="b", initial=FALSE). You can set its initial value to TRUE if you prefer. If you add this option, it controls whether the GUI has a "Calculate" button (FALSE) or whether the output should refresh a second or two after the user finishes changing parameters (TRUE).

Localization

To display human-friendly text on the controls and to get tooltip help text, you need one or more localization files. These files are named inst/www/locales/XX/app.json where XX is replaced with the appropriate ISO language code.

These files are JSON files containing an object with the following keys:

title

Text for the link to put in the top left

homepage

Destination for the link to put in the top left

functions

One pair of translations for each function in the schema.

params

One pair of translations for each parameter in the schema.

optiongroups

Each of the optiongroups in the schema gets a key which maps to an object which has the following keys:

@title

A translation pair for the option group itself.

...

One translation pair for each option in the group.

types

One object for each 'enum' type in the schema. Each value is an object with one key per possible enum value. Each value in this object is that enum value's translation pair.

A "translation pair" is an object with the following keys:

name

A short name

help

Tooltip text

See Also

toolkit.loadFileButton