[Checkins] SVN: z3c.formjs/trunk/src/z3c/formjs/ very initial work on client side event framework.

[Paul Carduner]

Log message for revision 78910:
  very initial work on client side event framework.

Changed:
  A   z3c.formjs/trunk/src/z3c/formjs/jsclientevent.py
  A   z3c.formjs/trunk/src/z3c/formjs/jsclientevent.txt
  U   z3c.formjs/trunk/src/z3c/formjs/jsfunction.txt
  U   z3c.formjs/trunk/src/z3c/formjs/tests/test_doc.py

-=-
Added: z3c.formjs/trunk/src/z3c/formjs/jsclientevent.py
===================================================================
--- z3c.formjs/trunk/src/z3c/formjs/jsclientevent.py	                        (rev 0)
+++ z3c.formjs/trunk/src/z3c/formjs/jsclientevent.py	2007-08-17 16:53:31 UTC (rev 78910)
@@ -0,0 +1,28 @@
+##############################################################################
+#
+# Copyright (c) 2007 Zope Foundation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Javascript Functions.
+
+$Id: jsfunction.py 78862 2007-08-16 00:16:19Z srichter $
+"""
+__docformat__ = "reStructuredText"
+import sys
+import zope.component
+import zope.interface
+
+from z3c.formjs import interfaces, jsfunction
+
+def listener(eventType):
+    """A decorator for defining a javascript function that is a listener."""
+    namespace = "%s_%s" % (eventType.__module__.replace(".","_"), eventType.__name__)
+    return jsfunction.function(namespace)

Added: z3c.formjs/trunk/src/z3c/formjs/jsclientevent.txt
===================================================================
--- z3c.formjs/trunk/src/z3c/formjs/jsclientevent.txt	                        (rev 0)
+++ z3c.formjs/trunk/src/z3c/formjs/jsclientevent.txt	2007-08-17 16:53:31 UTC (rev 78910)
@@ -0,0 +1,63 @@
+========================================
+Mapping Events Between Server and Client
+========================================
+
+The ``jsclientevent`` module of this package provides an extremely
+minimal event framework whereby events that occur on the server, such
+as ``IObjectModifiedEvent``s, propagate to a clients browser through
+injected JavaScript function calls.  This is not to be confused with
+"action events" that occur on the client such as onClick.
+
+  >>> from z3c.formjs import jsclientevent
+
+There are several components these types of interactions.  First there
+are the server events, which, for example, are thrown on a state
+change.  Next there is a client listener, which is just a javascript
+function that gets called when the event occurs, and finally there is
+the "event transport" which allows the server to call a function
+defined on the client side.
+
+
+Client Side Listener
+--------------------
+
+The client side event listener is just a JavaScript function that gets
+called when the event occurs.  In order for the server to know which
+JavaScript functions to call, we must define the JavaScript function
+itself on the server, in python, so it can be referenced by the
+server.  This works a lot like the jsfunction module with slight
+modifications.
+
+Let's create a simple view class with an event listener for the
+IObjectModifiedEvent
+
+  >>> from zope.lifecycleevent.interfaces import IObjectModifiedEvent
+  >>> class View(object):
+  ...
+  ...     @jsclientevent.listener(IObjectModifiedEvent)
+  ...     def modifiedListener(self, data):
+  ...         return 'alert("object modified: " + data);'
+
+The argument passed to the ``listener`` decorator is the interface for
+the event that this function will be listening for.  This is the only
+thing that makes this decorator different from the jsfunction.function
+decorator.  Specifically, the jsclientevent.listener decorator sets
+the namespace of the function based on the type of event passed to it.
+
+All these event listeners are collected in the ``jsFunctions``
+attribute because that is after all what they are.
+
+  >>> View.jsFunctions
+  <JSFunctions
+     {'zope_lifecycleevent_interfaces_IObjectModifiedEvent': [<JSFunction modifiedListener>]}>
+
+  >>> print View.jsFunctions.render()
+  var zope_lifecycleevent_interfaces_IObjectModifiedEvent = {
+    modifiedListener: function(data) {
+      alert("object modified: " + data);
+    }
+  }
+
+
+Server Side Listeners
+---------------------
\ No newline at end of file

Modified: z3c.formjs/trunk/src/z3c/formjs/jsfunction.txt
===================================================================
--- z3c.formjs/trunk/src/z3c/formjs/jsfunction.txt	2007-08-17 16:45:46 UTC (rev 78909)
+++ z3c.formjs/trunk/src/z3c/formjs/jsfunction.txt	2007-08-17 16:53:31 UTC (rev 78910)
@@ -36,8 +36,9 @@
     }
   }
 
-Similarly to Javascript subscriptions, a JavaScript viewlet exists for any
-view containing JavaScript functions that provides the following output:
+Similarly to Javascript subscriptions, a JavaScript viewlet exists for
+any view containing JavaScript functions that provides the following
+output:
 
   >>> viewlet = jsfunction.JSFunctionsViewlet(
   ...     object(), object(), View(), object())
@@ -51,9 +52,9 @@
     }
   </script>
 
-Let's now have a closer look that the decorator. As mentioned before, the
-namespace is option. So what happens if the namespace is not specified? Then
-the function should be declared normally:
+Let's now have a closer look at the decorator. As mentioned before,
+the namespace is optional. So what happens if the namespace is not
+specified? Then the function should be declared normally:
 
   >>> class View(object):
   ...

Modified: z3c.formjs/trunk/src/z3c/formjs/tests/test_doc.py
===================================================================
--- z3c.formjs/trunk/src/z3c/formjs/tests/test_doc.py	2007-08-17 16:45:46 UTC (rev 78909)
+++ z3c.formjs/trunk/src/z3c/formjs/tests/test_doc.py	2007-08-17 16:53:31 UTC (rev 78910)
@@ -44,6 +44,11 @@
             optionflags=zope.testing.doctest.NORMALIZE_WHITESPACE |
                         zope.testing.doctest.ELLIPSIS),
         zope.testing.doctest.DocFileSuite(
+            '../jsclientevent.txt',
+            setUp=testing.setUp, tearDown=testing.tearDown,
+            optionflags=zope.testing.doctest.NORMALIZE_WHITESPACE |
+                        zope.testing.doctest.ELLIPSIS),
+        zope.testing.doctest.DocFileSuite(
             '../jqueryrenderer.txt',
             setUp=testing.setUp, tearDown=testing.tearDown,
             optionflags=zope.testing.doctest.NORMALIZE_WHITESPACE |