WordCamp Raleigh & “Shortcake”-Powered Design

I recently had the pleasure of speaking at WordCamp Raleigh, the annual WordPress conference for Triangle-area designers, developers, users, and WordPress enthusiasts. In my talk, I walked through how we use Shortcake (Shortcode UI), and how it helps us solve some of the problems we face at NC State.

We don’t have everything figured out, and I talked about some of that in my presentation. But using Shortcake has helped shape a larger design philosophy that’s been very useful in our work, and that I think will become more useful to the broader WordPress over the next few years.

I once heard a developer call these kinds of talks “working out loud”—talking through our problem so we can hear ideas from others, and maybe give other developers some ideas too. I got a lot of good feedback after my talk, and I know of at least one area business that’s planning to incorporate Shortcake into their processes now. That’s a great feeling.

So in the interests of “working out loud” with a broader audience, here’s my WordCamp Raleigh presentation in blog post form.

NC State’s “Shortcake”-Powered Design Strategy


Shortcake (Shortcode UI) is a WordPress feature plugin (under consideration to be included in WP core), with development led by Daniel Bachhuber and Matthew Haines-Young. It provides an API to register a simple user interface for shortcodes, and it previews those shortcodes in the Visual Editor.

That’s the tl;dr version of what you can do with Shortcake. To really appreciate how powerful it is will require a little more explanation.

What this story actually is, besides talking about how we use a particular plugin, is a love letter to the WordPress Visual Editor. Like all good love letters, this post contains some tortured metaphors and goes on a lot longer than necessary. Feel free to skip straight to the code examples, the big-picture takeaways, and the caveats and thoughts about the future.

Falling in Love with the Visual Editor

From the outside, big universities like NC State might look like well-organized institutions with centralized leadership. From the inside, the reality we experience is a lot more complicated. NC State is incredibly decentralized by necessity—we just do so much stuff here that it’s not practical or desirable for everyone to be on the same page at the same time.

WordPress is the perfect CMS for that higher ed experience. (See also: WPCampus!) It’s easy to set up, easy to get content into, and can be deployed to meet the specific needs of a specific project. You can organize an entire college into a single multisite, or you can have a cluster of single-installation websites with all of their particular needs and non-WordPress “extras” accommodated. Or, at NC State, you can do all that and more simultaneously.

But that also makes our jobs at OIT Design a lot harder. Some groups on campus that have their own dedicated IT staff with WordPress expertise (eg. ITECS in the College of Engineering). Dozens of others have a “web guy” who “knows a lot about this” when they set up their site, but then they leave the university.

When those websites end up under our support umbrella, we’re often working with administrative assistants and grad students who are new to maintaining websites and have many other job responsibilities besides updating the website. Most don’t know HTML, CSS, or the inner workings of WordPress. They certainly don’t want to have to learn all of that to do what’s just one component of their jobs.

Thankfully, they don’t have to. When these clients come to us with a website already in place, the settings have already been configured and the plugins have been selected. We care about that stuff, but they don’t. Here’s what they’re doing:

  • Writing blog posts
  • Updating existing pages
  • Creating new pages

And WordPress is great at taking what they’ve typed into the Visual Editor and turning it into what they see on the front-end of their website.

Example Visual Editor providing a WYSIWYG experience for rich text and images
On a daily basis, most of our users are doing this: Entering rich text and images in the Visual Editor, and publishing it to their website.

(A quick aside that will be more important when we get into Shortcake stuff: Your WYSIWYG experience is even better when you use the add_editor_style() function in your theme. I’m surprised by how many developers don’t take that extra step to make the editor experience match the front-end look-and-feel.)

This is what keeps us in business. The Visual Editor is:

  • Easy to learn – If you’ve ever written an email in Gmail, you can figure out the Visual Editor
  • Well-documented – When users do need help, core WordPress functionality is very Google-able
  • Doesn’t require much attention from us – Core WordPress functionality is dependable and predictable

So we can get away with supporting a wide variety of clients who all do their own special thing because we just don’t get many questions about users’ day-to-day WordPress experience. Our support load stays busy-but-manageable. That’s why I love the Visual Editor.

Relationship Trouble

Uh oh. This is the part of the story where we discover that the Visual Editor takes me for granted and never does the laundry.

Or, rather, this is the part of the story where we run into users wanting to do things that the Visual Editor just isn’t designed to do.

The Visual Editor is great if you’re building something that’s relatively simple: text, images, and basic formatting.

Example Visual Editor providing a WYSIWYG experience for rich text and images

