Customizing The WordPress HTML Editor With The Quicktags API

img-0
admin
December 7, 2020 code learn post jumbotron

Here at Urban Influence, blog design is never an afterthought. In fact, we love designing clean and beautiful post layouts that offer up a brand’s content in a meaningful and engaging way.

Well considered typography, vertical rhythm, big impactful imagery… these are our tools to capture and hold readers. And, as proven by the success of such amazing writing tools as Medium and content rich sites like Quartz, this is where the industry’s heading.

Needless to say, we put a ton of time into designing and building super snazzy blogs. So, preserving those efforts after client hand-off is tricky. It begins with education, and ends with optimal UI/UX of the actual writing experience. Since our open source CMS of choice is WordPress, let’s call this: An intro to customizing Wp’s editor for ease of use and design preservation.

Kick Rocks Evil WYSI

First off, let’s tell the evil wysi to kick rocks. While the wysi environment does provide authors with layout insight, it also enables them to go against all your painstaking styles. Additionally, you’re leaving the door open for all kinds of unpredictable / gross / havoc wrecking markup output. Forget that noise. Let’s pull it

/*-----------------------------------------------*/
/* Remove Visual Editor form Admin
/*-----------------------------------------------*/
add_filter ( 'user_can_richedit' , create_function ( '$a' , 'return false;' ) , 50 );

Wp’s Quicktag API & quicktags_settings Hook

With the WYSI gone, time to customize the HTML Editor’s toolbar. The key is to provide authors with formatting control that precisely references your styles. Generally, this includes a collection of default tags and elements, such as lists, blockquotes, links, headers, etc. While Wp has several built in buttons for standards formats, you’ll probably want to offer some additional controls.

For this, we’ll be pulling from Wp’s Quicktag API, which allows you to include additional buttons in the HTML editor via a js function called QTags.addButton

But, before we start adding custom buttons, let’s use the quicktags_settings hook to display the built in buttons we need, in the order we’d like:

/*-----------------------------------------------*/
/* Customize button output
/*-----------------------------------------------*/
function urban_show_quicktags( $qtInit ) {
 $qtInit['buttons'] = 'strong,em,block,del,ul,ol,li,link,code,fullscreen';
 return $qtInit;
}
add_filter('quicktags_settings', 'urban_show_quicktags');

Now, let’s create our custom buttons. For this example, we’re adding options for headers, separators, arrow links, and captions. Of course, the outputted markup relates to predefined styles.

/*-----------------------------------------------*/
/* Add Text Editor Buttons
/*-----------------------------------------------*/
function urban_add_quicktags() {
//check to see if the 'quicktags' script is in use to avoid errors 
 if (wp_script_is('quicktags')){ 
?>
 <script type="text/javascript">
 QTags.addButton( 'h4-subheader', 'SubHeader', '<h4>', '</h4>', '4', 'Sub Header', 1 );
 QTags.addButton( 'hr-sep', 'HR Seperator', '<hr class="sep"/>', '', 's', 'Horizontal rule line', 201 );
 QTags.addButton( 'arrow-link', 'Link Arrow→', '<a class="link-arrow" target="_blank" href="">', '</a>', 'z', 'Link Arrow', 200 );
 QTags.addButton( 'figcaption', 'Caption', '<figcaption>', '</figcaption>', 'f', 'Figcaption', 203 );
 </script>
<?php
 }
}
//Print to admin footer
add_action( 'admin_print_footer_scripts', 'urban_add_quicktags' );

Quicktags Perimeters

The Quicktags perimeters are: Button ID (required), Button display value (required), Opening Tag (required), Closing Tag (required), Accesskey (optional), Title (optional), Priority/position (optional).

More on the Quicktags API and default editor buttons can be found in Wp’s docs

Going Further

Great start. But for my own purposes, how about some support for code samples (using the great syntax highlighter Prism).

/*-----------------------------------------------*/
/* Add support for code samples via Prisim
/*-----------------------------------------------*/
function urban_add_quicktags() {
 if (wp_script_is('quicktags')){
?>
 <script type="text/javascript">
  QTags.addButton( 'h4-subheader', 'SubHeader', '<h4>', '</h4>', '4', 'Sub Header', 1 );
  QTags.addButton( 'hr-sep', 'HR Seperator', '<hr class="sep"/>', '', 's', 'Horizontal rule line', 201 );
  QTags.addButton( 'arrow-link', 'Link Arrow→', '<a class="link-arrow" target="_blank" href="">', '', 'z', 'Link Arrow', 200 );
  QTags.addButton( 'figcaption', 'Caption', '<figcaption>', '</figcaption>', 'f', 'Figcaption', 203 );
  QTags.addButton( 'code-inline', 'Code Inline', '<code class="inline">', '</code>', 'n', 'Code: Inline', 204 );
  QTags.addButton( 'code-js', 'Code: JS', '<pre><code class="language-javascript">', '</code></pre>', 'j', 'Code: JS', 205 );
  QTags.addButton( 'code-html', 'Code: HTML', '<pre><code class="language-markup">', '</code></pre>', 'h', 'Code: HTML', 206 );
  QTags.addButton( 'code-css', 'Code: CSS', '<pre><code class="language-css">', '</code></pre>', 'x', 'Code: CSS', 207 );
  QTags.addButton( 'code-php', 'Code: PHP', '<pre><code class="language-php">', '</code></pre>', 'p', 'Code: php', 207 );
 </script>
<?php
 }
}
add_action( 'admin_print_footer_scripts', 'urban_add_quicktags' );

Boom. Now, when you go to create a new post, your toolbar will look a little something like this:

img-1

Usage

To rock your fancy new buttons, just highlight the desired text and click its related button. Or, click your button to open the inserted format, then click again to close were suited.

Hopefully, you now have some help with improving the author experience while preserving your blog’s design. Of course, this is only a nice first step. Stay tuned for more.

Other posts