Tutorials

Robust and Clean ExpressionEngine Field Instructions with jQuery in the Control Panel

January 19, 2009
by Ryan Masuga

ExpressionEngine’s field instructions are a fantastic way to give your user all the information they need to effectively manage their content—but your notes may get lengthy and clutter up the Publish and Edit pages. With jQuery in the control panel it is easy to toggle extended instructions, and devot:ee will show you how.

jQuery togglePhoto by Ilja via flickr.

One of the easiest ways you can provide continued support to your clients after rolling out an ExpressionEngine site is through judicious use of the instructions on each of the custom fields in your weblogs. Explicit instructions are low maintenance for you, and always there for your client.

It’s not uncommon to have 30 or more fields in a weblog, which can be overwhelming for someone who has to publish a new article, news item, or anything else. If you commonly make use of instruction fields (especially with very long, detailed instructions), then the Publish and Edit pages can look even more confusing, even though the instructions are there to help. How to make sure that our client isn’t overwhelmed by the unbelievable amount of control you have given them, particularly on complex fields? Introducing a simple jQuery toggle to the control panel instruction fields is one method. Presented here is an easy way to keep the Publish and Edit screens in your EE control panel clean, but still allow for very detailed instructions for your client.

jQuery Powers…Activate!

The 20081024 build of ExpressionEngine 1.6.5 bundled a new extension called jQuery for the Control Panel. With more and more of todays’ 3rd-party EE add-ons requiring jQuery, it is probably in your best interest to activate this extension first thing on a new install (it is not activated by default). With that activated, you’re ready to add some simple toggles to your instructions.

The Code

Now that jQuery is activated and available for use in the Control Panel, the basic code you need for a toggle in the instructions of a custom field is like so:

<script type="text/javascript">
$(document).ready( function(){
 $('#moreinfo1').hide();
 $("#revealinfo1").click(function(){
 $("#moreinfo1").slideToggle(600);return false;
 });
});
</script>
<a id="revealinfo1" href="#">More</a>
<div id="moreinfo1" style="display:none;">
</div>

This introduces three things:

  1. A short script that will toggle a div with the id of “moreinfo1” by clicking a link with the id of “revealinfo1” (The way it’s written here will slide reveal with a relatively quick speed. Feel free to adjust that to your taste with your own mad jQuery skills)
  2. The link for the above script that will toggle the div
  3. The div that will show/hide when the link is clicked

You should be able to introduce more than one toggle per instruction field if needed, or on multiple fields, but remember that if you have more than one toggle on a Publish or Edit page, that the IDs will need to be unique.

Fleshing out Example Instructions

Let’s say the Custom Field I’m editing is field_id_23, and this field is somewhat complex with a multiple image button (this is based on a real field I’ve done that uses MD Markitup in conjunction with Moxiecode Image Manager). I’ll use the field_id_ number as the toggle ID on my instructions, because I can be sure that it’s unique.

There are a lot of instructions for the multi-image button, but because they don’t always insert images here, it’s not necessary for the client to see all the photo instructions every time—a perfect opportunity to use a toggle to hide these notes.

I start by pasting in the code for a toggle. I jam the JavaScript together on one line just to keep the instruction field compact. I also add “23” after the ID’s in the script (five places):

<script type="text/javascript">$(document).ready( function(){$('#moreinfo23').hide();$("#revealinfo23").click(function(){$("#moreinfo23").slideToggle(600);return false;});});</script>
<a id="revealinfo23" href="#">More</a>
<div id="moreinfo23" style="display:none;">
</div>

This field also has some general instructions, and I can put those after the closing “</script>” and before the “More” Link. I’ll also add the lead up to the Multi Image button and change the text of the button to be more descriptive.

Keep in mind that you can put HTML in the instructions fields, but they aren’t touched by the typography class, so there is no “XHTML” formatting here. You’ll have to add your own line breaks and remember to wrap your paragraphs. I generally don’t wrap paragraphs, and use linebreaks to separate blocks.