But more and more of our users expect a content management experience where they can do more than that. All of those Squarespace ads on your favorite podcast—where they say you can “build it beautiful”—have raised expectations. They want to build different complex page layouts for every page, and they want it to be easy to make rows, columns, varied fonts and font sizes, background colors, icons, etc.

Page layout with lead paragraph with larger text, a featured "callout" box mid-page, and two columns of text

Page layout with featured image and text "callout," two columns of text, and an inline icon

Page layout with pullquote and three-column recent posts

And that’s the complex stuff. They also want simple things, like this:

Hyperlink with larger text and an animated arrow

That’s a screenshot of a what we’ve called “major links.” NC State’s UComm team introduced them a couple of years ago, and they were strangely popular. It’s just a regular link, but slightly bigger, and with an animated arrow that scoots to the right when you hover over the link. Everyone loves them and NC State uses them everywhere. We get requests from clients about these specifically.

But how do you add a major link to your page? If you know a little HTML and CSS, it’s easy. But if you’re one of our users who doesn’t know or want to learn HTML or CSS, it’s a lot less clear. There’s no button in the Visual Editor that says, “make my link bigger and add a little animated arrow.” We’re constrained by our editor in what we can do.

This is a problem that’s clearly on Matt Mullenweg’s mind, too. When Matt announced the development priorities for 2017, the editor experience was front-and-center:

There are three main focuses this year: the REST API, the editor, and the customizer… The editor will endeavour to create a new page and post building experience…

It sure sounds like Matt has fallen out of love with the Visual Editor. (More on that later.) But I haven’t given up.

Working Through Our Problems

Page layout with featured image and text "callout," two columns of text, and an inline iconAlright, Visual Editor. Let’s talk about what I’m looking for in this relationship.

I’ve got a user who needs a complex page layout with multiple columns, icons, a big section at the top in a different background color, and varied font sizes. (And not “I’ll just use headings when I want big text,” because we care about accessibility!)

What answers can we give that user?

Answer #1: “No.”

This is the easy answer, and sometimes it’s the right answer. The status quo has worked really well for us, and we just don’t have the people or the time to do more than that.

But that’s not always the right answer. More than that, we should really be aiming higher.

Jen Simmons, Mozilla’s Designer Advocate, has some great presentations on layouts. She argues that us web designers have gotten ourselves into a rut where we’ve convinced ourselves that there are only two layouts we’re allowed to use:

You know these layouts: The one with a sidebar, and the one with stacked rows subdivided into a few columns. She argues that we’re better than that, as designers, and asks us to look to other media for ideas.

Go watch her presentations and look at her demos. They’re inspiring. (But then come back here, because we haven’t even learned about Shortcake yet.)

I saw her speak in 2015 and I left feeling ready to conquer the world. I had so many ideas, and I wanted my users to be able to build amazing websites. But that Visual Editor I love so much holds us back, standing between us and the Jen Simmons layout utopia. If my editing experience is driven by the Visual Editor, my starting point is the most-boring version of Jen Simmons’ boring layouts.

The Visual Editor interface and a live page, compared to Jen Simmons' content-and-sidebar layout

Answer #2: “There’s a plugin for that!”

We’ve decided that we want to give our users what they want, but we don’t really know how to do that. So we do what everyone in WordPress does: We go looking for the right plugin.

And there are many to choose from! Tools like Page Builder, Visual Composer, and Divi are popular choices in the WordPress ecosystem. As last year’s WPCampus survey found, they’re popular in higher ed as well.

Some of these plugins are really good, useful tools. It’s pretty easy to build a more complex page layout with some fancy page elements that wouldn’t be possible in the regular Visual Editor:

Page layout with multiple text columns, an inline icon, and a featured image and text "callout"
I built this in about 5 minutes with Page Builder by SiteOrigin. It doesn’t quite match what the user asked for, but it’s close!

It’s also pretty easy to build a page that, well, doesn’t quite match your institution’s brand guidelines:

Page layout with multiple columns of text, inline icons, and a featured image and text "callout," but with the wrong school colors
Hint: That light blue color and that icon belong to a certain other school in Chapel Hill.

More importantly, it’s uncomfortably easy to build a page that’s got lots of accessibility issues:

Page with desired features, but inaccessible color combinations
Don’t think any of your users would make something like this? Do you really want to take that chance?

That’s ultimately my problem with page-building plugins, and why our team doesn’t use them. These tools are incredibly powerful. As we all learned from Uncle Ben, that power has to be wielded responsibly.

Wielding that power responsibly means:

  • Training content creators on acceptable use. Can we train every admin assistant and grad student with web content responsibilities on campus branding and web accessibility rules?
  • Monitoring use and intervening when necessary. How often can we reasonably check in on every page of every site we help manage?

