data/TWiki/BehaviourContrib.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Mon, 11 Aug 2008 20:33:37 +0200
changeset 2 7bc60a767fa4
parent 1 e2915a7cbdfa
permissions -rw-r--r--
TWiki-4.2.2 Release
     1 head	1.4;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.4
     9 date	2008.08.10.15.02.40;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	1.3;
    12 
    13 1.3
    14 date	2008.08.03.22.17.48;	author TWikiContributor;	state Exp;
    15 branches;
    16 next	1.2;
    17 
    18 1.2
    19 date	2008.01.22.03.21.31;	author TWikiContributor;	state Exp;
    20 branches;
    21 next	1.1;
    22 
    23 1.1
    24 date	2007.01.16.04.11.59;	author TWikiContributor;	state Exp;
    25 branches;
    26 next	;
    27 
    28 
    29 desc
    30 @buildrelease
    31 @
    32 
    33 
    34 1.4
    35 log
    36 @buildrelease
    37 @
    38 text
    39 @%META:TOPICINFO{author="TWikiContributor" date="1183913691" format="1.1" reprev="1." version="4"}%
    40 ---+!! !Behaviour Javascript framework Contrib
    41 
    42 This contrib packages the third-party =Behaviour= Javascript event library, available from http://bennolan.com/behaviour/.
    43 
    44 Behaviour uses CSS selectors to subscribe to javascript event handlers. This allows to create clean code, separated from HTML (and well suited to create javascript based interaction that degrades nicely when javascript is not available).
    45 
    46 %TOC{title="On this page:"}%
    47 
    48 
    49 ---++ Introduction
    50 From the website:
    51 <blockquote>
    52 After all the work of WASP and others to promote clean markup, valid pages and graceful degradation via css - it sucks that we're going back to tag soup days by throwing javascript tags into our html.
    53 
    54 The better way to do javascript is to do it unobtrusively. PPK and Simon Willison have been recommending this approach for ages. And it's definitely the way to go. The only problem is that it's a bit of a pain in the ass.
    55 
    56 That's why I came up with Behaviour - my solution to unobtrusive javascript behaviours.
    57 
    58 *How does it work?*
    59 
    60 Behaviour lets you use CSS selectors to specify elements to add javascript events to. This means that instead of writing:
    61 
    62 <verbatim>
    63 <li>
    64 	<a onclick="this.parentNode.removeChild(this)" href="#">
    65 		Click me to delete me
    66 	</a>
    67 </li>
    68 </verbatim>
    69 
    70 You can use:
    71 
    72 <verbatim>
    73 <ul id="example">
    74 	<li>
    75 		<a href="/someurl">Click me to delete me</a>
    76 	</li>
    77 </ul>
    78 </verbatim>
    79 
    80 And then use css selectors to select that element and add javascript functions to it.
    81 
    82 <verbatim>
    83 var myrules = {
    84 	'#example li' : function(el){
    85 		el.onclick = function(){
    86 			this.parentNode.removeChild(this);
    87 
    88 		}
    89 	}
    90 };
    91 
    92 Behaviour.register(myrules);
    93 </verbatim>
    94 </blockquote>
    95 
    96 
    97 
    98 ---++ Usage
    99 Include the javascript file:
   100 
   101 <blockquote>
   102 <verbatim>
   103 <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.js"></script>
   104 </verbatim>
   105 </blockquote>
   106 
   107 In your code you create a "rules" object, with sub-objects for each html element class name or id:
   108 <blockquote>
   109 <verbatim>
   110 var myrules = {
   111 	'.classname' : function(element) {
   112 		// element event
   113 		element.onclick = function() {
   114 			// code here
   115 		}
   116 	},
   117 	
   118 	'#id' : function(element) {
   119 		// element event
   120 		element.onclick = function() {
   121 			// code here
   122 		}
   123 	}
   124 };
   125 </verbatim>
   126 
   127 Or use nested identifiers:
   128 
   129 <verbatim>
   130 var myrules = {
   131 	'.menu li a' : function(element) {
   132 		element.onclick = function() {
   133 			// code here
   134 		}
   135 	}
   136 };
   137 </verbatim>
   138 </blockquote>
   139 
   140 Apply the rules with:
   141 
   142 <blockquote>
   143 <verbatim>
   144 Behaviour.register(myrules);
   145 </verbatim>
   146 </blockquote>
   147 
   148 
   149 
   150 ---+++ Example
   151 If we have a 'normal' link to TWiki Web hometopic: [[%TWIKIWEB%.%HOMETOPIC%][TWiki Web Home]], we can use javascript to make it open a popup window. When javascript is not available the link behaviour defaults to opening the page in the current window.
   152 
   153 <blockquote>
   154 <verbatim>
   155 <div id="demoblock" style="padding:1em; width:100px; text-align:center;">
   156 MOUSE OVER ME
   157 </div>
   158 
   159 <script type="text/javascript">
   160 // <![CDATA[
   161 var myrules = {
   162 	'#demoblock' : function(el) {
   163 		var defaultColor = '#A3D6F8';
   164 		var highlightColor = '#4A7FB5';
   165 		
   166 		el.style.backgroundColor = defaultColor;
   167 		
   168 		el.onmouseover = function() {
   169 			this.style.backgroundColor = highlightColor;
   170 			return false;
   171 		}
   172 		el.onmouseout = function() {
   173 			this.style.backgroundColor = defaultColor;
   174 			return false;
   175 		}
   176 	},
   177 	'#demoblock span' : function(el) {
   178 		
   179 		var text = el.innerHTML;
   180 		
   181 		var fisherYates = function (inArray) {
   182 		  var i = inArray.length;
   183 		  if ( i == 0 ) return false;
   184 		  while ( --i ) {
   185 			 var j = Math.floor( Math.random() * ( i + 1 ) );
   186 			 var tempi = inArray[i];
   187 			 var tempj = inArray[j];
   188 			 inArray[i] = tempj;
   189 			 inArray[j] = tempi;
   190 		   }
   191 		}
   192 		
   193 		var randomize = function(inText) {
   194 			var letters = inText.split('');
   195 			fisherYates(letters);
   196 			return letters.join('');
   197 		}
   198 		el.onmouseover = function() {
   199 			this.innerHTML = randomize(text);
   200 			return false;
   201 		}
   202 		el.onmouseout = function() {
   203 			this.innerHTML = text;
   204 			return false;
   205 		}
   206 	}
   207 };
   208 Behaviour.register(myrules);
   209 // ]]>
   210 </script>
   211 </verbatim>
   212 
   213 Creates:
   214 
   215 <div id="demoblock" style="padding:1em; width:150px; text-align:center;">
   216 <span>MOUSE OVER ME</span>
   217 </div>
   218 
   219 <script type="text/javascript">
   220 // <![CDATA[
   221 var myrules = {
   222 	'#demoblock' : function(el) {
   223 		var defaultColor = '#A3D6F8';
   224 		var highlightColor = '#4A7FB5';
   225 		
   226 		el.style.backgroundColor = defaultColor;
   227 		
   228 		el.onmouseover = function() {
   229 			this.style.backgroundColor = highlightColor;
   230 			return false;
   231 		}
   232 		el.onmouseout = function() {
   233 			this.style.backgroundColor = defaultColor;
   234 			return false;
   235 		}
   236 	},
   237 	'#demoblock span' : function(el) {
   238 		
   239 		var text = el.innerHTML;
   240 		
   241 		var fisherYates = function (inArray) {
   242 		  var i = inArray.length;
   243 		  if ( i == 0 ) return false;
   244 		  while ( --i ) {
   245 			 var j = Math.floor( Math.random() * ( i + 1 ) );
   246 			 var tempi = inArray[i];
   247 			 var tempj = inArray[j];
   248 			 inArray[i] = tempj;
   249 			 inArray[j] = tempi;
   250 		   }
   251 		}
   252 		
   253 		var randomize = function(inText) {
   254 			var letters = inText.split('');
   255 			fisherYates(letters);
   256 			return letters.join('');
   257 		}
   258 		el.onmouseover = function() {
   259 			this.innerHTML = randomize(text);
   260 			return false;
   261 		}
   262 		el.onmouseout = function() {
   263 			this.innerHTML = text;
   264 			return false;
   265 		}
   266 	}
   267 };
   268 Behaviour.register(myrules);
   269 // ]]>
   270 </script>
   271 
   272 
   273 ---+++ Leaking danger
   274 Behaviour code leaks memory on Windows Explorer prior to version 7. To prevent leaking, set the element variable to =null=:
   275 <blockquote>
   276 <verbatim>
   277 var myrules = {
   278 	'table.test td' : function(element) {
   279 		element.onmouseover = function() {
   280 			this.style.backgroundColor = highlightColor;
   281 			return false;
   282 		}
   283 		element = null; // by setting this IE will not leak  
   284 	}
   285 };	
   286 Behaviour.register(myrules);
   287 </verbatim>
   288 </blockquote>
   289 
   290 
   291 ---++ Development
   292    * [[http://groups.google.com/group/behaviour][Google Groups: Behaviour Javascript Library]]
   293    * [[http://www.nabble.com/Behaviour-Javascript-Library-f16264.html][Nabble - Behaviour Javascript Library forum & mailing list archive]]
   294    * [[http://groups.google.com/group/behaviour/browse_thread/thread/e9828f9fdb482ac1/8ca704730053e23f?#8ca704730053e23f][Behaviour2]] - update in the making, since 2006
   295 
   296 
   297 ---++ License
   298 Behaviour is freely distributable under the terms of an BSD license.
   299 For details see the Behaviour website.
   300 
   301 
   302 
   303 ---++ Links
   304    * [[http://bennolan.com/behaviour/][Behaviour website]]
   305    * [[http://groups.google.com/group/behaviour][Behaviour Google Group]]
   306 
   307 ---++ Installation Instructions
   308 You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
   309 
   310 Like many other TWiki extensions, this module is shipped with a fully
   311 automatic installer script written using the Build<nop>Contrib.
   312    * If you have TWiki 4.2 or later, you can install from the =configure= interface (Go to Plugins->Find More Extensions)
   313       * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.
   314    * If you have any problems, then you can still install manually from the command-line:
   315       1 Download one of the =.zip= or =.tgz= archives
   316       1 Unpack the archive in the root directory of your TWiki installation.
   317       1 Run the installer script ( =perl &lt;module&gt;_installer= )
   318       1 Run =configure= and enable the module, if it is a plugin.
   319       1 Repeat for any missing dependencies.
   320    * If you are *still* having problems, then instead of running the installer script:
   321       1 Make sure that the file permissions allow the webserver user to access all files.
   322       1 Check in any installed files that have existing =,v= files in your existing install (take care *not* to lock the files when you check in)
   323       1 Manually edit !LocalSite.cfg to set any configuration variables.
   324 
   325 %IF{"defined 'SYSTEMWEB'" else="<div class='twikiAlert'>%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your %MAINWEB%.TWikiPreferences, if they are not already there:<br><pre>   * <nop>Set SYSTEMWEB = %<nop>TWIKIWEB%<br>   * <nop>Set USERSWEB = %<nop>MAINWEB%</pre></div>"}%
   326 
   327 
   328 ---++ Contrib Settings
   329    * Set SHORTDESCRIPTION = =Behaviour= Javascript event library to create javascript based interactions that degrade well when javascript is not available
   330 
   331 You can also set the global TWiki variable BEHAVIOURCONTRIB_DEBUG to 1 to make the contrib use uncompressed javascript sources, in the event of problems.
   332 
   333 ---++ Contrib Info
   334 |  Author: | TWiki:Main.ArthurClemens |
   335 |  Copyright: | Code: =behaviour.js= version 1.1 - Copyright (c) Ben Nolan and Simon Willison. TWiki distribution and updates/additions: TWiki:Main.ArthurClemens. |
   336 |  License: | BSD |
   337 |  Version: | 15675 (11 Aug 2008) |
   338 |  Dependencies: | None |
   339 |  Contrib&nbsp;Version: | 1.3.1 |
   340 |  Change&nbsp;History: | <!-- specify latest version first -->&nbsp; |
   341 |  17 Oct 2007 | 1.3 Replaced "faster code" by other code from Dean Edwards, [[ packed by http://groups.google.com/group/behaviour/browse_thread/thread/85137977bedf5ed/3cf3ba8065d41a8c#3cf3ba8065d41a8c][Raymond Irving]]. |
   342 |  02 Jul 2007 | 1.2 Integrated other faster code by Dean Edwards: [[http://dean.edwards.name/weblog/2006/06/again/][faster onload (again)]]. |
   343 |  08 Mar 2007 | 1.1 Integrated code by Dean Edwards (see [[#CodeUpdate][Code update version 1.1 with faster DOM queries]]). |
   344 |  04 Jun 2006 | 1.0  First Version. Included Behaviour version: 1.1. |
   345 |  Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
   346 |  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
   347 |  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |
   348 
   349 __Related Topics:__ %TWIKIWEB%.TWikiPreferences
   350 
   351 %META:FILEATTACHMENT{name="behaviour.js" attr="" autoattached="1" comment="" date="1162075796" path="behaviour.compressed.js" size="2902" user="UnknownUser" version=""}%
   352 
   353 @
   354 
   355 
   356 1.3
   357 log
   358 @buildrelease
   359 @
   360 text
   361 @d1 1
   362 a1 1
   363 %META:TOPICINFO{author="TWikiContributor" date="1183913691" format="1.1" reprev="1." version="3"}%
   364 d299 1
   365 a299 1
   366 |  Version: | 15675 (04 Aug 2008) |
   367 @
   368 
   369 
   370 1.2
   371 log
   372 @buildrelease
   373 @
   374 text
   375 @d1 1
   376 a1 1
   377 %META:TOPICINFO{author="TWikiContributor" date="1183913691" format="1.1" reprev="1." version="2"}%
   378 d299 1
   379 a299 1
   380 |  Version: | 15675 (22 Jan 2008) |
   381 @
   382 
   383 
   384 1.1
   385 log
   386 @buildrelease
   387 @
   388 text
   389 @d1 1
   390 a1 1
   391 %META:TOPICINFO{author="TWikiContributor" date="1162394433" format="1.1" version="1"}%
   392 d6 1
   393 a6 1
   394 Behaviour is suited to create javascript based interaction that degrades well when javascript is not available.
   395 d8 1
   396 a8 1
   397 Javascript file: [[%PUBURL%/%TWIKIWEB%/%TOPIC%/behaviour.js][behaviour.js]] (8.1K). The [[%PUBURL%/%TWIKIWEB%/%TOPIC%/behaviour.compressed.js][compressed javascript file]] (2.9K) has been processed by [[http://alex.dojotoolkit.org/shrinksafe/][ShrinkSafe]].
   398 a9 1
   399 %TOC{title="On this page:"}%
   400 d58 2
   401 d65 1
   402 a65 1
   403 <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.compressed.js"></script>
   404 d111 2
   405 a112 1
   406 ---++ Example
   407 d117 3
   408 a119 1
   409 <span class="link%TWIKIWEB%%HOMETOPIC%">[[%TWIKIWEB%.%HOMETOPIC%][TWiki Web Home]]</span>
   410 d124 42
   411 a165 4
   412 	'.link%TWIKIWEB%%HOMETOPIC% a' : function(el){
   413 		el.onclick = function() {
   414 			// open in a popup with no other attributes than template 'viewplain'
   415 			launchTheWindow(this.href,null,null,null,"viewplain");
   416 a169 1
   417 
   418 a174 3
   419 The class name =link%<nop>TWIKIWEB%%<nop>HOMETOPIC%= will get expanded to =link%TWIKIWEB%%HOMETOPIC%=
   420 </blockquote>
   421 
   422 d177 3
   423 a179 1
   424 <span class="link%TWIKIWEB%%HOMETOPIC%">[[%TWIKIWEB%.%HOMETOPIC%][TWiki Web Home]]</span>
   425 d184 42
   426 a225 4
   427 	'.link%TWIKIWEB%%HOMETOPIC% a' : function(el){
   428 		el.onclick = function() {
   429 			// open in a popup with no other attributes than template 'viewplain'
   430 			launchTheWindow(this.href,null,null,null,"viewplain");
   431 a229 1
   432 
   433 d234 19
   434 d255 3
   435 a257 1
   436    * [[http://dean.edwards.name/weblog/2006/03/faster/][Dean Edwards: Faster DOM Queries]] - with a speed-up hack to Behaviour
   437 d261 3
   438 a263 1
   439 For details, see the Behaviour website.
   440 d268 27
   441 a294 1
   442    
   443 d296 11
   444 a306 6
   445 
   446 | Author: | TWiki:Main.ArthurClemens |
   447 | Copyright: | version 1.1 - Copyright (c) Ben Nolan and Simon Willison |
   448 | License: | BSD |
   449 | Dependencies: | None |
   450 | 4 June 2006| 1.000 First Version. Included Behaviour version: 1.1 |
   451 d313 2
   452 a314 2
   453 %META:FILEATTACHMENT{name="behaviour.compressed.js" attr="" autoattached="1" comment="" date="1162075796" path="behaviour.compressed.js" size="2902" user="UnknownUser" version=""}%
   454 %META:FILEATTACHMENT{name="behaviour.js" attr="" autoattached="1" comment="" date="1161199153" path="behaviour.js" size="8149" user="UnknownUser" version=""}%
   455 @