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