Qb-ui-components NPM

QB UI Components

QB UI Components is intended to be a library containing HTML components for use in HTML and Shiny apps (as HTMLWidgets). Example HTML components can be seen Building out to Shiny will create a lib called qbUiLib, which can be used for adding flashy HTML goodness to a dull and dreary Shiny app. To use a component in a Shiny app, there is no need to compile the code locally, you should be able to follow the instructions in installing Shiny R Package to use the compiled code.

App Dependencies

NodeJS, which is used for installing dependencies via NPM

SASS, which is used as a pre-processor to help structure CSS.

Instructions.

Once the app has been cloned, run the command npm install to install all the javascript dependencies.

Build commands

npm run serve will build the source and expose the examples folder on a local server at http://localhost:3000. This is generally the task to be used for developing components locally, as any changes in the source will automatically be reflected in the rendered output through the webpack hot reloader (refreshing the content without the need to refresh the browser window)
npm start will build the Javascript source into examples/bundles and expose the examples folder on a local server at http://localhost:5000 (a simple express webserver). This is used for serving up the files on the QuantumBlack Dokku server
npm run docs will build the ESDocs documentation, building to the docs folder in the root of the project
npm run build-shiny will build the qbUiLib rStudio project and library into build folder in the root of the project.
npm test will run the Javascript unit tests for components

Installing Shiny R Package

The R package can be installed by running this command at an R prompt (replacing with the wifi password):

Installing as Javascript dependency

To install the component library as a javascript dependency in another project, run the command npm install git+ssh://git@bitbucket.org/quantumblack/qb-ui-components.git --save from the command line.

install.packages("QbUiLib", repos="https://qb:<wifipwd>@shinyr.quantumblack.com/Rpkgs/", type="source")

Publishing updates

To build the components, first run npm run build-shiny to build the library into the build folder. This will contain an R project file, which can be used to build the package.

To publish updates to the Shiny Server, you need to mount the source folder from the Shiny Server on your local filesystem. This can be done by following the instructions on QBlib on Confluence.

App structure

/src HTML, JS, CSS (SASS) source

/examples Examples of how to implement components

/templates File templates to be used within build process (mainly for R)

Creating a new component

To create a new HTMLWidget component, create the component's folder in src/components/ (see src/components/qbAutocomplete for an example). In the component folder, create the [componentName].jsx and [component-name.scss] files and add an entry.js file.

The compilation process for HTMLWidget components searches through each folder in src/components and finds every folder with an entry.js file.

The entry.js file should expose publicly accessible setData, getInputs and getOutput function (see src/components/qbAutocomplete/entry.js for an example). There is a template entry.js file in the templates folder.

A component must be have an entry in src/data/bindingData.json, which specifies the inputs (from R to HTML) that are expected to be received in the setData function and the outputs that the component will fire back to Shiny.

In order to test a component, it may be helpful to add a folder in the examples folder, to render the component into an HTML page. Adding a subfolder into examples will automatically be indexed when running npm start, so that hitting http://localhost:3000 in the browser will display an index page, showing every component for which there are example HTML pages. It may also be helpful for both yourself and other developers to create a Shiny example in the examples/R folder.