javascript.rb in nitro-0.26.0

- old
+ new

@@ -1,5 +1,9 @@
+require 'nano/inflect'
+
+require 'nitro/compiler/morphing'
+
 module Nitro
 
 # A collection of useful Javascript helpers. This modules
 # integrates helpers for the following javascript libraries:
 #
@@ -9,12 +13,20 @@
 # * dragdrop.js
 # * controls.js
 
 module JavascriptHelper
 
-private
+  # Insert an anchor to execute a given function when the link is followed.
+  # Call with the name of the link, and the function to be called:
+  #  link_to_function "Do it." :go
 
+  def link_to_function(name, function)
+    %{<a href="#" onclick="#{function}; return false;">#{name}</a>}
+  end
+
+  # -- older stuff --
+
   unless const_defined? :DEFAULT_JAVASCRIPT_FILES
     DEFAULT_JAVASCRIPT_FILES = [
       'js/behaviour.js', 
       'js/prototype.js', 
       'js/effects.js', 
@@ -22,19 +34,53 @@
       'js/controls.js'
     ]
   end
 
   # :section: behaviour.js
+  #
+  # Behaviour.js is a third-party library for keeping HTML clean of javascript.
+  # The +behaviour+ method provides an interface to that library.
+  # To learn more about the concept, visit the distributor:
+  # http://bennolan.com/behaviour/
   
+  # Register javascript code with an HTML element of a given id with the
+  # +behaviour+ method.
+  #
+  # Example: 
+  #
+  #  behaviour '#alert', %{
+  #    el.onclick = function() {
+  #      alert('Hello world');
+  #    }    
+  #  }  
+
   def behaviour(id, js)
     @_behaviours ||= []
     @_behaviours << [id, js]
     return nil
   end
   
   # :section: prototype.js
+  #
+  # Prototype.js is a third-party library that provides a number of functions
+  # for AJAX-style interaction with the browser. It depends on the Behaviour.js
+  # library. Prototype's homepage is http://prototype.conio.net/
 
+  # A live, or asynchronous, request is one that does not bring the user to a
+  # new page. It is used to send data back to the web server while the user is
+  # still interacting with a document.
+  #
+  # Call +live+ with the id of an achor element as a string or a symbol.
+  # Alternatively, add <tt>async="true"</tt> to the anchor (A) element. Specify the
+  # anchor to be called either as a second parameter to the +live+ method, or
+  # in the HREF option of the anchor element.
+  #
+  # Examples:
+  #
+  #  live :id_of_anchor_element [:method]
+  #  <a href="receiver" async="true">Go!</a>
+
   def live_request(id, options = {})
     __append_script_file__ 'js/behaviour.js'
     __append_script_file__ 'js/prototype.js'
     
     if href = options.delete(:href)
@@ -55,11 +101,12 @@
     return nil
   end
   alias_method :live, :live_request
   alias_method :async, :live_request
   
-  # Denotes an element as toggleable.
+  # Clicking the element will make it disappear. If you want it to reappear,
+  # you'll have to call <tt>toggle()</tt>.
   
   def toggleable(id, options = {})
     __append_script_file__ 'js/prototype.js'
     
     behaviour "##{id}", %{
@@ -72,11 +119,11 @@
     return nil
   end
   
   # :section: script.aculo.us dragdrop.js
   
-  # Make the element dragable.
+  # The user may click and drag the element about the screen.
   
   def draggable(id, options = {})
     __append_script_file__ 'js/behaviour.js'
     __append_script_file__ 'js/prototype.js'
     __append_script_file__ 'js/effects.js'
@@ -213,11 +260,12 @@
   end
   
   # -----------------------------------------------------------
   # :section: general javascript helpers.
   
-  # Include external javascript file.
+  # Inserts links to the .js files necessary for your page. Call it from within
+  # HEAD. Add other script files as arguments if desired.
   
   def include_script(*files)
     return if @_script_files.nil? and files.empty?
     
     code = ''
@@ -251,17 +299,19 @@
     return unless @_css
     %{<style>#{@_css.join("\n")}</style>}
   end
   alias_method :helper_css, :emit_css
 
-  # Emits the aggregated helper javascript.
+  # Call this in your template/page to include the javascript statements that
+  # link your HTML to the javascript libraries. Must be called after the HTML
+  # elements involved, i.e., at the bottom of the page.
   #--
   # FIXME: refactor this!
   #++
   
   def emit_script
-    code = %|<script type="text/javascript">\n|
+    code = %|<script type="text/javascript">\n<!--\n|
     unless @_behaviours.empty?
       code << %|var _behaviours = {\n|
       compo = []
       for id, js in @_behaviours
         compo << %|'#{id}': function(el) { #{js} \n }|
@@ -274,10 +324,11 @@
     end
     code << %|
         #{@_script.join("\n")}
     | if @_script
     code << %|
+      //-->
       </script>
     |
   end
   alias_method :helper_script, :emit_script
 
@@ -304,9 +355,38 @@
     @_css ||= []
     @_css << css unless @_css.include?(css)
   end
 
 end
+
+# :section: Javascript related morphers.
+
+# Transform a normal achor into an asynchronous request:
+#  <a href="..." async="true">...</a>
+# becomes
+#  <a href="#" onclick="new Ajax.Request...; return false;">...</a>
+
+class AsyncMorpher < Morpher
+  def before_start(buffer)
+    href = @attributes['href'] 
+    @attributes['href'] = '#'
+    @attributes['onclick'] = "new Ajax.Request('#{href}'); return false;"
+    @attributes.delete(@key)
+  end
+end
+
+class LocalMorpher < Morpher
+  def before_start(buffer)
+    @attributes['href'] = '#'
+    @attributes['onclick'] = "ngs#{@value.camelcase(true)}();"
+    @attributes.delete(@key)
+  end
+end
+
+# Install the morphers.
+
+Morphing.add_morpher :async, AsyncMorpher
+Morphing.add_morpher :local, LocalMorpher
 
 end
 
 # * George Moschovitis <gm@navel.gr>