[This article was first published on rapporter, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
It’s been a while since you last heard from Rapporter, and we came up with a (hopefully) good excuse for our absence from the blogosphere: Rapplications. To demystify: we developed an API that allows you to create dynamic reports by using the R templates and datasets available on Rapporter. All you need is an account on Rapporter (you can get it here) and of course an access to some templates and datasets in there.
Once you’re logged in click on Settings > Rapplications > New, or simply visit this link. You should see a form similar to this one:
New Rapplication form
Title and Description fields are pretty self-explanatory. In the Referer field you can add newline-separated list of Ruby regular expressions to restrict access to your Rapplication from a desired set of URLs, while blank field (default) sets no restrictions. Proceed and select a Template and optionally a Dataset if the template could use one, then click on Create Rapplication.
In Output format field you can choose between various document types – currently we support: PDF, DOCX, ODT, HTML, and partial HTML (which returns just rendered report, and not the full HTML page). If everything goes fine, a new Rapplication will be created, a unique Token will be assigned to it, and you’ll see something like this:
In case you want some instant gratification, you can grab the code from the bottom of the page and include it in your website. Once you do that, HTML form will be rendered, so that you can map inputs defined in the template against the variables available in the dataset. Try out the live form below and generate your report (or visit the page directly if your RSS reader blocked the part):
So go ahead and provide required inputs, click on Show report when you’re done, and depending on the dataset size and calculation complexity, you’ll be soon served a report in the desired document format. And for that one to happen, you don’t even need to be logged in Rapporter. Pretty neat, huh?
But that’s just a convenience wrapper with a clickity-click user interface. We’re pre-populating the form inputs with the appropriate dataset variable names and/or input values, so you don’t have to.
Anyway, remember that there’s an API behind this? PoweR useRs, stay tuned, you may like what comes next.
The Token assigned to your Rapplication is the crucial piece of information needed for further hacking (d’uh). Once it’s created, Rapplication saves selected dataset and template under the unique token. If you know the names of inputs, you can easily send POST/GET request via cURL or your preferred REST tool to generate rendered reports in the desired document format. For instance, if your template has numeric variable inputs x and y, and your dataset has variables a and b to match the given inputs, you can send GET request like this (assuming, of course, that you have provided a correct Token value):
Output format can be omitted from the request query, and in that case Rapplication-defined value is used (defaults to PDF). Currently valid output_formatvalues are: pdf, docx, odt, html, and html-partial.
And a note of caution: before you Rapplicate, please make sure that your referer URL matches the defined rules (if any) – it’s a common pitfall, at least from our experience.
You can also send POST request and shove the parameters in the BODY instead. Here’s an example with cURL, we’ll be using Beta distribution template, pass some inputs and get ODT file as a result:
Upon successful request, output file will be sent with response code 200, and in case of query error (e.g. incorrect Token or parameters), response code 400 will be returned along with the fancy error notice (though not as fancy as GitHub’s Star Wars flavoured Octocat).
S’il vous plaît, we hacked in a plain HTML form for you. Please choose a variable from the well-know mtcars dataset and click on the Show me the report! button.
If you’re interested, here’s the source of previous form:
As you can see, it’s pretty straightforward to roll your own stuff, just make sure to add a proper token value in the hidden input, and hunt down the appropriate dataset input values. Once again, we’re doing that for you in our bundled solution, but feel free to play with it. And please don’t break it, or if you do, let us know!
You can check out the source of the template used in this demo on GitHub and Rapporter too. Feel free to fork the templates either on GitHub or Rapporter (we recommend the latter), and subscribe to our blog or follow us FB/G+/Twitter to be notified about new Rapplications.
To leave a comment for the author, please follow the link and comment on their blog: rapporter.