jquery.showhide.js

Author: Dana Woodman
Version: 0.1
Licence: MIT

Comments and questions can be directed at woodman.dana (at) gmail.com

Contents

  1. Introduction
  2. Getting started
  3. Examples
  4. Configuration
  5. Download
  6. Compatability
  7. Support
  8. Credits

Introduction

The showhide plugin is an advanced version of the jQuery "toggle" function. It adds in many useful options for controlling of a target element. The primary use is to show/hide a target HTML element by clicking on a "toggle" element (usually a link).

The plugin allows you to:

The plugin is called showhide because that is what it is primarily intended for: showing/hidding of a target element. This does not mean, however, that you need to use it for showing/hidding elements. You could use it to toggle the style of a target element (not just hiding it).

Getting started

Using showhide is fairly simple. The first step is to put this in the head of your page:

<script type="text/javascript" src="/path/to/jquery-latest.js"></script> 
<script type="text/javascript" src="/path/to/jquery.showhide.js"></script>

Next, create your HTML. Here is an example of the bar minimum you need to use showhide (see Examples for more uses):

<p>
    <a href="#" title="Toggle the span" id="example-1">Toggle</a>
    <span>This can be toggled.</span>
</p>

Now add in the jQuery code to call the showhide plugin:

<script type="text/javascript">
    $(function() {
        $('#example-1').showhide();
    });
</script>

And then add in the CSS to hide the target object:

<style type="text/css">
    .hide { display: none; }
</style>

... and you should be up and running.

Examples

Basic example

A simple inline toggle using no options. By default showhide will toggle the next element (e.g. $(this).next()) and will default the target object to be visible.

Example:
Toggle This can be toggled.
HTML:
<p>
    <a href="#" title="Toggle the span" id="example-1">Toggle</a>
    <span><strong>This can be toggled.</strong></span>
</p>
jQuery:
$('#example-1').showhide();

Declaring a custom target

Use the target_obj option to set an object other than .

Example:

Toggle

This can be toggled.

HTML:
<p><a href="#" title="Toggle the span" id="example-2">Toggle</a></p>
<p><strong>This can be toggled.</strong></p>
jQuery:
<script type="text/javascript">
    $(function() {
        $('#example-2').showhide({
            target_obj: $('#example-2').parent().next();
        });
    });
</script>

Configuration

showhide has many configuration options. The table below lists all the options available, what data type they are, their default and how to use them.

Property Type Default Description
target_obj DOM element null

The DOM element to show/hide. Example of using a jQuery object:

$('#toggle').showhide({
    target_obj: $('#target');
});

Another example, this time using a reference to "self" (e.g. the "#toggle" DOM element):

$('#toggle').showhide({
    target_obj: $(this).parent().next();
});

This will select the toggle element parent's nearest sibling.

Default object is the next object (e.g. $(this).next()).
focus_target DOM element null

A DOM input element to automatically focus on after showing (e.g. use the JavaScript .focus() function on the input). This is used to automatically put the text cursors focus on a form field. For example, this will focus on an input field with the id of "id_title":

$('#toggle').showhide({
    focus_target: $('#id_title');
});
default_open Boolean true

Whether or not to show the target element by default. If true, show the target. If false, hide the target on DOM load.

If you enable cookies, the cookie value will override this.
show_class String 'show'

The CSS class to apply to the target element to show it.
hide_class String 'hide'

The CSS class to apply to the target element to hide it.
plus_class String 'plus'

The CSS class to apply to the toggle element when the target is shown.

Useful if you want to apply a "plus"/"minus" image to the toggle element VIA CSS.
plus_text String null

The text to replace the toggle elements text with when shown.

Useful if you want the text to change when the user clicks the toggle object (e.g. "Show form"/"Hide form").
minus_class String 'minus'

The CSS class to apply to the toggle element when the target is hidden.

Useful if you want to apply a "plus"/"minus" image to the toggle element VIA CSS.
minus_text String null

The text to replace the toggle elements text with when hidden.

Useful if you want the text to change when the user clicks the toggle object (e.g. "Show form"/"Hide form").
use_cookie Boolean false

Indicates whether or not to store the user's choice in a cookie.

This is useful if you want user's to be able to set their preferences of hidden/visible elements.

NOTE: To use the cookie feature, you need to include the jQuery Cookie plugin on your page.
cookie_expires Number 365

Number of days before cookie should expire.
cookie_name String 'show_target'

The name of the cookie to store.

NOTE: This must be unique for every instance of showhide so there is no conflict of cookie values.

Download

Downloads are available VIA Google Code here:
http://code.google.com/p/jquery-showhide/downloads/list

Compatability

showhide should be compatable with the following browsers:

If you find a browser bug or issue, please contact me at woodman.dana (at) gmail.com and let me know about it.

Support

Please email me at woodman.dana (at) gmail.com for help.

For general jQuery help, check out the Google Group.

Credits

Written by Dana Woodman: woodman.dana (at) gmail.com