updated docs; added invert option for LinkBehavior

fivepointssolutions · Apr 8, 2010 · 64b18e8 · 64b18e8
1 parent a1ecf0e
commit 64b18e8
Show file tree

Hide file tree

Showing 9 changed files with 155 additions and 119 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/README → README.markdown b/README → README.markdown
@@ -1,35 +1,41 @@
-toggle.js
+ToggleJS
+========
 
-dependencies: prototype.js, lowpro.js, effect.js
+ToggleJS is a LowPro and Prototype-based library with a collection of 
+behaviors for unobtrusively toggling the visibility of other elements via 
+links, checkboxes, radio buttons, and selects.
 
---------------------------------------------------------------------------
+Dependencies: prototype.js, lowpro.js, effect.js
+
+Homepage: <http://github.com/fivepointssolutions/togglejs>
 
-A LowPro and Prototype-based library with a collection of behaviors for
-unobtrusively toggling the visibility of other elements via links,
-checkboxes, radio buttons, and selects.
 
-To use you will need to install the following LowPro behaviors. If you are 
-using Rails, put this in "application.js":
+Using ToggleJS
+--------------------------------------------------------------------------
+
+To use ToggleJS you will need to have Prototype and LowPro installed and 
+loaded, and the following LowPro behaviors will need to be configured. If 
+you are using Rails, put this in "application.js":
 
-  Event.addBehavior({
-    'a.toggle': Toggle.LinkBehavior(),
-    'input.checkbox.toggle': Toggle.CheckboxBehavior(),
-    'div.radio_group.toggle': Toggle.RadioGroupBehavior(),
-    'select.toggle': Toggle.SelectBehavior()
-  });
+    Event.addBehavior({
+      'a.toggle': Toggle.LinkBehavior(),
+      'input[type=checkbox].toggle': Toggle.CheckboxBehavior(),
+      'div.radio_group.toggle': Toggle.RadioGroupBehavior(),
+      'select.toggle': Toggle.SelectBehavior()
+    });
 
-Once the hooks are installed correctly, you should add a "rel" attribute
+Once the hooks are installed correctly, you should add a `rel` attribute
 to each element that you want to use as a toggle trigger. Set the value
-of the "rel" attribute to "toggle[id]" where id is equal to the ID of
+of the `rel` attribute to "toggle[id]" where id is equal to the ID of
 the element that you want to toggle. You can toggle multiple elements by 
 separating the IDs with commas (like this: "toggle[id1,id2,id3]").
 
 For example, a link with a class of "toggle":
 
-  <a class="toggle" href="#more" rel="toggle[more]">More</a>
+    <a class="toggle" href="#more" rel="toggle[more]">More</a>
 
-will become a trigger for a div with an ID of "more". Checkboxes work in
-the exact same manner. To use with a group of radio buttons, make sure
+...will become a trigger for a div with an ID of "more". Checkboxes work
+in the exact same manner. To use with a group of radio buttons, make sure
 that all of the radio buttons are inside of a div with a class of
 "radio_group toggle". Then set the "rel" attribute on each radio button
 that should act as a toggle trigger. Selects work in a similar manner,
@@ -39,11 +45,11 @@ toggle the visibility of an element or array of elements.
 Each of the included LowPro behaviors can be customized in various ways.
 Check out the inline documentation for detailed usage information.
 
-Project Homepage: http://github.com/fivepointssolutions/togglejs
 
+License and Copyright
 --------------------------------------------------------------------------
 
-Copyright (c) 2007-2010, Five Points Solutions, Inc.
+Copyright (c) 2007-2010, Five Points Solutions, Inc.  
 Copyright (c) 2010, John W. Long
 
 Permission is hereby granted, free of charge, to any person obtaining a

diff --git a/Rakefile b/Rakefile
@@ -1,4 +1,4 @@
-desc 'Launch the testing server on port 4000'
+desc 'Open the demo document in the default web browser'
 task :demo do
   `open demo.html`
 end
@@ -8,7 +8,7 @@ task :clean do
   rm_rf 'dist'
 end
 
-file 'dist/toggle.js' => ['README', 'src/javascripts/toggle.js'] do |t|
+file 'dist/toggle.js' => ['README.markdown', 'src/javascripts/toggle.js'] do |t|
   target = t.name
   unless uptodate?(target, t.prerequisites)
     readme = IO.read(t.prerequisites.first)
