Improve Shortcode Experience using Shortcake

The real value in a WordPress-based website should be ease of management. You don’t need a developer on staff to update your website.

There are a lot of tools I use to keep my websites as easy as possible for non-technical clients. These include:

  • WP101 Video Tutorials to educate on how WordPress works and explain new features, because they’re always kept up-to-date with WordPress releases.
  • I provide detailed notes describing how to manage every aspect of their website when the site is sent for review. They can refer back to this in the future regarding custom features I built for them, since they won’t be covered in the videos.
  • I use editor styles so that the Visual Editor in the backend matches the styles of the frontend.
  • I add additional styles to the visual editor if needed, so they don’t have to remember class names (ex: two different types of blockquotes)
  • I create a Style Guide page that shows all the styling options they have in the visual editor
  • I create custom metaboxes for managing page elements that are outside the main content area, like page-specific header and testimonials.

Why I’ve Avoided Shortcodes

I also try my best to avoid shortcodes. They are code, so most clients aren’t comfortable with it. A shortcode doesn’t visually represent what it will be on the frontend – it’s just text, and the client has to preview the page to see what it actually looks like.

Finally, if the theme or plugin is ever deactivated, you’re left with content polluted with unused shortcodes. This issue can be minimized by registering your shortcode in a Core Functionality plugin and telling the client never to deactivate that plugin.

Shortcode UI to the Rescue

Shortcake provides a UI for inserting and viewing shortcodes in the editor. You click the “Add Media” button and there’s now a “Insert Post Element” option. All shortcodes that have included Shortcode UI code are displayed here. You get a nice visual builder, and when you click “Insert” it adds the properly formatted shortcode to your post. Even better, if you’re in Visual mode it will render the shortcode for you!

screenshot-4
screenshot-3

It’s a core feature plugin, so hopefully it will be merged into WordPress core soon. Here are recent chat summaries about Shortcake on the Make WordPress Core blog.

Using your own shortcodes

page-link-frontend

I’m working on a website right now that includes visual page links in the content area. The client needs to be able to select which pages to include, and where to place it in the page’s content. Each page link will be a rectangle with the page’s featured image in the background and the page title overlaid.

I created a simple shortcode that creates these links: [page-link ids=”12,34″]. But the client won’t know the IDs for the pages, and will most likely forget the proper syntax for the shortcode (is it page-link, page-links, page_link, page_links… should I use id if I’m only linking to one page…).

In my core functionality plugin, I placed the following to both register the shortcode and add it to Shortcake (walkthrough of the code follows the snippet).

<?php
/**
* Core Functionality Plugin
*
* @package CoreFunctionality
* @since 1.0.0
* @copyright Copyright (c) 2016, Bill Erickson
* @license GPL-2.0+
*/
/**
* Page Link Shortcode
*
*/
function be_page_link_shortcode( $atts ) {
$output = '';
$atts = shortcode_atts( array(
'ids' => '',
), $atts );
$ids = array_map( 'intval', explode( ',', $atts['ids'] ) );
if( $ids ) {
$output .= '<div class="page-link">';
foreach( $ids as $id ) {
$style = has_post_thumbnail( $id ) ? ' style="background-image: url(' . wp_get_attachment_image_url( get_post_thumbnail_id( $id ), 'page_link' ) . ');"' : '';
$output .= '<a href="' . get_permalink( $id ) . '"' . $style . '><span class="page-link-title">' . get_the_title( $id ) . '</span></a>';
}
$output .= '</div>';
}
return $output;
}
add_shortcode( 'page-link', 'be_page_link_shortcode' );
/**
* Page Link Shortcode UI
*
*/
function be_page_link_shortcode_ui() {
if( ! function_exists( 'shortcode_ui_register_for_shortcode' ) )
return;
shortcode_ui_register_for_shortcode( 'page-link', array(
'label' => 'Page Link',
'listItemImage' => 'dashicons-admin-links',
'attrs' => array(
array(
'label' => 'Pages',
'attr' => 'ids',
'type' => 'post_select',
'query' => array( 'post_type' => 'page'),
'multiple' => true,
)
)
) );
}
add_action( 'init', 'be_page_link_shortcode_ui' );
/**
* Page Link Image Size
*
*/
function be_page_link_image_size() {
add_image_size( 'page_link', 470, 300, true );
}
add_action( 'after_setup_theme', 'be_page_link_image_size' );
view raw shortcodes.php hosted with ❤ by GitHub

Here’s a walkthrough of what’s happening:

  • The first function creates the shortcode. Lines 18-22 define the parameter I’m expecting (ids) and ensures only integers are used.
  • If there are IDs passed, lines 23-31 build the shortcode output.
  • Line 27 checks if the page has a featured image, and if it does it sets the background-image equal to the featured image’s URL using the ‘page_link’ image size.
  • Line 28 builds the output, creating a link to the page, adding the styles defined above, and adds the page title.
  • Lines 41-60 add the Shortcode UI.
  • Lines 43-44 check to make sure the function is defined (confirming the plugin is active), and if not it returns early.
  • Lines 46-58 register all the shortcode’s information. I specify the shortcode (‘page-link’), the label to use in the backend, what Dashicons icon should be used to represent it, and the shortcode attributes.
  • This shortcode only has one attribute (ids), which uses the ‘post_select’ field type. You can see all the available field types here.
  • Finally, lines 66-70 register the image size used by the shortcode.

Then I added the appropriate CSS to both my theme’s stylesheet and the editor-style.css file. Now when editing pages the client will see the visual page links:

page-link-modal

page-link-in-post

Summary