<script type="text/javascript">$(document).ready( function(){$('#moreinfo23').hide();$("#revealinfo23").click(function(){$("#moreinfo23").slideToggle(600);return false;});});</script>
This is a complicated field. That multi-image button is a bear.<br />
<br />
<b>Multi Image Button</b><br />
The multi image button is very complicated, and requires a lot of instructions - but we don't always use the button, so we don't need to see the instructions all the time.<br />
<a id="revealinfo23" href="#">Click for more extensive info on the multi image insert button &raquo;</a>
<div id="moreinfo23" style="display:none;">
</div>

Now all that is left to do is put all the instructions in the <div>. The instructions here are an example from a site I worked on, modified slightly to make a little more sense here out of context.

<script type="text/javascript">$(document).ready( function(){$('#moreinfo23').hide();$("#revealinfo23").click(function(){$("#moreinfo23").slideToggle(600);return false;});});</script>
This is a complicated field. That multi-image button is a bear.<br />
<br />
<b>Multi Image Button</b><br />
The multi image button is very complicated, and requires a lot of instructions - but we don't always use the button, so we don't need to see the instructions all the time.<br />
<a id="revealinfo23" href="#">Click for more extensive info on the multi image insert button &raquo;</a>
<div id="moreinfo23" style="display:none;">
There are three sub-buttons: <b>"1. Image Left, Caption Left, Wrap Existing Pic"</b>, <b>"2. Image Left, Caption Left, Insert New Pic"</b>, and <b>"3. Insert Image (Left), No Caption"</b>. For captioned images, there are four possible classes:<br /><br />
.image-left-caption-left <b>(default)</b><br />
.image-left-caption-right<br />
.image-right-caption-left<br />
.image-right-caption-right<br /><br />
The classes are pretty self-explanatory. If you prefer the image to the right side of the article, change the default "image-left" to "image-right", and the caption can be aligned to the right or left by changing the word after "caption". By default, captioned images are to the left, and the captions are text-aligned left.
<br /><br />
<b>1) Image Left, Caption Left, Wrap Existing Pic.</b> Select an image tag already in the field, and click this button to wrap it with the code for a caption. This will <i>not</i> open the image editor.
<br />
<b>2) Image Left, Caption Left, Insert New Pic.</b> Clicking this button will open the image editor, and wrap it with the code for a "captioned" div. Make sure to note the width of your image so you can edit the width of the div.
<br />
<b>3) Insert Image (Left), No Caption.</b> This inserts an image with no "captioned" div, and no caption. This defaults to a class of "imageleft", but you can float the image to the right by changing that to "imageright".
<br /><br />
<i><b>Remember:</b> On all captioned images the width of the ".captioned" div should be the same width as the image it contains, and you may have to set this manually if you are wrapping existing images. And don't forget your caption.</i><br />
&lt;div class="captioned image-left-caption-left" style="width:<span style=" color:#c00;">00</span>px;"&gt;&lt;img src="/image.jpg" /&gt;<span style=" color:#c00;">Caption</span>&lt;/div&gt;
</div>

Now You Don’t See It, Now You Do

Here are before and after pics of the toggled field.

jQuery toggle - beforeBefore: Before revealing the hidden div full of information.

Before clicking the toggle link, the field looks pretty clean. From top to bottom we see the field name, the general instructions, then our Multi Image Button instructions block. Then, because this happens to be an MD Markitup field, we also see an optional Textile documentation link, and the row of buttons assigned to this field. At this point, we click the link to show all the hidden information.

jQuery toggle - afterAfter: The hidden div full of information in the open state.

After the reveal, the user has all the extra info specific to inserting an image.

This is a pretty simple solution that has worked for me on fields that needed detailed information and would have just cluttered up the page had they been left alone. I’m sure this technique can be improved or expanded upon (what can’t?).

Until then, happy toggling!

Have a better solution? Have an easier way to implement this sort of thing? Can you improve the examples here? We’re all ears. Let us know in the comments.

18 Comments:

Brandon Kelly 01.19.09

Great article, Ryan. Which extension do you recommend to write all that extra copy, though? :-)

Chad Crowell 01.19.09

Oh Ryan, how do you get any work done if you are always working out all these killer tips for, um, getting work done?

