README.md

In good-marketing/RGhost: R wrapper for Ghost blogging api.

Ghost

Ghost is a simple, powerful publishing platform that allows you to share your stories with the world. Ghost is a kickstarter funded project which is growing rapidly. The source from Ghost is available to run on your own server, different hosted alternatives exists as well.

Purpose of RGhost

While Ghost is great at writing and publishing content, there is /was no easy way to integrate code, examples and grpahs from R into blogposts. The RGhost package and its shiny implementation aims to help R users create an easy workflow from idea, to analysis to publising content.

Ghost API: UNDER DEVELOPMENT

Ghost is under heavy development and the team is pushing out new features an a rapid pace. This is also true for the Ghost api. As of now there is no official release of the api. The documentation is scarce but can be found on the forums and here. I'll make a best effort to keep the package up to date with the developements as they are rolled out.

The current implementation is based on Ghost version 0.5.7.

RGhost code

The current package is an clear alpha, the following features need to be implemented improved:

• [ ] Update secuirity of storing passwords
• [ ] Error handling
• [ ] Implement adding, updating tags for new and existing posts
• [ ] Implement uploading pictures with posts

Installation

Please use the devtools package to install the latest version from RGhost devtools::install_github(goodmarketing/RGhost).

NOTE

RGhost has only been tested with a self-hosted version. Technically it should work with the hosted versions of Ghost.

Usage

Please see the help documentation in the package itself.

Authentication

• Authentication is based on username and password. There is no official release yet for Oauth for Ghost).Once the Ghost API officially will be released Oauth will be implemented.See here for the initial details.
• Note: Ghost locks down for one hour if to many false authentication request have been made. If you control your own ghost installation you can restart the instance and authenticate again.

Get operations

• Get all posts (published and draft)
• Get all users / Get current user
• Get all tags

(Blog)post operations

• Create new posts
• Update existsing post
• Delete a post

RGhost: Shiny Application

Introduction

The RGhost shiny application is a web application which provides an easy way to combine markdown & R code and publish to Ghost. RGhost shiny application is based on editR by Simon Garnier.

editR is a basic Rmarkdown editor with instant previewing of your document. It allows you to create and edit Rmarkdown documents while instantly previewing the result of your writing and coding. It also allows you to render your Rmarkdown file in any format permitted by the rmarkdown R package

Installation RGhost shiny application

Before you install the applicatin you can give it a try on shinyapps. In order to run the RGhost shiny application the following packages are required:

Required packages

• shiny
• shinyBS
• shinyAce
• shinyFiles
• shinyStore
• shinybootstrap2
• rmarkdown
• knitr

Run the RGhost shiny application

To launch the application load the RGhost library library (RGhost) and run the following command

library (RGhost)
launch_rghost_app()

Usage

RGhost extends editR by the ability to post, update and delete content. The most prominent features of the Ghost blogging platform are implemented. Users can create status pages, edit drafts, mark a post as featured, add and remove tags and provide a cover image for a blog post.

Implementation of the Ghost feature may depend on the chosen theme. For example how the image property used per post depends on the ghost theme used.

Login

