jQuery.fortune

So what am I doing here?

jQuery.fortune is a jQuery plugin that generates random fortune cookies. The intention behind it is to replace backend fortune scripts. There's no need for those anymore.

The following data formats are supported:

Plain text — configurable cookie delimiter.
JSON — configurable file format.
XML — configurable file format (but undocumented).
.DAT (binary fortune format) — unsupported for obvious reasons.

OK, I'm sold. How do I use it?

Assuming a my-cookie-element in your HTML page, call the plugin like this:

$("#my-cookie-element").fortune();

Then, in the same directory, create a file called cookies.txt that looks like this:

Happy? Happy in Paraguay.
%
What do you say we make apple juice and fax it to each other?
%
You and me in Japan. Watch me dance.

my-cookie-element will be populated with a random cookie from cookies.txt.

That's it? What if I want to get fancy?

To use another file, specify a different delimiter, and enable a simple animation, call the plugin like this:

$("#my-cookie-element").fortune({file: "./my_cookies.txt", delimiter: "#####", animate: true});

Even more fancy?

You can use a JSON (or XML) fortune file, but you must supply its path and the name of the cookies node/object, like this:

$("#my-cookie-element").fortune({file: "./my_cookies.json", cookieNode: "cookies"});

In this example, my_cookies.json should look like this:

{
   "cookies":
   [
       "Happy? Happy in Paraguay.",
       "What do you say we make apple juice and fax it to each other?",
       "You and me in Japan. Watch me dance."
   ]
}

But what's the advantage over text files?

Ah! With JSON (or XML), you can specify metadata for each cookie (theIndex, theContent, theSource, and theDate). These attributes are optional: you can specify some, none, or all of them. If you want to do this, call the plugin like this:

$("#my-cookie-element").fortune({file: "./my_cookies.json", cookieNode: "cookies",
    metaNodes: {theIndex: "index", theContent: "content", theSource: "source", theDate: "date"});

In this example, my_cookies.json should look like this:

{
    "cookies":
    [
        {
            "index": 1,
            "content": "Happy? Happy in Paraguay!",
            "source": "Worf, Son of Mogh",
            "date": "29/01/2010"
        },
        {
            "index": 2,
            "content": "What do you say we make apple juice and fax it to each other?",
            "source": "Worf, Son of Mogh",
            "date": "31/01/2010"
        },
        {
            "index": 3,
            "content": "You and me in Japan. Watch me dance.",
            "source": "Captain Jean-Luc Picard",
            "date": "31/01/2010"
        }
    ]
}

When using metadata, my-cookie-element in your HTML should have children with corresponding class names, like this:

<div id="my-cookie-element">
    <div class="index">&nbsp;</div>
    <div class="content">&nbsp;</div>
    <div class="source">&nbsp;</div>
    <div class="date">&nbsp;</div>
</div>

What about XML?

XML works similar to JSON, but it's a bloated format that you should avoid. I'm supporting it for completeness, but I won't document it. It should be trivial to figure out, in any case.

Finally, for a live example, check out the demo.

Who do I blame for this?

Mohammed Badran. Credit to Random Content Generator for the inspiration. Note that I've done minimal testing and error handling, so use at your own risk etc.

Questions? Comments? Write me at mebadran at gmail dot com.