From 2617e929844f1c4be10220bdaaeaf83dc29e6b51 Mon Sep 17 00:00:00 2001 From: Bart6114 Date: Thu, 6 Apr 2017 18:20:55 +0200 Subject: [PATCH] refactor docs --- docs/articles/index.html | 2 +- docs/articles/jug.html | 38 +++++++++++++++++++------------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/articles/index.html b/docs/articles/index.html index 2cf6850..089a9e3 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -84,7 +84,7 @@

All vignettes

diff --git a/docs/articles/jug.html b/docs/articles/jug.html index fccbf48..03128da 100644 --- a/docs/articles/jug.html +++ b/docs/articles/jug.html @@ -5,7 +5,7 @@ -Getting started with Jug • jug +Getting started with jug • jug @@ -54,7 +54,7 @@
-

Getting started with Jug

+

Getting started with jug

Bart Smeets

2017-04-06

@@ -63,7 +63,7 @@

2017-04-06

-

generated using Jug version 0.1.6

+

generated using jug version 0.1.6

Hello World!

@@ -79,9 +79,9 @@

-What is Jug?

-

Jug is a small web development framework for R which relies heavily upon the httpuv package. It’s main focus is to make building APIs for your code as easy as possible.

-

Jug is not supposed to be either an especially performant nor an uber stable web framework. Other tools (and languages) might be more suited for that. It’s main focus is to easily allow you to create APIs for your R code. However, the flexibility of Jug means that, in theory, you could built an extensive web framework with it.

+What is jug? +

jug is a small web development framework for R which relies heavily upon the httpuv package. It’s main focus is to make building APIs for your code as easy as possible.

+

jug is not supposed to be either an especially performant nor an uber stable web framework. Other tools (and languages) might be more suited for that. It’s main focus is to easily allow you to create APIs for your R code. However, the flexibility of jug means that, in theory, you could built an extensive web framework with it.

@@ -95,16 +95,16 @@

-The Jug instance

-

Everything starts with a Jug instance. This instance is created by simply calling jug():

+The jug instance +

Everything starts with a jug instance. This instance is created by simply calling jug():

jug()
## A Jug instance with 0 middlewares attached
-

Jug is made to work closely with the piping functionality of magrittr (%>%). The configuration of the Jug instance is set up by piping the instance through the various functions explained below.

+

jug is made to work closely with the piping functionality of magrittr (%>%). The configuration of the jug instance is set up by piping the instance through the various functions explained below.

Middleware

-

In terms of middleware, Jug somewhat follows the specification of middleware by Express. In Jug, middleware is a function with access to the request (req), response (res) and error (err) object.

+

In terms of middleware, jug somewhat follows the specification of middleware by Express. In jug, middleware is a function with access to the request (req), response (res) and error (err) object.

Multiple middlewares can be defined. The order in which the middlewares are added matters. A request will start with being passed through the first middleware added (more specifically the functions specified in it - see next paragraph). It will continue to be passed through the added middlewares until a middleware does not return NULL (note: if a value is set using e.g. res$json("foo") the body will not be NULL). Whatever will be passed by that middleware will be set as the response body.

Most middleware will accept a func or ... argument to which respectively a function or multiple functions can be passed. If multiple functions are passed; the order in which they are passed will be respected when processing a request. To each function the req, res and err objects will be passed (and they thus should accept them).

@@ -175,7 +175,7 @@

Including elsewhere defined middleware chains

-

In order to make you code more modular, you can include elsewhere defined middleware chains into your Jug instance. To do this you can use a combination of the collector() and include() functions.

+

In order to make you code more modular, you can include elsewhere defined middleware chains into your jug instance. To do this you can use a combination of the collector() and include() functions.

Below a collector is defined locally (in the same R script) and included.

 collected_mw<-
     collector() %>%
@@ -207,7 +207,7 @@ 

 

 

 Error handling

-
A simple error handling middleware (simple_error_handler / simple_error_handler_json) which catches unbound paths and func evaluation errors. If you do not implement a custom error handler, I suggest you add either of these to your Jug instance. The simple_error_handler returns an HTML error page while the simple_error_handler_json returns a JSON message.

+
A simple error handling middleware (simple_error_handler / simple_error_handler_json) which catches unbound paths and func evaluation errors. If you do not implement a custom error handler, I suggest you add either of these to your jug instance. The simple_error_handler returns an HTML error page while the simple_error_handler_json returns a JSON message.

 
jug() %>%
   simple_error_handler() %>%
   serve_it()

@@ -223,12 +223,12 @@ 

   </body>
 </html>

If you want to implement your own custom error handling just have a look at the code of these simple error handling middlewares.

-

Please note that generally you would like the error handler middleware to be attached to the Jug instance after all other middleware has been specified.

+

Please note that generally you would like the error handler middleware to be attached to the jug instance after all other middleware has been specified.

Easily using your own functions

-

The main reason Jug was created is to easily allow access to your own custom R functions. The convenience function decorate is built especially for this purpose.

+

The main reason jug was created is to easily allow access to your own custom R functions. The convenience function decorate is built especially for this purpose.

If you decorate your own function it will translate all arguments passed in the query string of the request as arguments to your function. It will also pass all headers to the function as arguments.

If your function does not accept a ... argument, all query/header parameters that are not explicitly requested by your function are dropped. If your function requests a req, res or err argument (or ...) the corresponding objects will be passed.

say_hello<-function(name){paste("hello",name,"!")}
@@ -248,7 +248,7 @@ 

   serve_static_files() %>%
   serve_it()

The default root directory is the one returned by getwd() but can be specified by providing a root_path argument to the serve_static_files middleware. It transforms a bare / path to index.html.

-

Aside from development, I do not recommend using Jug to serve static files.

+

Aside from development, I do not recommend using jug to serve static files.

@@ -387,7 +387,7 @@

-Starting the Jug instance

+Starting the jug instance

Simply call serve_it() at the end of your piping chain (see Hello World! example).