Nothing But Words

My last Shashin post has about 75 comments, so it’s time for a fresh plugin support post. I’m also creating a new plugin support category for these posts, which should make them easier to find.

Please use the comments section for any questions about my plugins. I’m gratified that my plugins are becoming more popular, but it also makes it harder for me to provide personalized support. My plugins have extensive documentation, especially Shashin, so please review the documentation to see if you can find an answer to your question there before posting here. Thanks!

A feature of WordPress 3.3 is the new QuickTags API, which makes it possible for developers to add buttons to WordPress’ HTML Editor button bar. My Extensible HTML Editor Buttons plugin uses this API to allow non-developers to easily add buttons. It includes a WYSIWYG settings form for creating new buttons. You can use it to specify the label for your button, the tag you want it to insert, and whether it is a self-closing tag (such as an <img> tag). If you’re comfortable with HTML (and you should be, since you’re using the HTML Editor!), you can also create a custom dialog for your button to launch. This is handy if your tag has multiple attributes (such as class, title, etc). And for plugin developers, it has an API that uses a simple method call where you can register your own button. This is useful if, for example, your plugin uses a shortcode and you’d like to create a button for it, without having to delve into the QuickTags API yourself.

• Download at wordpress.org
• Documentation here at toppa.com
• Source code for review at GitHub.com

Something I quickly learned working with the QuickTags API is that it’s fairly limited. It’s really designed just for adding simple buttons. Supporting custom dialogs through it required me to do some jQuery gymnastics – see my buttonController.js file if you want the gory details.

If you’re interested in the QuickTags API itself, the qt.addButton function in wp-includes/js/quicktags.dev.js has detailed explanatory comments, and there’s a good, simple working example in this gist file.

Aficiondos of toppa.com (if there are any such people) may notice this plugin sounds a lot like my old Koumpounophobia plugin. That plugin did a lot of jQuery-based scraping of the HTML Editor to make it possible to add custom buttons, since there didn’t used to be an API, and it ceased to work with the rewrite of QuickTags in WordPress 3.3. Also, the name I gave it was a poor choice (it means “fear of buttons” – totally obscure and a little too clever…). So I took the opportunity to re-write it and give it a much more descriptive name.

This past summer I started attending the Philly WordPress meetups, which led to an opportunity for me to speak at Philly WordCamp, which led to an amazing opportunity to work at WebDevStudios, with an amazing team. Today – Monday – was my first day on the job. I’m doing custom development work and soon I’ll get involved with project management. I’m starting with some enhancements to Baja.com. Friday was my last day at Penn, so my head is spinning a bit from the transition.

I’ve been part of the web team in Penn’s School of Medicine since 2004, and I’ve been Director for the past 2 years. My team had a lot of demands placed on them, with the need for projects outpacing what we could provide. One of the first things I did as Director was learn Agile practices so I could teach them to my team (and I brought in a scrum coach to help). These two graphics illustrate the two primary challenges we faced – not enough staff, and too much chaos:

Blue represents available SOMIS staff, red indicates how many people would be needed to complete the desired work View at Picasa Blue represents available SOMIS staff, red indicates how many people would be needed to complete the desired work

Illustration by Esther Derby showing a not very well functioning development process View at Picasa Illustration by Esther Derby showing a not very well functioning development process

For many months my work spilled over into nights and weekends as I tried to move things forward. I can’t say we entirely solved these problems, but we made a lot of progress, and got the wheels turning in higher levels of administration to address the situation (“turning the aircraft carrier,” as one of our project managers put it – change is not easy to implement in a huge institution). Deciding to leave was hard, but an opportunity to turn my WordPress plugin development hobby into a job, to work with Brad (@williamsba) and the WebDevStudios team, and having the flexibility of working at home… it was too good to pass up. I’m especially looking forward to having more time to code again. If the past 2 years have taught me anything, it’s that I have a passion for software development, and always striving to do it better.