When you’re a small team with a big client base (like us), there’s no practical way to do either of these.

Answer #3: “I’ll add a page template to the theme”

This is the next stop for every WordPress developer: Adding new page templates.

“You want a page with text at the top, three columns of recent posts, and your latest calendar events? I can add that to the theme, sure.” And since I’m the one coding the template, I can make sure it stays on-brand and accessible, with less risk of the content creator going in a different direction.

But once a client gets one custom template, they often want another one. The “Symposiums” page is meaningfully different than the “Colloquia” page, and both are different from the “Seminars” page. And they all have to look different. So they ask for another page template… and another… and another.

WordPress page template dropdown menu, with similarly-named templates like "Page - Full Width" and "Page - Full Width with Sub Pages"
These are the page templates from one of the themes we manage. This is the best way we could think of to name the templates.

You end up with a list of templates with names that try to be descriptive—but not too specific, because we want them to be at least a little generic and reusable. But these names are cryptic to new users, and each page has its own unique set of rules: this meta box maps to here, and that part comes from the theme options, and this other part is actually a widget area.

Representation of disparate views in the WordPress admin mapping into a single page template

This experience is bad for the user for all of the reasons the Visual Editor is good for the user:

  • Hard to learn – Users have to remember all the rules associated with each template
  • Poorly documented – It’s certainly not Google-able, and depends on good documentation by the developer
  • Requires regular attention from us – Every time a client wants a minor tweak they have to contact the developer, wasting both the developer and the client’s time

Before you say it: Yes, Advanced Custom Fields buys you a little more flexibility and makes this whole thing a lot easier on the developer. But you’re still adding templates to themes with “this meta box goes to here” rules that users have to remember, and you don’t have that WYSIWYG experience the core Visual Editor offers.

And—while not directly relevant to this discussion—once you start using ACF, you’re storing what should be considered post content in wp_postmeta instead of wp_posts. That can cause issues (eg. WP native search won’t see it), and it’s just… not very satisfying to me. It bothers me deep in my core. I want my post content in wp_posts!

But setting that aside, the “let me add it to the theme” method is developer-intensive. Multiply this across all of the themes our team is responsible for, and this gets out of hand really quickly. Page templates have their place, absolutely. But wouldn’t it be nice if we could empower our users a little more, and put a little less pressure on the developers to make it all happen?

Falling in Love Again

None of those answers—page-building plugins, an ever-growing lists of templates, or the status quo of traditional/boring pages—really solves anything. But each has merits, and our ideal outcome would be to combine the best of each answer:

  1. Like page-building plugins, we want user-driven page design. They shouldn’t have to come to us all the time for new templates, and should have the freedom to decide what their pages look like.
  2. Like the page templates that we build for clients, everything should be branded and meet all of our accessibility requirements. We want users to drive the design process, but we don’t want them to drive themselves off a cliff.
  3. Like the status quo that’s served us well up until now, the user experience should be contained in the WordPress Visual Editor. That’s the interface our users are familiar with, and it has all the Google-able benefits of being core functionality.

That’s way off in the future, right? Maybe someday, when the WP core team rewrites the editor, we can have something like that.

But what if we didn’t need to wait? What if I told you how you could have all of that, right now?

I don’t know about you, but to me, that feels something like this:

Shortcodes

The Shortcode API is a well-established part of WordPress (since version 2.5!), so most developers reading this probably have some experience with it. If this is all old news to you, trust me, the exciting part is coming.

As you likely know, a shortcode defines a macro [shortcode attr="value"] that you can place in a post or page. When the end user views that published post, a block of PHP or HTML is rendered instead of the placeholder.

Let’s add a “major link” shortcode, which is sort of the bare minimum added functionality our users might be looking for. (If you skipped all the backstory above, that’s a big-ish link with an animated arrow.) I’m going to do this as a plugin, so that it can be used in any of the themes we maintain.

When you activate that plugin and place

