In previous posts I talked about wanting to avoid using the HTML editor. There are 3 parts of the report that cause me pain. Here’s a snippet of the last Beer Pairing Dinner report I wrote (now taking advantage of ONE of the shortcodes that was created):
[course name="First Course" grade="B"]
|Beer: B||Food: A-/B+|
This course paired Harp with seafood – Scallop. The scallop was perfectly seared and served on top of lightly toasted Brioche. The sauce lining the plate was a Peach & Lemon Jam with some Mizuna. This course, being the first, was viewed tentatively – was it going to be the best of the night or portend a much better evening. The scallop was perfect, but the brioche was a little boring (maybe it was supposed to be?) and the mizuna was like spinach without much flavor. It was a fine tasting meal, but the crispness of the Harp tended to overpower all of the flavors other than the peach jam (which was delightful). One last thought – it was like a combination of breakfast (jam on toast) with a nice dinner appetizer. A little odd but the scallop was absolutely perfect.
There are 4 painful things in just that snippet that caused me to use the HTML editor:
- The Part Grade Header – Done in plugin v0.1 ([course])
- The Beer/Food picture combo
- The indented paragraphs
- The undefined word (with link to definition)
(One other area, the final grade table, is also painful but it’s not in that snippet.)
As noted, the section grade header is done. Now we’re going to tackle 3 of those 5 problems (the 4 in the snippet and the bonus one) – the picture combo, the undefined word, and the final grade – with shortcodes. This post covers the Beer/Food grade/picture table.
Dissecting that construct, we see fixed parts and variable parts. Shortcodes are good tools for encoding the fixed bits (so the post writer doesn’t have to) and supporting the varying parts.
I tried a bunch of different ideas until I landed on the one I’ll be showing below.
The first thought was to put it all on one line, like I did for [course]. The problem with that idea was that that one line got complicated – look at all the varying parts: There’s the grade, the picture (or lack of picture; more coming on that), and the caption (or lack of caption; more coming, I promise). Oh, did I mention that all of that has to show up twice, once for beer and once for food? Right. Yes, I agree, it’s a bit much. *flush*
Version 2 says: Ok, let’s not do that, instead let’s tackle half of the problem: just code it up for ONE of the columns, repeat it on another code, and have a table appear with that content. Well… splitting it by column is a good idea – within a column, the grade, the picture, and the caption all apply to the same thing. But tables in HTML consist of rows, not columns! Somehow we have to figure out that those columns belong to the same table and arrange it by row. *flush* (but remember that column idea – it’s only half bad).
Version 3 says: Ok, let’s split the problem a different way – we can have a code that represents the TABLE (and it’s rows), with content that represents the columns. Make the shortcode handler function deal with translating between columns and rows. Hmm. The notion of writing code to solve the structure problem is the reason for shortcodes, and splitting between 2 kinds of shortcodes (one that handles a column and a second one that handles the table) seems good. Let’s go down that path.
Here’s what I came up with, following the 3rd idea: Two shortcodes, [pairing] and [pairgrade] (I’m not sure I’m completely on board with the names, but they’re OK for working with). A pairing is the table with 2 rows, the first row being grades and the second row being pictures, comprising some set of pairgrades. A pairgrade is a column in a pairing table, with 2 pieces of information: a grade and some other content (maybe a picture, maybe nothing). Here’s an example of what it would look like to write a post using these shortcodes, representing the same table as the snippet above.
[pairgrade name="Beer" grade="B"]
[caption ...]<a href="..."><img .../></a>[/caption]
[pairgrade name="Food" grade="A-/B+"]
[caption ...]<a href="..."><img .../></a>[/caption
The content between [pairgrade] and [/pairgrade] is created using the existing Visual editor mode means to insert an image with a caption, so I won’t spend too much time on it. The code that implements the shortcodes outputs the same table, centered the way I like it.
To do that requires some coordination between the shortcode handler functions. That’s done using PHP arrays. The pairing handler first initializes the arrays to empty, then processes the content of the shortcode (everything between the start and end markers). In the example, there are 2 of these elements, so the arrays will have 2 elements. Each row has an array, representing the content of a given pairgrade.
When the content of the pairing shortcode is completely processed, all of the shortcode content has been populated into the arrays. The handler then completes its job by building the rows of the table (using the content of the arrays) and publishing the table, appropriately centered.
This is available as Ron’s Beer Report Plugin, v0.2.
In the next post, I’ll talk about the handler for new words.