WordPress 3.3 introduced a new, unified media menu, where the functionality that used to be accessed through several different menus is now all in one. If you are a plugin developer, and you want to create a custom media menu, you will discover WordPress’ media menu is an arcane and fickle beast. The general reason it’s challenging to work with is that the media menu lacks a complete API. I put several hours of code archaeology work into teasing out its functionality, so this post can guide you through using it. There are two approaches.

Approach one: use ThickBox directly

The WordPress media menu is displayed using ThickBox. One approach is to simply invoke ThickBox directly from your own media button, and not rely on WordPress’ filters or hooks beyond that. This is the simplest approach, and is suitable for many purposes, but it prevents you from using WordPress’ filters and hooks for applying stylesheets to it, or using menu tabs. This is the approach used by the Gravity Forms plugin. Here is the relevant parts of the Gravity Forms code, slightly re-arranged, to show how it all fits together:

1. Add the Gravity Forms button to the media menu (“RGForms” and “GFCommon” are custom Gravity Forms classes)

   add_action('media_buttons_context', array('RGForms', 'add_form_button'));
   
   public static function add_form_button($context){
       $image_btn = GFCommon::get_base_url() . "/images/form-button.png";
       $out = '<a href="#TB_inline?width=480&inlineId=select_gravity_form" class="thickbox" id="add_gform" title="' . __("Add Gravity Form", 'gravityforms') . '"><img src="'.$image_btn.'" alt="' . __("Add Gravity Form", 'gravityform') . '" /></a>';
       return $context . $out;
   }

2. Add to the editor page footer the javascript and html that will be shown in the thickbox window when the media button is clicked.

   if(in_array(RG_CURRENT_PAGE, array('post.php', 'page.php', 'page-new.php', 'post-new.php'))){
       add_action('admin_footer',  array('RGForms', 'add_mce_popup'));
   }

3. In the function below I’ve removed the javascript code that reads the form inputs. The call to send_to_editor passes the resulting Gravity Forms shortcode to the editor window. After that is the html code that displays the form. The display: none style is important: the form is hidden at the bottom of the editor page, and then shown in the ThickBox window when the media button is clicked (the media button link refers to the id of this div). I’ve also removed the input form, which has all its CSS styling done inline (with this approach, there’s no straightforward way to call an external stylesheet).

   function add_mce_popup(){
       // ...not shown - javascript that reads the form inputs
   
       window.send_to_editor("[gravityform id=\"" + form_id + "\" name=\"" + form_name + "\"" + title_qs + description_qs + ajax_qs + "]");
       // ...
   
       <div id="select_gravity_form" style="display:none;">
       // ...not shown - html for the form
   }

Approach two: use WordPress’ filters and hooks

Due to a code change in WordPress 3.3, you can no longer use your own media button if you want to create a menu with custom tabs (or, at least, I couldn’t figure out how). With this approach, your menu will be accessible as a new tab in WordPress 3.3′s unified media menu. I’ll use code from my Shashin plugin as an example.

1. Register the function that will add tabs to the media menu. The function then adds tabs to the media menu array ($tabs contains the pre-defined WordPress menu tabs)

   add_filter('media_upload_tabs', array($this, 'addMediaMenuTabs'));
   
   public function addMediaMenuTabs($tabs) {
       $shashinTabs = array(
           'shashinPhotos' => __('Shashin Photos', 'shashin'),
           'shashinAlbums' => __('Shashin Albums', 'shashin')
       );
       return array_merge($tabs, $shashinTabs);
   }

2. Use the media_upload_* action to register the functions that will load the contents for the Shashin menus. It’s crucial that the last portion of the action name match the array keys added to the tabs in the previous step.

   add_action('media_upload_shashinPhotos', array($this, 'initPhotoMediaMenu'));
   add_action('media_upload_shashinAlbums', array($this, 'initAlbumMediaMenu'));

