Custom Quote of the Day widget for WordPress

This post is a tutorial for creating a custom Quote Of The Day (QOTD) widget for WordPress. The real motivation for this tutorial is to demonstrate AJAX with jQuery.  Also, the details provided in this post are biased towards WordPress, however the principles could be applied to a wide variety of applications.  All you really need to get started is a web browser (and patience ;-) ).

Before you begin

This tutorial assumes the following:

  • You’re a WordPress administrator
  • Your WordPress site uses jQuery

For non-WordPress users, the last section shows how to incorporate the widget in any web site.

Let me tell you a story

Here is the user story for the QOTD widget:

As a site user, I would like to see a Quote of the Day on each page.

The Design

To implement the feature, we will use a WordPress widget that can be added to the site theme.  Here is a bird’s eye view of the widget:

  • A web service will provide a quote.
  • A client-side script will get the quote, format it, and display it to the user.
  • A WordPress text widget will run the client-side script.

The Details

Now that the overall “design” has been outlined, we can concentrate on the details.

At your service

The core of our widget is the quote web service.  The requirements for the service are:

  • Simple to implement on a WordPress site.

Create a folder called api at the root level of your site folder.  This folder will be the home of your site’s web services.  For example, this site uses http://jpmec.com/api/ as the root folder for its web services.

Create a file called qotd.txt in the api folder.  This file contains the quote data.  Edit the file with a text editor and add the lines of text shown below.

"Eureka!" : "Archimedes"
"Knock, knock" : "unknown"

The quotes in qotd.txt are formatted with the quote on the left in double quotes and the author on the right.  The quote and author are separated by a colon.

Create a file called qotd.php in the api folder.  This script provides the quote service.  The script is written in PHP because WordPress is written in PHP, so using the script with WordPress is simple.

<?php
$lines = file('qotd.txt');
$line = $lines[array_rand($lines)];
echo '{'.$line.'}';
?>

The script does three things.  It loads the qotd.txt file into an array, where each line is an element in the array.  Then a random line is picked from the array.  Finally, the line has opening and closing braces { } added and is echo’ed to the user.  Note, that after the opening and closing braces are added to the quote line, it becomes valid JSON.

  {"Eureka!" : "Archimedes"}

A service call

After the qotd.php and qotd.txt files have been created, you can test the service with a web browser, simply by typing the script path in the browser address bar.  For example, here is a link to the qotd service on this site.

http://jpmec.com/api/qotd.php

When you click on the link above, you should get a new browser window with a random quote in JSON format.

Our client’s request

Once the service is working, we can move on to the client side of the widget.

Create a file called qotd.js in the api folder.  This script file will contain a JavaScript function to make the web service request, format the response and insert it into the document.

function quoteOfTheDay(id, callback) {
	jQuery.get('http://jpmec.com/api/qotd.php', function (response) {
		var quote = jQuery.parseJSON(response);
		for (var saying in quote) {
			jQuery(id).html("<quote>" + saying + "</quote><br/><cite>" + quote[saying] + "</cite>");
		}
		callback();
	});
};

The JavaScript function above uses jQuery to get the data from our qotd.php service and parse it as JSON.  The result is a JavaScript object with one attribute.  jQuery is also used to insert the formatted HTML into the element (or elements) with matching ‘id’.  Here is a link to the qotd.js on this site:

http://jpmec.com/api/qotd.js

Which widget is it?

Now that we have a web service in place, and a JavaScript function to render the data provided by the service, we can make a WordPress widget.

Log into WordPress and go to the wp-admin page.  From there, open the Widgets page in the Appearance section.  Find the “Text” widget in the Available Widgets area and drag it to an appropriate Widget Area.  (For example, I put the Quote Of The Day widget in the upper right corner, below the site search box.)  Give the new widget a title, and in the text area, put the following code:

<div id="qotd" style="display:none"></div>
<script src='http://jpmec.com/api/qotd.js'></script>
<script>jQuery(function() {
	quoteOfTheDay('#qotd', function () {
		jQuery('#qotd').slideDown('slow');
	});
});</script>

This will insert a <DIV> element with an id of ‘qotd’ that is initially hidden.  It will then load the qotd.js script.  Finally, it will call the quoteOfTheDay() function passing in ‘#qotd’ as the id.  An unnamed function is also passed to quoteOfTheDay as a callback.  This function is executed after the quote is retrieved from the web service and the <DIV> block is updated.  The callback will show the quote using the jQuery .slideDown() animation.

Try It

An example of the Quote Of The Day widget is shown on this site. However, you don’t have to use the script in a widget. It can be used anywhere a script can be inserted into HTML. For example, click here to display a quote below.


The interesting part of the example above is that each time the user clicks on the hyperlink, new data is requested from the service and displayed in the page. But, the page didn’t have to reload! This is the essence of AJAX programming.

The End

That’s it!  Hopefully, you now have a Quote Of The Day widget on your WordPress site, or maybe you just learned a little about jQuery and AJAX.

… wait, what was this tutorial about?

This tutorial showed how to:

  • Create a web service using PHP.  The service provides a Quote Of The Day in JSON format.
  • Create a JavaScript function that renders the service content for the client.  The JavaScript function uses jQuery to dynamically insert content into a web page via AJAX.
  • Incorporate the JavaScript function into a WordPress widget, or any HTML page.