Login requires the Ghost admin username (email) and password. Using the shinyStore package it is possible to save the credentials for later use. Also supply the url (inc http://) to the shiny application.

1. Fill out your login information.
2. Click the Save button. This stores the information for future sessions.
3. Click the Connect button.

You are now ready to interact with the Ghost blogging platform.

Note The current implementation is not secure and your credentials are send over http and stored as is. Future feature will support hashed passwords for storage and Oauth 2.0 implementation which uses SSL/TSL.

Working with files

Thanks to editR you can work with files (currently there is now way to create a new file from the application.) You can open and save existing Rmd files. To view your file in HTML format hit the render button. A new window will open showing you a html version of your content.

NOTE: On shinyapps.io the home directory is a relative directory (posts), which is publicly available.

Post a new post

Write your content in (R) markdown and use the left hand options to set the properties of the post.

Most field are self explanatory, but a number of notes

• Url: you can determine the url of the post. Ghost accepts any type of string and converts it to a valid url.

• Image: for the image property to work you need to full link to an online image. Currently uploading is not supported (yet).

• Tags: you can select multiple tags.

• Feature : depending on the Ghost theme applied the feature property is used to provide a post a prominent position on the homepage.

NOTE

The application stores an Rmd file the first time you publish a post in the 'posts' directory. As the RMarkdown is parsed by knitr and then Ghost the original r code you write will be converted. Storing an Rmd file allows for retreival of the R code.

Markdown Content

You can use regular markdown to style your blogposts, the preview allows you to see the results immediatly.Ghost will convert the markdown to proper HTML for you, once a blogpost is published or updated. You can also incorporate html tags.

Running R code

The best feature of the application is the ability to mix content with R code. Check out the R Markdown documentation for a run down of the possibilities.

Please note once content is converted from RMarkdown to Markdown, the original r code is converted in markdown and cannot be editted anymore.

• A workaround is to set the echo property on the r code chunk to true. This option will include the r code in a code box and the r code will be included in your blogpost. I'd recommend using this option when you are editting draft posts, depending on your preference you may or may not want to include the source code.

• Another method to preserve the r code is to open an Rmd file in the editor and save the file once you are done, and only post it to ghost once you are completly done with the post.

A couple of highlights

Charting

An important feature of any data driven blogpost are charts. By added chart to an R chunch you can now easily integrate charts into your blogposts. I'd recommend one of two ways to do this

Plotting using standard plotting libs.

Create any chart you want in an r chunk, you can use the r chunk options to control size, code preview etc.. It will be displayed in the preview window, so you can review it in real time. Using one of the awesome features of knitr, any chart /figure will be automatically uploaded to imgur. See knitr for more information and an img tag including url is added to the markdown code. Ghost also allows image uploads, a custom hook to the knitr package could be created to upload images to your Ghost account. This feature is currently on the to do list. Here is an example using ggthemes.

# Load libraries

library("ggthemes")

(qplot(hp, mpg, data = subset(mtcars, cyl != 5), geom = "point", color = factor(cyl)) + 
    geom_smooth(method = "lm", se = FALSE) + scale_color_fivethirtyeight() + 
    theme_fivethirtyeight())

Interactive plots: rCharts & rMaps

Since your readers will be viewing your content online you can take advantage of interactive graphing libraries such as the great rCharts and rMaps by [Ramnath Vaidyanathan] (https://github.com/ramnathv).

mr Vaidyanathan defines two options for integrating rCharts in R Markdown. I found that using an Iframe to display the chart works best with Ghost. Here is an example using highcharts. Please note that the chunck options need to be set as follows, for the chart to render properly:comment = NA, results = "asis", tidy = F

library(rCharts)
h1 <- Highcharts$new()
h1$chart(type = "spline")
h1$series(data = c(1, 3, 2, 4, 5, 4, 6, 2, 3, 5, NA), dashStyle = "longdash")
h1$series(data = c(NA, 4, 1, 3, 4, 2, 9, 1, 2, 3, 4), dashStyle = "shortdot")
h1$legend(symbolWidth = 80)
h1$set(width = 800)
h1$show('iframesrc', cdn = TRUE)

iframe.rChart{ width: 100%; height: 400px;}

In a similar fashion you can create interactive maps using the rMaps package

library(rMaps)
map <- Leaflet$new()
map$setView(c(52.36, 4.90), zoom = 5)
map$tileLayer(provider = 'Stamen.Watercolor')
map$marker(c(52.36, 4.90), bindPopup = 'Hi. Welcome to Amsterdam')
map$set(width = 800)
map$show('iframesrc', cdn = TRUE)

iframe.rChart{ width: 100%; height: 400px;}

Tables

Currently Ghost does not support markdown tables. There are probably more than one ways around this, my current most convenient solution is xtable.

If you produce a table in a R chunck you can use the following to publish this to Ghost

a <- head(cars) #Your results

library(xtable) # Load xtable library
tab <- xtable(a) #xtable your results

# Styling table using css
print(tab, type="html",html.table.attributes='class:mytable') # print them to html. Ghost accepts standard html in markdown.

speed dist 1 4.00 2.00 2 4.00 10.00 3 7.00 4.00 4 7.00 22.00 5 8.00 16.00 6 9.00 10.00

# Styling table using html properties
print(tab, type="html", html.table.attributes = list('border="0" bgcolor="#FFCC00" cellpadding="10"'))

speed dist 1 4.00 2.00 2 4.00 10.00 3 7.00 4.00 4 7.00 22.00 5 8.00 16.00 6 9.00 10.00

TIP: if you use html.table.attributes and set the table class attribute you can style you output tables with CSS. Usually Ghost themes have a class for styling table, so if you set it to this class all you tables will be outputted in the same format.

Update a post

Get existing posts

In order to update an existing post you need to get them from ghost. Currently all posts (draft and published) will be loaded and a selectbox will be displayed.

You can type in the select field to find the post you are looking for.

Update

Edit the post content and properties and hit update. Upon success a message will be displayed.

Delete a post

Select a post you want to delete and hit the Delete button. (Be careful deletion is permanent).

good-marketing/RGhost documentation built on May 17, 2019, 7:42 a.m.