3. For the remaining steps I’ll just show the “shashinPhotos” tab, as the albums one is similar. Calling admin_print_styles with -media-upload-popup lets you pass your own css file to the media menu, for your custom tab. wp_iframe loads your html into menu.

   public function initPhotoMediaMenu() {
       add_action('admin_print_styles-media-upload-popup', array($this, 'displayMediaMenuCss'));
       return wp_iframe(array($this, 'mediaDisplayPhotoMenu'));
   }

4. Load your custom css

   public function displayMediaMenuCss() {
       $cssUrl = plugins_url('/Display/', __FILE__) .'media.css';
       wp_enqueue_style('shashinMediaMenuStyle', $cssUrl, false, $this->version);
   }

5. It’s crucial for this function name to start with the word media. WordPress uses this as a cue to load its standard css for the ThickBox window. Without it, the tabs and other aspects of the window will not get the correct layout. media_upload_header loads the menu tabs. After that, put in your javascript and html for what you want to display for this tab. Like the Gravity Forms example above, you need to call WordPress’ send_to_editor javascript function to insert the final result into the editor.

   public function mediaDisplayPhotoMenu() {
       media_upload_header();
   
       // ... not shown - javascript and html for the menu
   }

Before WordPress 3.3, the Shashin plugin had its own media button, that launched a media menu with two custom tabs. From what I can tell, there is no straightforward way to do this in WordPress 3.3. It used to be possible to have tabs that were independent of the tabs that are part of the standard WordPress media uploader. But now if you want to have custom tabs, you can’t have them as part of a custom menu – you have to add them to the existing media uploader tabs. So for Shashin, I decided to take this approach, as the only alternative would be to add two buttons to the media button bar, and have two separate media menus instead of one menu with two tabs.

Update 12/13: the Shashin media menu is not working in WordPress 3.3. I’ll see how they’ve changed the media menu and try to have a fix in the next few days. In the meantime, you can still add shortcodes by hand (you can see the album ids and photo ids in the Shashin Tools menu).

Update 12/14: ….And I just uploaded a fix – version 3.0.9. Note that the Shashin media menus are now available as tabs within WordPress 3.3′s new, unified media menu. So Shashin no longer has it’s own media button. I’ll explain why in an upcoming post.

Last night I uploaded Shashin 3.0.8. If you were browsing photos in one album after another, in some circumstances you’d get spurious Highslide navbars stacking up on the top left side of the page. It’s fixed now. It had to do with the complexities of having different kinds of photo groupings going on at the same time in Shashin – there can be multiple groups of albums on a page, groups of photos within albums, photo-by-photo navigation within Highslide, and “page-by-page” navigation using the Shashin “next” and “previous” links. Getting all of them working together seamlessly has proven to be the most challenging (and therefore rewarding!) part of working on Shashin.

I expect this to be the last maintenance release for Shashin 3.0 (knocking on wood, crossing fingers…). For 3.1 I am planning to add support for Highslide thumbstrips and introduce lazy loading of the photos. I had done some initial work on adding Flickr support, but the Flickr API is fairly complex, so I’m going to put off Flickr to version 3.2, as I’ve been getting a lot of requests for the thumbstrips feature.

Please use the comments section for any support questions.

Video of my Clean Code for WordPress presentation at WordCamp Philly is available at wordpress.tv. You can also check out the other presentation videos available so far. Every session was recorded, so eventually they’ll all be online (Doug Stewart is doing a great job editing them, so they’re worth the wait). Poka Yoke Design provided the photography, and they’ve posted a bunch of great pictures. Here are a few they took of me.

View at Picasa WordCamp Philly 201105-Nov-2011 14:11, NIKON CORPORATION NIKON D7000, 2.8, 70.0mm, 0.005 sec, ISO 400

View at Picasa My presentation at WordCamp Philly 201105-Nov-2011 11:31, NIKON CORPORATION NIKON D7000, 2.8, 70.0mm, 0.006 sec, ISO 3200

View at Picasa My WordCamp Philly 2011 presentation05-Nov-2011 11:31, NIKON CORPORATION NIKON D7000, 2.8, 24.0mm, 0.006 sec, ISO 3200