@@ -41,18 +41,18 @@ desc 'Assemble files for distribution'
 task :dist => [:mkdist, 'dist/toggle.js', 'dist/toggle.min.js']
 
 desc 'Build documentation from source'
-task :doc do
+task :doc => :dist do
   gem 'treetop', '= 1.2.6' # PDoc seems to require this version right now
   gem 'pdoc', '0.2.0'
   require 'pdoc'
   rm_rf 'doc'
   mkpath 'doc'
-  files = FileList['src/javascripts/*.js']
-  files.exclude('prototype.js', 'effects.js', 'lowpro.js')
+  files = FileList['dist/*.js']
+  files.exclude('toggle.min.js')
   PDoc.run(
     :source_files => files,
     :destination => 'doc',
-    :index_page => 'README',
+    :index_page => 'README.markdown',
     :syntax_highlighter => :pygments,
     :markdown_parser => :bluecloth
   )

diff --git a/demo.html b/demo.html
@@ -53,7 +53,7 @@
         margin-bottom: 1em;
       }
 
-      #one, #three, #four, #five, #nine, #eleven {
+      #one, #three, #four, #five, #six, #ten, #twelve {
         margin-bottom: 0;
       }
       /* ]]> */
@@ -62,6 +62,7 @@
       //<![CDATA[
         Event.addBehavior({
           'a.toggle': Toggle.LinkBehavior(),
+          'a.inverted_toggle': Toggle.LinkBehavior({invert: true}),
           'a.open': Toggle.LinkBehavior({
             effect: 'blind',
             onLoad: function(link) {
@@ -83,7 +84,8 @@
     </script> 
   </head> 
   <body> 
-    <h1>toggle.js</h1> 
+    <h1>ToggleJS</h1>
+    <p>A LowPro and Prototype-based solution for unobtrusively toggling elements with effects.</p>
     <form> 
       <fieldset> 
         <h3>Toggle.LinkBehavior</h3> 
@@ -96,35 +98,42 @@ <h3>Toggle.LinkBehavior</h3>
         <p> 
           <a class="toggle" href="#two" rel="toggle[two,three]">Expand even more</a> 
         </p> 
-      </fieldset> 
+      </fieldset>
       <fieldset> 
-        <h3>Toggle.LinkBehavior (with custom event handlers)</h3> 
+        <h3>Toggle.LinkBehavior (inverted)</h3> 
         <div class="expand_me" id="four">Expanded!</div> 
         <p> 
-          <a class="open" href="#four" rel="toggle[four]">Open</a> 
+          <a class="inverted_toggle" href="#four" rel="toggle[four]">Close</a> 
+        </p> 
+      </fieldset>
+      <fieldset> 
+        <h3>Toggle.LinkBehavior (with custom event handlers)</h3> 
+        <div class="expand_me" id="five">Expanded!</div> 
+        <p> 
+          <a class="open" href="#five" rel="toggle[five]">Open</a> 
         </p> 
       </fieldset> 
       <fieldset> 
         <h3>Toggle.CheckboxBehavior</h3> 
         <p> 
-          <input class="checkbox toggle" id="checkbox1" name="checkbox1" rel="toggle[five]" type="checkbox" value="" /> 
+          <input class="checkbox toggle" id="checkbox1" name="checkbox1" rel="toggle[six]" type="checkbox" value="" /> 
           <label class="checkbox" for="checkbox1">Check for more</label> 
         </p> 
-        <div class="expand_me" id="five">Expanded!</div> 
+        <div class="expand_me" id="six">Expanded!</div> 
         <p> 
-          <input class="checkbox toggle" id="checkbox2" name="checkbox2" rel="toggle[six,seven]" type="checkbox" value="" /> 
+          <input class="checkbox toggle" id="checkbox2" name="checkbox2" rel="toggle[seven,eight]" type="checkbox" value="" /> 
           <label class="checkbox" for="checkbox2">Check for even more</label> 
         </p> 
-        <div class="expand_me" id="six">Expanded! 1</div> 
-        <div class="expand_me" id="seven">Expanded! 2</div> 
+        <div class="expand_me" id="seven">Expanded! 1</div> 
+        <div class="expand_me" id="eight">Expanded! 2</div> 
       </fieldset> 
       <fieldset> 
         <h3>Toggle.CheckboxBehavior (inverted)</h3> 
         <p> 
-          <input class="checkbox inverted_toggle" id="checkbox3" name="checkbox3" rel="toggle[eight]" type="checkbox" value="" /> 
+          <input class="checkbox inverted_toggle" id="checkbox3" name="checkbox3" rel="toggle[nine]" type="checkbox" value="" /> 
           <label class="checkbox" for="checkbox3">Check for less</label> 
         </p> 
-        <div class="expand_me" id="eight">Expanded!</div> 
+        <div class="expand_me" id="nine">Expanded!</div> 
       </fieldset> 
       <fieldset> 
         <h3>Toggle.RadioGroupBehavior</h3> 
@@ -134,34 +143,34 @@ <h3>Toggle.RadioGroupBehavior</h3>
             <label class="radio" for="option_1">None</label> 
           </p> 
           <p> 
-            <input class="radio" id="option_2" name="option" rel="toggle[nine]" type="radio" value="2" /> 
+            <input class="radio" id="option_2" name="option" rel="toggle[ten]" type="radio" value="2" /> 
             <label class="radio" for="option_2">Expand One</label> 
           </p> 
-          <div class="expand_me" id="nine">Expanded!</div> 
+          <div class="expand_me" id="ten">Expanded!</div> 
           <p> 
-            <input class="radio" id="option_3" name="option" rel="toggle[ten,eleven]" type="radio" value="3" /> 
+            <input class="radio" id="option_3" name="option" rel="toggle[eleven,twelve]" type="radio" value="3" /> 
             <label class="radio" for="option_3">Expand Two</label> 
           </p> 
-          <div class="expand_me" id="ten">Expanded!</div> 
           <div class="expand_me" id="eleven">Expanded!</div> 
+          <div class="expand_me" id="twelve">Expanded!</div> 
           <p> 
-            <input class="radio" id="option_4" name="option" rel="toggle[nine,ten,eleven]" type="radio" value="4" /> 
+            <input class="radio" id="option_4" name="option" rel="toggle[ten,eleven,twelve]" type="radio" value="4" /> 
             <label class="radio" for="option_4">Expand All</label> 
           </p> 
         </div> 
       </fieldset> 
-      <fieldset> 
+      <fieldset style="margin-bottom: 15em"> 
         <h3>Toggle.SelectBehavior</h3> 
         <p> 
           <select class="toggle" id="select" name="select"> 
             <option>&lt;select one&gt;</option> 
-            <option rel="toggle[twelve]" value="1">Option 1</option> 
-            <option rel="toggle[thirteen]" value="2">Option 2</option> 
-            <option rel="toggle[twelve,thirteen]" value="1,2">Both Options</option> 
+            <option rel="toggle[thirteen]" value="1">Option 1</option> 
+            <option rel="toggle[fourteen]" value="2">Option 2</option> 
+            <option rel="toggle[thirteen,fourteen]" value="1,2">Both Options</option> 
           </select> 
         </p> 
-        <div class="expand_me" id="twelve">Expanded! Option 1 selected</div> 
-        <div class="expand_me" id="thirteen">Expanded! Option 2 selected</div> 
+        <div class="expand_me" id="thirteen">Expanded! Option 1 selected</div> 
+        <div class="expand_me" id="fourteen">Expanded! Option 2 selected</div> 
       </fieldset> 
     </form> 
   </body> 

diff --git a/dist/toggle.js b/dist/toggle.js
@@ -1,36 +1,42 @@
 /*
- * toggle.js
+ * ToggleJS
+ * ========
  * 
- * dependencies: prototype.js, lowpro.js, effect.js
+ * ToggleJS is a LowPro and Prototype-based library with a collection of 
+ * behaviors for unobtrusively toggling the visibility of other elements via 
+ * links, checkboxes, radio buttons, and selects.
  * 
- * --------------------------------------------------------------------------
+ * Dependencies: prototype.js, lowpro.js, effect.js
+ * 
+ * Homepage: <http://github.com/fivepointssolutions/togglejs>
  * 
- * A LowPro and Prototype-based library with a collection of behaviors for
- * unobtrusively toggling the visibility of other elements via links,
- * checkboxes, radio buttons, and selects.
  * 
- * To use you will need to install the following LowPro behaviors. If you are 
- * using Rails, put this in "application.js":
+ * Using ToggleJS
+ * --------------------------------------------------------------------------
  * 
- *   Event.addBehavior({
- *     'a.toggle': Toggle.LinkBehavior(),
- *     'input.checkbox.toggle': Toggle.CheckboxBehavior(),
- *     'div.radio_group.toggle': Toggle.RadioGroupBehavior(),
- *     'select.toggle': Toggle.SelectBehavior()
- *   });
+ * To use ToggleJS you will need to have Prototype and LowPro installed and 
+ * loaded, and the following LowPro behaviors will need to be configured. If 
+ * you are using Rails, put this in "application.js":
  * 
- * Once the hooks are installed correctly, you should add a "rel" attribute
+ *     Event.addBehavior({
+ *       'a.toggle': Toggle.LinkBehavior(),
+ *       'input[type=checkbox].toggle': Toggle.CheckboxBehavior(),
+ *       'div.radio_group.toggle': Toggle.RadioGroupBehavior(),
+ *       'select.toggle': Toggle.SelectBehavior()
+ *     });
+ * 
+ * Once the hooks are installed correctly, you should add a `rel` attribute
  * to each element that you want to use as a toggle trigger. Set the value
- * of the "rel" attribute to "toggle[id]" where id is equal to the ID of
+ * of the `rel` attribute to "toggle[id]" where id is equal to the ID of
  * the element that you want to toggle. You can toggle multiple elements by 
  * separating the IDs with commas (like this: "toggle[id1,id2,id3]").
  * 
  * For example, a link with a class of "toggle":
  * 
- *   <a class="toggle" href="#more" rel="toggle[more]">More</a>
+ *     <a class="toggle" href="#more" rel="toggle[more]">More</a>
  * 
- * will become a trigger for a div with an ID of "more". Checkboxes work in
- * the exact same manner. To use with a group of radio buttons, make sure
+ * ...will become a trigger for a div with an ID of "more". Checkboxes work
+ * in the exact same manner. To use with a group of radio buttons, make sure
  * that all of the radio buttons are inside of a div with a class of
  * "radio_group toggle". Then set the "rel" attribute on each radio button
  * that should act as a toggle trigger. Selects work in a similar manner,
@@ -40,11 +46,11 @@
  * Each of the included LowPro behaviors can be customized in various ways.
  * Check out the inline documentation for detailed usage information.
  * 
- * Project Homepage: http://github.com/fivepointssolutions/togglejs
  * 
+ * License and Copyright
  * --------------------------------------------------------------------------
  * 
- * Copyright (c) 2007-2010, Five Points Solutions, Inc.
+ * Copyright (c) 2007-2010, Five Points Solutions, Inc.  
  * Copyright (c) 2010, John W. Long
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a
@@ -68,15 +74,13 @@
  */
 
 /**
- *  == Toggle ==
- *  
- *  Hello world!
- *  
- **/
+ * == Toggle ==
+ * 
+**/
 
 /** section: Toggle
  *  Toggle
- **/
+**/
 var Toggle = {
 
   DefaultEffect: 'slide',
@@ -228,6 +232,16 @@ Toggle.LinkBehavior = Behavior.create({
   initialize: function(options) {
     var options = options || {};
 
+    var elements = Toggle.extractToggleObjects(this.element.readAttribute('rel'));
+    this.toggleWrappers = elements.map(function(e) { return Toggle.wrapElement(e) });
+
+    this.invert = options.invert || false;
+
+    if (this.invert) {
+      this.effect = 'none';
+      this.toggle();
+    }
+
     this.effect = options.effect || Toggle.DefaultEffect;
 
     this.onLoad = options.onLoad || Prototype.emptyFunction;
@@ -239,9 +253,6 @@ Toggle.LinkBehavior = Behavior.create({
     this.afterToggle = options.afterToggle || Prototype.emptyFunction;
     this.afterToggle.bind(this);
 
-    var elements = Toggle.extractToggleObjects(this.element.readAttribute('rel'));
-    this.toggleWrappers = elements.map(function(e) { return Toggle.wrapElement(e) });
-
     this.toggleID = Toggle.extractAnchor(this.element.href);
     this.element.behavior = this; // a bit of a hack
     Toggle.addLink(this.toggleID, this.element);
@@ -259,8 +270,8 @@ Toggle.LinkBehavior = Behavior.create({
       this.toggleWrappers,
       this.effect,
       {
-        beforeStart: function() { this.beforeToggle(this.element) }.bind(this),
-        afterFinish: function() { this.afterToggle(this.element) }.bind(this)
+        beforeStart: function() { if (this.beforeToggle) this.beforeToggle(this.element) }.bind(this),
+        afterFinish: function() { if (this.afterToggle) this.afterToggle(this.element) }.bind(this)
       }
     );
   }