Philip Zaengle 01.19.09

Great write up Ryan, like Brandon said, now we just need something that will generate really helpful descriptions for each field.

Philip Zaengle 01.19.09

@ chad, I think Ryan took the month of January off to focus on devotee.

Chad Crowell 01.19.09

@philip – ya I know.  I just like teasing him :)

Ryan Masuga 01.19.09

Ryan Masuga

Brandon: For writing such lengthy stuff there is an extension called “Tolstoy” that generates reams of text. That extension works great with one called “Stretch Timestrong” which gives you extra hours in the day. Actually these don’t exist, but they should. Do you have any extra time to develop them?

Chad: I never get anything done, actually. I spend most of my time writing overly detailed instructions.

Peter 01.19.09

Nice writeup, although I actually use another handy extension for this, what was it called again, Dulee, hmm :)

Philip Zaengle 01.19.09

@chad he’s lucky eh? wish I could quit client work for a month (or two) :) I hear he’s making some side money with he extra good looks…

Travis Schmeisser 01.19.09

I’ve been waiting for this since you mentioned it on Twitter a while back. GREAT tip thanks for the write up!

John Faulds 01.19.09

I’ve been working on a method recently that involves setting up a user-guide weblog that contains two entries – one for a general guide relating to creating, editing & deleting entries and to the usage of TinyMCE and its file and image management plugins; and one for guidelines specific to each site that relate to the usage of custom fields. Both are illustrated with screenshots.

The general guide also links to a template where I display videos that further demonstrate how to use TinyMCE. Because the general guide is not site specific, I can create the videos once, host them from a central location and serve them up to each individual site; likewise with most of the screenshots. And the entries and templates of the user-guide is easily duplicated from one site to another.

I then use your Dulee Noted extension to add a nice big link to the user guide at the top of every publish/edit form (the user guide link in the site links nav also points to the same location) and use Brandon Kelly’s Gypsy extension to add that custom field to all the different weblogs.

The advantage your method has over mine is that the instructions can appear on the same page as you’re working. The advantage mine has is that you can provide more detailed instructions with illustrations and video, but you do need to open separate windows or tabs.

John Faulds 01.19.09

Another idea that would be halfway between yours and mine (for fields requiring lengthier descriptions) would be you could load the content from your user guide into the same window using some sort of modalbox script.

Casey Reid 01.19.09

Another awesome tip Ryan. Between all the add-ons and tricks of yours I use, my CP is full of your handy-work.

Ryan Masuga 01.19.09

Ryan Masuga

John: Good stuff, thanks for the feedback. I have placed screenshots into instruction fields before, and I’ve also used a method similar to yours where I link to an external page from an instruction field. The external page has been an EE page with access restrictions set on it, but not tied to a weblog.

Paul Frost 01.23.09

You do seem to have the knack of coming up with things that should be part of the default EE install or in the official User Guide.

This is so quick to do and will save loads of support requests.

As has been said before, I don’t know where you find the time, but glad you do!

Ben Seigel 01.23.09

I like the modal box idea. I’ve had good results with Facebox, a jQuery plugin, on the public site.  I guess there’s no reason not to use in within EE control panel.

Rob Butz 01.27.09

You know what would be sweet? In the very last field on a long data entry form, a link that scrolls you (via jQuery) to the “topBar” div on the control panel page with a friendly reminder to hit “Submit” or “Update.” After a long data entry form, it’s nice to not have to scroll back to the “I’m done” buttons.

Ryan Masuga 01.27.09

Ryan Masuga

Rob: My idea was to have an extension that actually duplicates the Submit/Update button area at the bottom of the entry. That way, you wouldn’t have to scroll at all. I don’t have any time to work on that myself, but if it inspires anyone reading this…go for it!

Ben Seigel 02.04.09

Update: I tried the modal approach with Facebox, a jQuery plugin, but no dice.  It puts the div at the very bottom of the page. Presumably it interferes somehow with EE’s divs and javascript.  So now I will try Ryan’s method.

You must be registered member to comment. If you're already a member, log in now, and if not go register (it's free and easy!).