ToggleVal 2.1

Summary

ToggleVal gives you the option to populate the default text of form fields (in a few different ways), and will then toggle the default value when the field receives and loses keyboard focus.

Download Donate

Updates

January 19, 2009: ToggleVal 2.1 is released. This release adds a couple new features, including the ability to specify default text directly from the toggleVal() function (using populateFrom: "custom" and the new text option), and includes a new destroy method that removes ToggleVal functionality from an element. Also, 2.1 uses the data attribute for all comparison logic, which proves to be much more reliable. Version 2.1 is fully compatible with jQuery 1.3, and you can now download a minified version of the plugin!

January 7, 2009: ToggleVal 2.0.2 is released. This is a very minor maintenance update that fixes an error when using a compressor such as Packer.

December 15, 2008: ToggleVal 2.0.1 is released. This minor update adds a jQuery data attribute of defText to each field affected by ToggleVal. This attribute stores the default text of the field, which can be utilized to compare fields to previous states. See the fourth example for details.

December 15, 2008: ToggleVal project is now hosted at Google Code!

September 14, 2008: ToggleVal version 2.0 goes public today, as does a new Web site. The entire plugin has been rewritten, so if you are currently using it please pay extra close attention to the documentation, as your old scripts may break.

Basic Usage

$(element).toggleVal();

$(element).toggleVal({ options });

$(element).toggleVal("destroy");

Available Options

focusClass (optional)

Specifies a class name to be added to an element when it has keyboard focus. Defaults to tv-focused if not specified.

changedClass (optional)

Specifies a class name to be added to an element when it has been changed from its default value. Defaults to tv-changed if not specified.

populateFrom (optional)

Tells ToggleVal where to get the text for the field's default value. You can choose one of the following settings:

text (optional)

This can only be used when using populateFrom: "custom". Specify a string of text to populate the target element(s) on the fly, rather than using hard-coded attributes in the DOM.

removeLabels (optional)

This should really only be used when using populateFrom: "label". If set to true, the associated <label> will be removed, so as to prevent redundant text. Defaults to false.

Methods

destroy

Use this method if you want to remove ToggleVal's focus and blur event listeners from an element that currently has ToggleVal's functionality applied to it. When using this, you may not pass an options object to the ToggleVal function.

Examples

Without options

<input type="text" name="name" value="Your name" />

<script type="text/javascript">
  $("input[name='name']").toggleVal();
</script>

Using populateFrom: "label" and removeLabels: "true"

<label for="txtEmail">E-mail address</label>
<input type="text" id="txtEmail" name="email" />

<script type="text/javascript">
  $("#txtEmail").toggleVal({
    populateFrom: "label",
    removeLabels: true
  });
</script>

Special styling for focusClass and changedClass

Note: Default text should be a light gray, focused text should be bold and black, and changed text should be bold and red.

<textarea name="message" rows="5" cols="30">
  Type your message here... the colors of the text ↵
  will change!
</textarea>

<script type="text/javascript">
  $("textarea").toggleVal({
    focusClass: "hasFocus",
    changedClass: "isChanged"
  });
</script>

Clearing unchanged fields on submit

Note: Try changing one field, leaving one unchanged, and submitting the form while focus is in the remaining field (hit the Return/Enter key)… take a look at the query string after submission to see the values!

<form action="test.html" method="get">
  <div><input type="text" name="test1" value="Test 1" /> ↵
  </div>
  <div><input type="text" name="test2" value="Test 2" /> ↵
  </div>
  <div><input type="text" name="test3" value="Test 3" /> ↵
  </div>
  <div><input type="submit" value="Submit" /></div>
</form>

<script type="text/javascript">
  $("form :text").toggleVal();
  $("form").submit(function() {
    $(this).find(".toggleval").each(function() {
      if($(this).val() == $(this).data("defText")) {
        $(this).val("");
      }
    });
  });
</script>

Using custom text

<input type="text" name="name2" />

<script type="text/javascript">
  $("input[name='name2']").toggleVal({
    populateFrom: "custom",
    text: "What is your name?"
  });
</script>

Using the destroy method

<input type="text" name="testField" value="Testing..." />
<a id="disable" href="#">Disable ToggleVal</a>

<script type="text/javascript">
  $("input[name='testField']").toggleVal();
  $("#disable").click(function() {
    $("input[name='testField']").toggleVal("destroy");
    return false;
  });
</script>

Additional Notes

Download Donate