I’m still conservative with my use of shortcodes, and will only use them if absolutely necessary. But if they are needed, the Shortcake (Shortcode UI) plugin drastically improves the experience of creating shortcodes and editing pages with shortcodes.

Bill Erickson

Bill Erickson is the co-founder and lead developer at CultivateWP, a WordPress agency focusing on high performance sites for web publishers.

About Me
Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Reader Interactions

Comments are closed. Continue the conversation with me on Twitter: @billerickson

Comments

  1. Christina says

    Wonderful, I’m going to play when I get a few min. this weekend. I figured that I’d make a plugin for it, but this is so much better.

  2. RW says

    Thanks a lot for this post. I’m going to tryout this shortcake solution. I would love to say goodbye to shortcodes once and for all. My customers hate it and it usually doesn’t extend well when updating to a new theme or if you part ways with a plugin.

  3. Chris Mower says

    Like you, I try to minimize shortcodes and when I do use them, I add them to a plugin. Apparently I’m out of the loop when it comes to shortcake. This post may have saved me from some frustrating situations. Thanks! Let’s hope it hits core soon. Until then… bring on the shortcake.

  4. Stephanie Leary says

    I played with Shortcake a few weeks ago and immediately thought about using it to create an interface for your Display Posts plugin.

    • Bill Erickson says

      I agree, it would be really nice to include Shortcake support in Display Posts. The issue though is the massive list of parameters they can specify. If there was a text field for every one it would be hard to use. I’d probably need to build some sort of custom UI so that you can select a parameter, then specify the value.

  5. Stagger Lee says

    You can use:

    if( defined( ‘SHORTCODE_UI_DOING_PREVIEW’ ) && SHORTCODE_UI_DOING_PREVIEW ){
    // Placeholder ! Shortcode callbacks must return content, hence, output buffering here.

    else {
    // Real content ! Shortcode callbacks must return content, hence, output buffering here.
    }

    to remove link from title in backend. Sometimes clicking on it opens related article in TinyMce shortcode.

  6. Heath says

    I’m loving Shortcake UI. I’m using it for a hand full of simple shortcodes. It’s a big leap for user experience.
    The only thing, for the life of me, I can’t get the editor styles to work? What am I missing?

    add_editor_style( BTRSC_PLUGIN_URL . ‘assets/css/custom-editor-style.css’ );

    Maybe I’ll figure it out when I get some sleep…

    • Bill Erickson says

      Two possible issues:

      1. The constant BTRSC_PLUGIN_URL isn’t returning what you think it is, so the link to the CSS file is broken. Try just echo’ing that in your theme somewhere, then click to see if it 404s
      2. The cache needs to be cleared. For some reason the editor-styles cache is very difficult to clear. I use this in my dev server’s mu-plugins directory which clears the cache when you update the file
      • Heath says

        The third issue – I’m sleep deprived and an idiot.

        I was referencing “custom-editor-style.css” the file is “custom-editor-styles.css”

        I should have checked my dev tools:P

        Thanks for the speedy & helpful reply Bill. Excellent article.

  7. Hafiz says

    I was quite bored to use my shortcode as it were making me mad as well. That’s y I was looking for some reliable blog posts to use any other method. And I found your blog post quite helpful. Thank u for making it trouble-free.

  8. Hans Schuijff says

    I just saw the presentation on YouTube (https://youtu.be/K_xLdI1102I) about content creation (shortcake) versus site creation (through page builders) by Stanislav Khromov, Aftonbladet. I found it very interesting and begin to understand the positioning of both directions a bit more. I recognize the dilemma’s between those two directions which both aim to enrich user experience.

    Looking at the admin-experience of using shortcodes this way seems to me a bit like the experience of using frontend pagebuilders like beaver builder or f.i. the 3.0 version of Divi builder (only two of many), except that the presentation is more fixed and the focus is more on the content than offering some sort of gui for css (like pagebuilders offer).

    I can understand that for an audience that doesn’t need to vary presentation beyond what is preformatted, a shortcake approach will be more fitting (less options to worry about and consistency in presentation), while others may want or need the extra options of a pagebuilder-experience. Both seem to be an answer on limitations still present in the editing environment, and both promising what is still to come.

    Lately I wonder a bit about the efficiency of the different directions and tools also, since I notice that usage of frameworks included different plugins means a lot of code is duplicated and wondering about the efficiency of realtime generated content (using widgets or shortcodes that generate code to be included when a page is requested) versus static content (html and text as part of the posts and pages content).

    Most pagebuilders use shortcodes behind the screen that are processed when a page is requested in stead of when it is build, just like shortcake, and they use lots of javascripts (both the builder as the result of it), while lots of the content is really static from the moment the page is build. Other content, like the latest events of the most populair post-titles, can only be generated at runtime.

    The more content is replaced by shortcodes and other runtime generators of content, the more html and css might be generated at runtime anyway. I wonder what impact does this have on server processing and the browser environment that this static html/css combo. Can we have flexibility in presentation, attractive visual elements, and fast content creation, and still have lean content environments? Will there be page/content builders that use shortcodes only when content really needs to be generated on runtime and just directly build html and css for the rest?

    Probably it’s the dilemma we’ re in, waiting for ever faster and more powerful machines to solve resource limitations. I have experienced how themes that use lots of shortcodes and scripts make response times explode, and how even the normal edit environment (tinymce) can slow down to a halt when articles get longer and are revised, so I’ve learned to be careful. But there is also a desire to have integrated wysiwyg functionality and great presentation.

    I’m curious about what the future will hold. Until then, I watch and learn some and thank you for your sharing and advice.