Creating an automatically updating news page
This is the second article in a series on how to use GitHub pages (the service that hosts this blog) and Cloudant on the BlueMix PaaS to create an automatically updating news section for a blog. The first article in this series is located here.
In this post we will
- Setup Cross Origin Resource Sharing
- Create a Cloudant index
- Build a blog page to access and render those news articles
Cross Origin Resource Sharing (CORS)
Consuming the Cloudant Database as a Service from GitHub Pages requires a few steps to authorize a web browser to access data from Cloudant which is served off a different domain name. Cloudant uses a technology called Cross Origin Resource Sharing or CORS to enable access to Cloudant from my blog. The Cloudant docs for CORS cover in detail how to configure CORS for a variety of usage scenarios.
Setting up CORS on Cloudant
Launch Cloudant Dashboard from your BlueMix account. Once launched, select Account from the left navigation section and then select CORS from the slide out menu.
By default, CORS is enabled but no domains are specified. Add the domains for your blog in the provided text box. Your blogs domain now authorized for CORS requests.
Create a Cloudant index
While still in Cloudant, select Databases from the left navigation section and then select your blog news database. Select the plus sign next to Design Documents then select query index.
In the next screen you can create your index. In our example we want to index the timestamp of the news articles so we can sort and display the last X number of articles. From the supplied default index replace ‘foo’ with ‘timestamp’ and click create index.
With the index created, Cloudant can now be queried for news articles.
Access Cloudant data from GitHub pages
To create our dynamic news page served by GitHub pages we will need to do a few things.
- Create a new top level news page in your Jekyll based blog
Create a top level news page
Add the following YAML front matter to the news page.
Add your new page to the navigation.yml in the _data directory. After adding news, my YAML looked like this:
Here is the content of the news page in its entirety.
There is a lot going on. So, lets break it down by section.
The pure HTML component of this page consists of creating a blank line and creating a div for the script code to update later.
This is the query we are sending to Cloudant. The query consists of a selector, fields and sort section. The selector tells Cloudant to pull documents that have a timestamp field that is greater than zero. The fields section instructs Cloudant to return these specified fields in the result. Finally, the sort section tells Cloudant to sort the results by the timestamp field in descending order.
Cloudant Request Section
This generates the Cloudant request and updates the web page with the results. The request is executed using the jQuery ajax function.
Lets break down all parts of the AJAX request.
The URL for the request is taken from your Cloudant instance. The format is
The data in the authorization header is the base64 encoded Key and Password you created in part 1. To generate this value you take the key and password, separate them with a ‘:’ and then encode them in base64. I used this online encoder for encoding.
The data section takes the query object we created earlier and turns that into a JSON string to send as the query to the Cloudant server.
The success function is run after the Cloudant returns results for the query. Those results are processed through several steps.
- Empty the results div we created earlier
- Iterate over all returned documents
- Add a link with The link text is the title of the article stored in Cloudant and the href if the link to the article
- Add a blank line
- Add the excerpt of the news article from the Cloudant document
- Add a blank line
- In italics, pretty format the date of when the article was created (This uses jQuery date format).
- Add in two blank lines
After you push this up to GitHub Pages you should have an automatically updated news page like this!