Update 11/21: I’ve upload Shashin 3.0.5, which fixes this issue, reported in the wordpress.org forums

I uploaded two updates to wordpress.org last night – one for Shashin and one for Toppa Plugin Libraries for WordPress. They address a couple bugs in Shashin:

• Automatic photo cropping is now done when appropriate when parsing the old Shashin shortcode format
• At least a few people have had problems with showing album photos when clicking an album thumbnail. In some cases this was being caused by how I was detecting whether to use http or https for AJAX calls. This is fixed now.

Another cause of the album thumbnail clicks not working is the jQuery form validation plugin. This plugin comes with the Arras theme. I’m still investigating why (there are no forms in Shashin, so offhand I don’t know why there would be a conflict). If you want to temporarily disable the form validation in Arras, go to line 46 in its header.php file and comment it out, like this:

//wp_enqueue_script('jquery-validate', get_template_directory_uri() . '/js/jquery.validate.min.js', 'jquery', null, false);

The Toppa Plugin Libraries update also include a new class for simplifying management of plugin settings (for any plugin that wants to use it). I’ll document it shortly.

Please use the comments section of this post to report any other issues.

I uploaded some Shashin fixes yesterday. Thanks everyone for the feedback. These were the changes:

• Fixed display of “crop” input field on media menu for photos and albums (it wasn’t showing the option for you to crop)
• Improved exception handling (there were a few cases where you could end up with an uncaught exception, which is not nice if there’s a problem)
• Handle commas in “exposure” in EXIF data (there’s at least one camera model that included a comma in the exposure value, so Shashin now handles it as a string instead of a number).

Please use the comment section for reporting problems. I have a hectic week coming up, so it may take me a few days to respond to feedback. Thanks for your patience.

Update 11/21: Video of my presentation is now available at wordpress.tv, and I put up a post yesterday with more pictures.

My Clean Code for WordPress presentation at Philly WordCamp View at Picasa My Clean Code for WordPress presentation at Philly WordCamp05-Nov-2011 11:19, Canon Canon PowerShot SD780 IS, 3.2, 5.9mm, 0.033 sec, ISO 400

WordCamp Philly this past weekend was a blast, and I met a lot of great people. The vibrancy of the WordPress community here in Philly is impressive. Giving my Clean code for WordPress presentation was also a lot of fun. I got vigorous agreement from the audience that more evangelism for clean code in WordPress plugins is definitely needed. Video of my presentation will be online at wordpress.tv in a few weeks.

The youngest attendee was 10 years old. He came to the developers’ day on Sunday too. The organizers were planning to guide him through fixing a bug in WordPress core, so he could be the youngest contributor to WordPress and get his name on the official credits. I spent the developers’ day getting started on adding Flickr support to Shashin. I’m not a Flickr user, but I was sitting next to Captin Shmit, who is, and he had a lot of useful suggestions. Thanks Captin! (yes that’s how he spells it).

Below are the slides from my presentation (if you click the link, it will take you to slideshare.net, where you can also see my notes for the slides).

Tonight I pushed a set of updates to Shashin that should address most of the issues people have reported in the last 24 hours. I tried to be thorough in the development and beta testing, so I’m glad to see most of the issues are minor. Thanks everyone for the detailed reports. Note you will also need to update Toppa Plugin Libraries for WordPress. Here’s the list of updates in Shashin 3.0.2 (from the readme file):

• Album photos table now inherits position from parent album thumbnail table
• Now handles Shashin 2 shashin_album_key query string arg, for old links
• Bug fix: numeric fields (like photo count, pub date) were getting cleared when updating ‘include in random’ settings for albums
• Bug fix: now checks for ‘include in random’ flag on albums and photos when generating random thumbnail display
• Bug fix: fixed size for album thumbnails using old shortcode format
• Aligned ‘update include in random’ button on Tools menu with radio button column
• Updated explanation on Settings menu for photo thumbnails
• Added .pot translation file