Fortune Cookies Demo Page
The Fortune Cookie is a current side project of mine — a WordPress version of the old Unix fortune cookie program that gives you a quotation or an aphorism (sometimes silly). The plugin stores quotations in a custom MySQL table, and uses the WordPress REST API to retrieve information from the backend.
There are three ways to insert fortune cookies on a page:
- The cookie shortcode inserts a cookie on a page — that’s the easy way to use the plugin.
- Define a View in the Fortune Cookie Settings > Options and Views page, and a matching cookie will appear on any page where the selector matches.
The first two fortune cookies are generated from WordPress shortcodes in the page text, and they have an (optional) Again button that will request a new cookie based on the filters used to create the current one. The first cookie uses the default type ‘quote’, and the second specifies the type ‘aphorism’, loosely defined here as a quote without an attribution. The third cookie is generated from a View defined in the backend, and it will be added to any page where the selector matches a container in the DOM.
There’s a lot of flexibility in determining which cookie shows up at a given location. You can specify: an exact cookie that will always be used; a list of cookies, where one is chosen randomly; random selection from a type. I’m planning to add another selector for keywords used in a cookie, but that’s not built yet. There’s always room for more selectors, and you could even tie into the WordPress tags or categories mechanisms.
This plugin kept generalizing itself as it progressed, so it’s actually a good way to dynamically inject display cards at arbitrary places on a page. I’ve initially defined two types of cookies (‘Quote’ and ‘Aphorism’), and I built an import mechanism that reads a text file of fortune cookies and stores them in a table in the WordPress database. The rendering function that creates the HTML for a given cookie is determined by the type, so you could easily add a new type or change the rendering function for an existing type. You can even assign an image to the cookie through the backend interface.
Backend Administration of the Plugin
After activating the plugin, the WordPress dashboard has a new top-level entry called “Fortune Cookie Settings” with 2 subpages. You can import, view, and edit cookies, as well as manage the actual instances (views) of cookies on pages.
- The Options and Views page lets you manages the actual instances (views) of cookies on the page. It also has the Import mechanism that lets you import cookies from a data file located in the plugin folder (or a subdirectory of the plugin folder).
- The Fortune Cookies page lists all of the defined cookies in the custom table, and allows you to Edit, Clone, or Delete any given entry. This list is paginated — if you import the sample data file, you’ll get almost a thousand entries. You can define the number of entries to see on each page in the previous Options and Views page.
How to place a Fortune Cookie in a Page
There are currently three mechanisms for placing fortune cookies into actual page locations.
- The cookie shortcode will insert a cookie at that location, and it will be there as long as the cookie shortcode appears in the page. You can provide various values as arguments to filter the possibilities, including directly specifying a particular cookie.
- idlist: a CSV list of IDs from the database entries. This overrides any other filters. If you supply a single ID, that entry will be returned every time. If you supply a list of IDs, then a single entry will be randomly chosen from that list.
- type: restricts the choice to a single type. Defaults to ‘quote’, and the sample cookies file also uses type ‘aphorism’.
- keywords: intended to be used to filter by entries that include one of the keywords. Not implemented yet.
- again: the value is either ‘yes’ (the default) or ‘no’. If the value is ‘yes’, then an Again button will be placed in the cookie.
- Defining a View: The Options and Views backend page allows you to define specific Views — the mapping of a filtered set of Fortune Cookies into an actual page location. The selectors for currently defined views are checked whenever a page is loaded while the plugin is active.
Here are some notes about how the plugin works.
- The plugin uses the WP REST API plugin (version 2), so it must be installed before this plugin will work.
- The content for all fortune cookies is stored in a custom table called ‘fortune_cookies’ using the WP-prefix. The table is created using the dbDelta function. Entries do not contain presentational info, just the facts.
- View definitions are stored as a JSON-encoded string in the wp_option called ‘FORTUNE_COOKIE_Initial_Cookies’. I decided against creating a second table for this info, so encoding it into the option is a simple mechanism to store it. If you have a *lot* of entries, this might be too inefficient.
This plugin kept generalizing itself as it progressed, so it’s actually a good way to dynamically inject display cards at arbitrary places on a page. I’ve defined several types of cookies to start (‘Quote’ and ‘Aphorism’). The rendering function that creates the HTML for a given cookie is determined by the type, so you could easily add a new type or change the rendering function for an existing type.
Although currently using WordPress, it would be a simple matter to change this code to use a different storage mechanism or backend administration mechanism.
This is just the first workable draft of the plugin. Planned enhancements include:
- Allow you to specify the length of the content before truncating with an active ellipse for expansion. Currently, a long quote will grow to be as tall as it needs to be.
- Beef up authentication; this just uses nonces.
- Add more REST endpoints to handle Views and manage cookies.
- Make this be a proper WordPress plugin suitable for the repository.
- Add functions to allow definition of custom card types and handlers.
- Add the Keywords filter for selecting fortune cookies.
- Rewrite the backend browser for cookies — I borrowed some old code and didn’t bother to update it.
- Update the date_modified and the rendered count fields for entries as they are retrieved or edited.