[pypy-svn] r31686 - pypy/dist/pypy/doc/js
micktwomey at codespeak.net
micktwomey at codespeak.net
Sat Aug 26 17:28:37 CEST 2006
Author: micktwomey
Date: Sat Aug 26 17:28:34 2006
New Revision: 31686
Modified:
pypy/dist/pypy/doc/js/using.txt
Log:
Updated the javascript docs with more examples and tweaked the language a bit here and there.
Modified: pypy/dist/pypy/doc/js/using.txt
==============================================================================
--- pypy/dist/pypy/doc/js/using.txt (original)
+++ pypy/dist/pypy/doc/js/using.txt Sat Aug 26 17:28:34 2006
@@ -10,14 +10,15 @@
Purpose:
========
-This tutorial explains hot to use a `PyPy`_'s JavaScript backend,
-altough a reader should have some previous knowledge of writing
-an `RPython`_ programs.
-
-A JavaScript backend is intended for writing `RPython`_ source code
-which get translated into JavaScript and executed on a browser. Resulting
-JavaScript code should not depend on a browser (this is backend responsibility)
-and should integrate as much as possible with a web server.
+This tutorial explains how to use `PyPy`_'s JavaScript backend. The
+reader should have some previous knowledge of writing `RPython`_
+programs.
+
+The JavaScript backend lets you write `RPython`_ source code which gets
+translated into JavaScript and executed in a browser. The resulting
+JavaScript code should not depend on a browser (this is backend
+responsibility) and should integrate as much as possible with a web
+server.
.. _`PyPy`: http://codespeak.net/pypy
.. _`RPython`: http://codespeak.net/pypy/dist/pypy/doc/coding-guide.html#restricted-python
@@ -25,61 +26,151 @@
Getting started:
----------------
-You can use a JavaScript backend in many different ways. One of those is to
-simply run `jscompile`_ from bin directory with module name and functions to
-get your functions compiled. Other way is to use compile_function from `runtest`_ and to get your javascript generated on-the-fly (When serving a web page)
+You can use a JavaScript backend in many different ways. One of those is
+to simply run `jscompile`_ from bin directory with module name and a
+list of functions to get your functions compiled. Another way is to use
+rpython2javascript from `js.main`_ which allows your javascript to be
+generated on-the-fly (e.g. when serving a web page).
.. _`jscompile`: http://codespeak.net/svn/pypy/dist/pypy/bin/jscompile.py
-.. _`runtest`: http://codespeak.net/svn/pypy/dist/pypy/translator/js/test/runtest.py
+.. _`js.main`: http://codespeak.net/svn/pypy/dist/pypy/translator/js/main.py
+
+Here is a simple example using `MochiKit`_'s logDebug call to show a
+message::
+
+ from pypy.translator.js.modules import mochikit
+
+ def simple_example():
+ mochikit.createLoggingPane(True)
+ mochikit.logDebug("Hello")
+
+Save this to a python file, e.g. simpledemo.py. Then use jscompile to
+create a javascript version::
+
+ $ python pypy/bin/jscompile.py simpledemo simple_example
+
+Note that you specify the module as a python module which must be on the
+python path.
+
+When you run this you should see some information on the compilation
+process scrolling past. The JavaScript is written to a file which looks
+something like
+`/tmp/usession-1/some_strange_function_which_will_never_be_called.js`.
+
+You can call the compilation process programatically using
+rpython2javascript::
+
+ from pypy.translator.js.main import rpython2javascript
+
+ import simpledemo
+
+ js_src = rpython2javascript(simpledemo, ["simple_example"])
+ print js_src
+
+.. _`MochiKit`: http://www.mochikit.com/
+.. _`rpython2javascript`:
Web server integration:
-----------------------
There is an `example`_ of using this toolkit with BaseHTTPServer from
-standart python library. Web server integration is simple - you can compile
-any RPython function at runtime and provide it to client as JavaScript file.
+the standard python library. Web server integration is simple - you can
+compile any RPython function at runtime and provide it to client as
+a JavaScript file.
.. _`example`: http://codespeak.net/svn/pypy/dist/pypy/translator/js/demo/jsdemo/example.py
Easy AJAX:
----------
-Idea is simple: Normal python method calls get rendered as communication over
-XmlHTTPRequest without too much user intervention. To acheieve it, you must
-provide some informations that *these* method calls needs to be rendered like
-that. First you must subclass BasicExternal from `bltregistry`_ to any class
-and provide instance of it to RPython code (as global variable or any other
-way). Then you need to set class instance _render_xmlhttp of it, to tell
-JS backend to render it as xmlhttp communication. Because web server code
-does not need to be rpython, you have to supply some way of telling
-what types can be returned out of it. This is done by decorator
- at described(retval = <example of used type>), for example you may provide::
+The idea is simple: Normal python method calls get rendered as
+communication over `XMLHttpRequest`_ without too much user intervention.
+To achieve this, you must tell PyPy that *these* particular method calls
+need to be rendered in this way.
+
+First you must subclass BasicExternal from `bltregistry`_ and provide
+instance of it to RPython code (as global variable or any other way).
+Then you need to set class instance's `_render_xmlhttp` to `True`, to
+tell the JS backend to render it using xmlhttp communication. Because
+the web server code does not need to be rpython, you have to supply some
+way of telling PyPy what types can be returned out of it. This is done
+using the decorator `@described(retval = <example of used type>)` from
+`bltregistry`_. For example you may provide::
@described(retval = {'a':'a'})
def some_fun(self, some_arg = 3):
....
-to tell compiler that this function will return mapping from string to string
-and will take integer as an argument (note that 'a' and 3 are not special
-values, just examples of the type).
-
-On the other hand you must supply a method for returning JSON tables by
-server itself (this is done automatically in for example TurboGears or others).
+to tell compiler that this function will return mapping from string to
+string and will take integer as an argument (note that 'a' and 3 are not
+special values, just examples of the type). You can simply specify the
+arguments using keyword arguments with an example, or pass an args
+dictionary to the described decorator.
+
+Then you must supply a method which returns JSON data in the server
+itself (for example, this is done automatically by `TurboGears`_ using
+the `@expose(format='json')` decorator).
+.. _`XMLHttpRequest`: http://en.wikipedia.org/wiki/XMLHttpRequest
+.. _`TurboGears`: http://www.turbogears.org/
.. _`bltregistry`: http://codespeak.net/svn/pypy/dist/pypy/rpython/ootypesystem/bltregistry.py
-Integration with turbogears or any other web framework:
+Ajax Ping Example:
+------------------
+
+To create a simple javascript method which pings a server you need two parts, a server side python class which knows how to talk via XMLHttpRequest to a client side call.
+
+On the server side::
+
+ from pypy.rpython.ootypesystem.bltregistry import BasicExternal, described
+
+ class PingHandler(BasicExternal):
+ _render_xmlhttp = True
+
+ @described(retval={"aa":"aa"})
+ def ping(self, ping_str="aa"):
+ return dict(response="PONG: %s" % ping_str)
+
+ ping_handler = PingHandler()
+
+This uses the BasicExternal class and the described decorator to let PyPy know how to deal with the input and output of the methods. You then need an instance of the class to pass to other parts of the RPython code.
+
+On the client you call the ping_handler.ping method with a callback::
+
+ from pypy.translator.js.modules import mochikit
+ from somewhere import ping_handler
+
+ def callback(response):
+ mochikit.logDebug("Got response: " + response["response"])
+
+ def ping():
+ ping_handler.ping("PING", callback)
+
+You compile this to JavaScript using jscompile or rpython2javascript and
+the ping method. The resulting javascript is passed to a web browser,
+while there needs to be a server which knows how to deal with a HTTP
+request to `/ping` (the name is derived from the name of the method
+decorated with described). The server then calls the `ping_handler.ping`
+method with the data from the call and returns a JSON dictionary.
+
+Integration with TurboGears or any other web framework:
-------------------------------------------------------
-There is nothing special in this case. JS backend can work with virtually
-any web framework. In some examples there is use of turbogears, but just
-for simplifying JSON tables and so on.
+There is nothing special in this case. The JS backend can work with
+virtually any web framework. In some of the examples TurboGears is used,
+but just for simplifying generation of the JSON data. You can use
+`simplejson`_ to generate a JSON response from any framework. The `django ping example`_ shows how to do this in `Django`_.
+
+.. _`simplejson`: http://cheeseshop.python.org/pypi/simplejson
+.. _`Django`: http://www.djangoproject.com/
Further examples:
-----------------
-There is bub'n'bros client working in javascript aviable `here`_ (No working copy on-line right
-now, sorry) and simple example of JS `console`_.
+There is bub'n'bros client working in javascript available `here`_ (No
+working copy on-line right now, sorry) and a simple example of JS a
+`console`_. There is also a simple `django ping example`_.
.. _`here`: http://codespeak.net/svn/pypy/dist/pypy/translator/js/tools/start_bnb.py
.. _`console`: http://codespeak.net/svn/pypy/dist/pypy/translator/js/tools/console.py
+.. _`django ping example`: http://codespeak.net/svn/pypy/dist/pypy/translator/js/demo/jsdemo/djangoping
More information about the Pypy-commit
mailing list