[major-link url="https://www.ncsu.edu/admissions/"]]Apply to NC State[[/major-link]

in a post, it will render as

<a class="major-link" href="https://www.ncsu.edu/admissions/">Apply to NC State <img src="arrow.svg" /></a>.

The styling for .major-link can be set in your theme or in a CSS file bundled with the plugin.

Shortcodes are a favorite tool in the WordPress developer toolbox for a lot of reasons. They’re relatively easy to build—I just made one just now! They’re reusable and can be used multiple times in any post or page. They have defined limits and only do what you build them to do. Most importantly, they’re well-supported in WordPress core.

But to a lot of our users—those admin assistants and grad students who get stuck with updating the website—shortcodes look like, well, code. And there’s literally nothing WYSIWYG about [shortcode attr="value"] all over your page.

So shortcodes aren’t the answer on their own, but they are the first half of the answer.

Shortcake

That’s where Shortcake comes in. The GitHub repo describes Shortcake:

Used alongside add_shortcode, Shortcake supplies a user-friendly interface for adding a shortcode to a post, and viewing and editing it from within the content editor.

After you register your shortcode, Shortcake lets you register a shortcode user interface:

In the attrs array, type supports 13 input types: text, checkbox, textarea, radio, select, email, url, number, date, attachment, color, post_select, and term_select.

Finally, you’ll want to use add_editor_styles() to style the Shortcake-rendered preview to match what you’ll see in your published page.

You can play along at home! Just follow these steps:

  1. Find Shortcake (Shortcode UI) in the WordPress plugin directory. Install it and activate it.
  2. Install and activate my demo plugin.
  3. Create a new page or post. You’ll notice there’s a new button that appears above the page editor that says “Add Post Element.”Visual Editor toolbar with "Insert Post Element" button
  4. Click that button and the WordPress media modal will open, with a new view displaying all of your registered shortcode UIs.Media modal showing the "Major Link" shortcode as an option
  5. Choose the shortcode you want to use. (If you’ve only installed my demo plugin, it’s an easy choice!) That opens a simple form that corresponds with the inner_content and attrs arrays that were defined in the plugin.User interface for inserting a "major link" shortcode
  6. Fill out the form and click the “Insert Element” button. In your Visual Editor, you should now see a preview of your major link rendered alongside the content you’ve already added."Major Link" shortcode previewed in the Visual Editor

The object is drag-and-drop-able, and you can click on it to open the modal again to edit it. If you need to edit the shortcode directly, you can still do that by switching to the Text editor. But for most of our users, what matters most is that the preview in the Visual Editor matches up pretty closely to what they see in the live site.

Not “Just Another Plugin”

Okay, but we’ve heard this before, haven’t we? The Visual Editor is all apologetic and says it can change! It just needs this one plugin and then everything will be different!

But Shortcake isn’t “just another plugin,” at least not entirely. Its status as a “feature plugin” candidate for WP core is important, both as an indicator of where it might be going and the quality of the code behind it.

It’s true, there are plenty of feature plugins that never make it into core—or take a really long time to get there and go through some breaking changes. But if I had to deactivate Shortcake on all of our sites tomorrow, the end user would see no change because the shortcodes themselves would continue to render. Shortcake is purely a content creation convenience—an extra layer that helps make the editor experience smoother and more robust.

The Next Stage of Our Relationship

With Shortcake, the Visual Editor has made a lot of changes and promised to clean up its life—and finally started doing its share of the laundry, too. Now it’s on us to reimagine what it’s capable of and give it a chance to impress us.

We have this idea of a WordPress theme as a collection of page templates. But now we can think of it as something else: a canvas for building posts and pages.

What if your theme doesn’t do the heavy lifting of page design and layout? What if, instead, you empower your content creators to choose their own design with Shortcake-powered shortcodes?

We distribute this plugin through an internal-to-NC State plugin directory, so this won’t show up in your plugin search results. Sorry.

That’s where “NC State Shortcodes” comes in. It’s our homegrown plugin modeled off of the Shortcake Bakery plugin, and it serves as our ever-growing collection of Shortcake-powered shortcodes.

Collection of shortcodes in the Shortcake modal

After an initial flurry of “We need a thing that fills this need can you make it for us?”-type development, we’re now starting to refocus on this project with cooperation from developers across the university.

Imagine it as a sort of pattern library, but instead of providing code examples to developers, we’re handing fully-functional modules to the content creators themselves. Each module meets our institutional branding and accessibility requirements, so our users can use them with less risk of misusing them.

Shortcake supports JavaScript for conditional display of attributes in each shortcode’s form. We’ve used that to make much more sophisticated shortcodes than you would normally see, using dummy attributes as ways of “unlocking” additional attributes. For example: choosing a callout with an image-type callout instead of a basic callout-type callout displays a different set of attributes, including an image upload button. Each of the banners below were created using the same “callout” shortcode:

"Callout" banner with blue background with white icon and text

"Callout" banner with image on the left half, dark gray background on the right, and white icon and text

"Callout" banner with full-width image, and red box with white text floating in the bottom-right corner
That would be unusable with normal shortcodes, because users just won’t remember all of the attribute combinations to get what they want. With a Shortcake-powered shortcode, we can walk a user step-by-step through a process, with dummy attributes, helper text, and instructions on best practices along the way.

For some shortcodes, you may want further control over how the shortcode renders in the Visual Editor. When you add_editor_styles(), you can style elements with #tinymce and its children. This gives us an extra option for guiding users toward proper usage.

We have embraced the layout-and-design potential for Shortcake-powered shortcodes as one of the core building blocks for the WordPress services we provide. We start most new projects with a homegrown theme called “Hillsborough” (named after Hillsborough Street, one of the main roads near campus). Here are the page templates we’ve built into Hillsborough:

Page template with content and a right sidebar

Page template with content and a left sidebar

Page template with content and no sidebars

And that’s… just about all the theme does, when it comes to page templates. You can add featured images and you can hide the page title. But there’s not much more than that. Our shortcode plugin does the rest of the hard work.

It’s not a perfect WYSIWYG experience… but the differences between the editing experience and the finished product are relatively minor. A little more custom CSS on the #tinymce element and its children, and we could probably clean up all the remaining differences.

And since we’ve put these layout and design elements in a plugin rather than the theme, that means these page elements can be inserted into any theme. Maintaining the legacy themes that we inherit when we begin supporting new sites becomes much easier, as does sharing the tools we build with the rest of campus.

At this point, we’re still pretty far from that Jen Simmons layout utopia. But Shortcake gives us some of the tools to get there. Jen Simmons wants us to take inspiration from the world of print media, use cutting-edge CSS techniques, and consider layouts like this:

Text with a heading rotated at a 45 degree angle

And that’s something we can do with a Shortcake-powered shortcode:

A heading added by shortcode, rotated 45 degrees inside the Visual Editor

We’re not ready to do things like that in production quite yet—and, truthfully, this example in particular wouldn’t comply with our brand guidelines anyway. But it’s an indicator of just how powerful these Shortcake-powered shortcodes can be—far beyond what you can do today with ACF or page-building plugins.

Relationship #RealTalk

Let’s be real about what what we’ve accomplished here. They’re still just shortcodes. It’s still just the visual editor.

Right now, Shortcake doesn’t support rich text fields, meaning there are some situations where users may need to know some basic HTML in order to style their content. (But people are working on that!) There also isn’t a great way to do repeating fields, which ACF power-developers can’t live without. There’s not really a way to do nested Shortcake-powered shortcodes. And sometimes you just run into weird behavior.

So let’s call this what it is: a kind-of-hacky way of making the most of the tools we have. Shortcodes were never imagined as the way to do all of these things, and the Visual Editor was never imagined as a complex page-building platform.

This is a big part of life in higher ed IT, and something our colleagues in the private sector don’t always get. Many tools aren’t designed with our weird organizational needs in mind. We live with some combination of enterprise-level tools built for the corporate world, education tools built for K12, and custom code to make it all come together. Shortcake-powered shortcodes are just another example of “thing built for one purpose being used in a completely different way because that’s the best we could do.”

That brings us back to Matt Mullenweg’s blog post. I snipped my excerpt short earlier because I wanted to save the full quote until now:

There are three main focuses this year: the REST API, the editor, and the customizer… The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.

It sure doesn’t sound like Matt is talking about Shortcake, does it? And if you stop by the Making WordPress Slack group, you’ll see a lot more activity in #core-editor than in #feature-shortcode. The early mockups of the Gutenberg editor are exciting and very promising.

Gutenberg UI mockup
Screenshot of Gutenberg, the next-generation WordPress editor

But while it’s a dramatic departure from what we have now, it’s conceptually linked to Shortcake and the design philosophy we’ve embraced. Gutenberg uses a block-based UI, in which users decide what kind of element they want to add to the open canvas of a new post or page. This extends beyond paragraphs and headings, including things like Twitter embeds, maps, and video:

View of content block embed pop-up in Gutenburg

The #core-editor team is developing an editor block API (see #104, #300, and #302) for adding your own content blocks via plugin, which would make adapting all of those Shortcake-powered shortcodes into editor blocks very plausible. This is the future of the WordPress editing experience, and it’s a future we can practice and learn with Shortcake.

Mock-up of NC State editor blocks

 

Big changes to WordPress take time, as we saw with the WP REST API. Some day, this 4,600-word blog post (sorry about that) will be totally obsolete. Some day.

In the meantime, the Visual Editor—our old friend and partner in building so many websites—is still here for us. Shortcake continues to solve a lot of immediate problems. And Shortcake offers a good training experience for when the block-based editing of Gutenberg becomes a reality.