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