Viewing file: livepage.py (29.12 KB) -rw-r--r-- Select action/file-type: (+) | (+) | (+) | Code (+) | Session (+) | (+) | SDB (+) | (+) | (+) | (+) | (+) | (+) |
# -*- test-case-name: nevow.test.test_livepage -*- # Copyright (c) 2004 Divmod. # See LICENSE for details.
""" Previous generation Nevow Comet support. Do not use this module.
@see: L{nevow.athena} """
import itertools, types import warnings
from zope.interface import implements, Interface
from twisted.internet import defer, error from twisted.internet.task import LoopingCall from twisted.python import log
from nevow import tags, inevow, context, static, flat, rend, url, util, stan
# If you need to debug livepage itself or your livepage app, set this to true DEBUG = False
_jslog = None
def _openjslog(): global _jslog if _jslog is None: _jslog = file("js.log", "w") _jslog.write("**********\n") _jslog.flush() return _jslog
def jslog(*x): if DEBUG: mylog = _openjslog() for y in x: mylog.write(str(y)) mylog.flush()
class JavascriptContext(context.WovenContext): def __init__(self, parent=None, tag=None, isAttrib=None, inJSSingleQuoteString=None, remembrances=None): super(JavascriptContext, self).__init__( parent, tag, inJS=True, isAttrib=isAttrib, inJSSingleQuoteString=inJSSingleQuoteString, remembrances=None)
class TimeoutException(Exception): pass
class ClientSideException(Exception): pass
class SingleQuote(object): def __init__(self, children): self.children = children
def __repr__(self): return "%s(%s)" % (type(self).__name__, self.children)
def flattenSingleQuote(singleQuote, ctx): new = JavascriptContext(ctx, tags.invisible[singleQuote], inJSSingleQuoteString=True) return flat.serialize(singleQuote.children, new) flat.registerFlattener(flattenSingleQuote, SingleQuote)
class _js(object): """ Stan for Javascript. There is a convenience instance of this class named "js" in the livepage module which you should use instead of the _js class directly.
Marker indicating literal Javascript should be rendered. No escaping will be performed.
When inside a JavascriptContext, Nevow will automatically put apostrophe quote marks around any Python strings it renders. This makes turning a Python string into a JavaScript string very easy. However, there are often situations where you wish to generate some literal Javascript code and do not wish quote marks to be placed around it. In this situation, the js object should be used.
The simplest usage is to simply pass a python string to js. When the js object is rendered, the python string will be rendered as if it were literal javascript. For example::
client.send(js(\"alert('hello')\"))
However, to make the generation of Javascript more convenient, the js object also provides safe implementations of __getattr__, __call__, and __getitem__. See the following examples to get an idea of how to use it. The Python code is to the left of the -> and the Javascript which results is to the right::
js(\"alert('any javascript you like')\") -> alert('any javascript you like')
js.window.title -> window.title
js.document.getElementById('foo') -> document.getElementById('foo')
js.myFunction('my argument') -> myFunction('my argument')
js.myFunction(True, 5, \"it's a beautiful day\") -> myFunction(true, 5, 'it\\'s a beautiful day')
js.document.all[\"something\"] -> document.all['something']
js[1, 2] -> [1, 2]
XXX TODO support javascript object literals somehow? (They look like dicts) perhaps like this::
js[\"one\": 1, \"two\": 2] -> {\"one\": 1, \"two\": 2}
The livepage module includes many convenient instances of the js object. It includes the literals::
document window this self
It includes shorthand for commonly called javascript functions::
alert -> alert get -> document.getElementById set -> nevow_setNode append -> nevow_appendNode prepend -> nevow.prependNode insert -> nevow.insertNode
It includes convenience calls against the client-side server object::
server.handle('callMe') -> server.handle('callMe')
It includes commonly-used fragments of javascript::
stop -> ; return false; eol -> \\n
Stop is used to prevent the browser from executing it's default event handler. For example::
button(onclick=[server.handle('click'), stop]) -> <button onclick=\"server.handle('click'); return false;\" />
EOL is currently required to separate statements (this requirement may go away in the future). For example::
client.send([ alert('hello'), eol, alert('goodbye')])
XXX TODO: investigate whether rendering a \\n between list elements in a JavascriptContext has any ill effects. """
def __init__(self, name=None): if name is None: name = [] if isinstance(name, str): name = [stan.raw(name)] self._children = name
def __getattr__(self, name): if name == 'clone': raise RuntimeError("Can't clone") if self._children: newchildren = self._children[:] newchildren.append(stan.raw('.'+name)) return self.__class__(newchildren) return self.__class__(name)
def __call__(self, *args): if not self._children: return self.__class__(args[0]) newchildren = self._children[:] stuff = [] for x in args: if isinstance(x, ( basestring, stan.Tag, types.FunctionType, types.MethodType, types.UnboundMethodType)): x = stan.raw("'"), SingleQuote(x), stan.raw("'") stuff.append((x, stan.raw(','))) if stuff: stuff[-1] = stuff[-1][0] newchildren.extend([stan.raw('('), stuff, stan.raw(')')]) return self.__class__(newchildren)
def __getitem__(self, args): if not isinstance(args, (tuple, list)): args = (args,) newchildren = self._children[:] stuff = [(x, stan.raw(',')) for x in args] if stuff: stuff[-1] = stuff[-1][0] newchildren.extend([stan.raw("["), stuff, stan.raw("]")]) return self.__class__(newchildren)
def __iter__(self): """Prevent an infinite loop if someone tries to do for x in jsinstance: """ raise NotImplementedError, "js instances are not iterable. (%r)" % (self, )
def __repr__(self): return "%s(%r)" % (type(self).__name__, self._children) def flattenJS(theJS, ctx): new = JavascriptContext(ctx, tags.invisible[theJS]) return flat.serialize(theJS._children, new) flat.registerFlattener(flattenJS, _js)
js = _js() document = _js('document') get = document.getElementById window = _js('window') this = _js('this') self = _js('self') server = _js('server') alert = _js('alert') stop = _js('; return false;') eol = tags.raw('\n')
set = js.nevow_setNode append = js.nevow_appendNode prepend = js.nevow_prependNode insert = js.nevow_insertNode
def assign(where, what): """Assign what to where. Equivalent to where = what; """ return _js([where, stan.raw(" = "), what])
setq = assign # hee
def var(where, what): """Define local variable 'where' and assign 'what' to it. Equivalent to var where = what; """ return _js([stan.raw("var "), where, stan.raw(" = "), what, stan.raw(";")])
def anonymous(block): """ Turn block (any stan) into an anonymous JavaScript function which takes no arguments. Equivalent to::
function () { block } """ return _js([stan.raw("function() {\n"), block, stan.raw("\n}")])
class IClientHandle(Interface): def hookupOutput(output, finisher=None): """hook up an output conduit to this live evil instance. """
def send(script): """send a script through the output conduit to the browser. If no output conduit is yet hooked up, buffer the script until one is. """
def handleInput(identifier, *args): """route some input from the browser to the appropriate destination. """
class IHandlerFactory(Interface): def locateHandler(ctx, name): """Locate a handler callable with the given name. """
class _transient(object): def __init__(self, transientId, arguments=None): self.transientId = transientId if arguments is None: arguments = [] elif isinstance(arguments, tuple): arguments = list(arguments) else: raise TypeError, "Arguments must be None or tuple" self.arguments = arguments
def __call__(self, *arguments): return type(self)(self.transientId, arguments)
def flattenTransient(transient, ctx): thing = js.server.handle("--transient.%s" % (transient.transientId, ), *transient.arguments) return flat.serialize(thing, ctx) flat.registerFlattener(flattenTransient, _transient)
class ClientHandle(object): """An object which represents the client-side webbrowser. """ implements(IClientHandle)
outputConduit = None
def __init__(self, livePage, handleId, refreshInterval, targetTimeoutCount): self.refreshInterval = refreshInterval self.targetTimeoutCount = targetTimeoutCount self.timeoutCount = 0 self.livePage = livePage self.handleId = handleId self.outputBuffer = [] self.bufferDeferreds = [] self.closed = False self.closeNotifications = [] self.firstTime = True self.timeoutLoop = LoopingCall(self.checkTimeout) if refreshInterval: self.timeoutLoop.start(self.refreshInterval) self._transients = {} self.transientCounter = itertools.count().next self.nextId = itertools.count().next ## For backwards compatibility with handler
def transient(self, what, *args): """Register a transient event handler, 'what'. The callable 'what' can only be invoked by the client once before being garbage collected. Additional attempts to invoke the handler will fail. """ transientId = str(self.transientCounter()) self._transients[transientId] = what return _transient(transientId, args)
def popTransient(self, transientId): """Remove a transient previously registered by a call to transient. Normally, this will be done automatically when the transient is invoked. However, you can invoke it yourself if you wish to revoke the client's capability to call the transient handler. """ if DEBUG: print "TRANSIENTS", self._transients return self._transients.pop(transientId)
def _actuallySend(self, scripts): output = self.outputConduit written = [] def writer(write): #print "WRITER", write written.append(write) def finisher(finish): towrite = '\n'.join(written) jslog("<<<<<<\n%s\n" % towrite) output.callback(towrite) flat.flattenFactory(scripts, self.outputContext, writer, finisher) self.outputConduit = None self.outputContext = None
def send(self, *script): """Send the stan "script", which can be flattened to javascript, to the browser which is connected to this handle, and evaluate it in the context of the browser window. """ if self.outputConduit: self._actuallySend(script) else: self.outputBuffer.append(script) self.outputBuffer.append(eol)
def setOutput(self, ctx, output): self.timeoutCount = 0 self.outputContext = ctx self.outputConduit = output if self.outputBuffer: if DEBUG: print "SENDING BUFFERED", self.outputBuffer self._actuallySend(self.outputBuffer) self.outputBuffer = []
def _actuallyPassed(self, result, deferreds): for d in deferreds: d.callback(result)
def _actuallyFailed(self, failure, deferreds): for d in deferreds: d.errback(failure)
def checkTimeout(self): if self.outputConduit is not None: ## The browser is waiting for us, send a noop. self.send(_js('null;')) return self.timeoutCount += 1 if self.timeoutCount >= self.targetTimeoutCount: ## This connection timed out. self._closeComplete( TimeoutException( "This connection did not ACK in at least %s seconds." % ( self.targetTimeoutCount * self.refreshInterval, )))
def outputGone(self, failure, output): # assert output == self.outputConduit # Twisted errbacks with a ConnectionDone when the client closes the # connection cleanly. Pretend it didn't happen and carry on. self.outputConduit = None if failure.check(error.ConnectionDone): self._closeComplete() else: self._closeComplete(failure) return None
def _closeComplete(self, failure=None): if self.closed: return self.closed = True self.timeoutLoop.stop() self.timeoutLoop = None for notify in self.closeNotifications[:]: if failure is not None: notify.errback(failure) else: notify.callback(None) self.closeNotifications = []
def notifyOnClose(self): """This will return a Deferred that will be fired when the connection is closed 'normally', i.e. in response to handle.close() . If the connection is lost in any other way (because the browser navigated to another page, the browser was shut down, the network connection was lost, or the timeout was reached), this will errback instead.""" d = defer.Deferred() self.closeNotifications.append(d) return d
def close(self, executeScriptBeforeClose=""): if DEBUG: print "CLOSE WAS CALLED" d = self.notifyOnClose() self.send(js.nevow_closeLive(executeScriptBeforeClose)) return d
def set(self, where, what): self.send(js.nevow_setNode(where, what))
def prepend(self, where, what): self.send(js.nevow_prependNode(where, what))
def append(self, where, what): self.send(js.nevow_appendNode(where, what))
def alert(self, what): self.send(js.alert(what))
def call(self, what, *args): self.send(js(what)(*args))
def sendScript(self, string): warnings.warn( "[0.5] nevow.livepage.ClientHandle.sendScript is deprecated, use send instead.", DeprecationWarning, 2) self.send(string)
class DefaultClientHandleFactory(object): clientHandleClass = ClientHandle
def __init__(self): self.clientHandles = {} self.handleCounter = itertools.count().next
def newClientHandle(self, livePage, refreshInterval, targetTimeoutCount): handleid = str(self.handleCounter()) handle = self.clientHandleClass( livePage, handleid, refreshInterval, targetTimeoutCount) self.clientHandles[handleid] = handle handle.notifyOnClose().addBoth(lambda ign: self.deleteHandle(handleid)) return handle
def deleteHandle(self, handleid): del self.clientHandles[handleid]
def getHandleForId(self, handleId): """Override this to restore old handles on demand. """ return self.clientHandles[handleId]
theDefaultClientHandleFactory = DefaultClientHandleFactory()
class OutputHandlerResource: implements(inevow.IResource)
def __init__(self, clientHandle): self.clientHandle = clientHandle
def locateChild(self, ctx, segments): raise NotImplementedError()
def renderHTTP(self, ctx): request = inevow.IRequest(ctx) neverEverCache(request) activeChannel(request) ctx.remember(jsExceptionHandler, inevow.ICanHandleException) request.channel._savedTimeOut = None # XXX TODO d = defer.Deferred() request.notifyFinish().addErrback(self.clientHandle.outputGone, d) jsContext = JavascriptContext(ctx, tags.invisible()) self.clientHandle.livePage.rememberStuff(jsContext) jsContext.remember(self.clientHandle, IClientHandle) if self.clientHandle.firstTime: self.clientHandle.livePage.goingLive(jsContext, self.clientHandle) self.clientHandle.firstTime = False self.clientHandle.setOutput(jsContext, d) return d
class InputHandlerResource: implements(inevow.IResource)
def __init__(self, clientHandle): self.clientHandle = clientHandle
def locateChild(self, ctx, segments): raise NotImplementedError()
def renderHTTP(self, ctx): self.clientHandle.timeoutCount = 0
request = inevow.IRequest(ctx) neverEverCache(request) activeChannel(request) ctx.remember(self.clientHandle, IClientHandle) ctx.remember(jsExceptionHandler, inevow.ICanHandleException) self.clientHandle.livePage.rememberStuff(ctx)
handlerName = request.args['handler-name'][0] arguments = request.args.get('arguments', ()) jslog(">>>>>>\n%s %s\n" % (handlerName, arguments)) if handlerName.startswith('--transient.'): handler = self.clientHandle.popTransient(handlerName.split('.')[-1]) else: handler = self.clientHandle.livePage.locateHandler( ctx, request.args['handler-path'], handlerName)
jsContext = JavascriptContext(ctx, tags.invisible[handler]) towrite = []
def writer(r): jslog("WRITE ", r) towrite.append(r)
def finisher(r): jslog("FINISHED", r) writestr = ''.join(towrite) jslog("<><><>\n%s\n" % (writestr, )) request.write(writestr) request.finish() return r
result = handler(jsContext, *arguments) jslog("RESULT ", result)
if result is None: return defer.succeed('') return self.clientHandle.livePage.flattenFactory(result, jsContext, writer, finisher)
class DefaultClientHandlesResource(object): implements(inevow.IResource)
clientResources = { 'input': InputHandlerResource, 'output': OutputHandlerResource, }
clientFactory = theDefaultClientHandleFactory
def locateChild(self, ctx, segments): handleId = segments[0] handlerType = segments[1] client = self.clientFactory.clientHandles[handleId]
return self.clientResources[handlerType](client), segments[2:]
theDefaultClientHandlesResource = DefaultClientHandlesResource()
class attempt(defer.Deferred): """ Attempt to do 'stuff' in the browser. callback on the server if 'stuff' executes without raising an exception. errback on the server if 'stuff' raises a JavaScript exception in the client.
Used like this::
def printIt(what): print "Woo!", what
C = IClientHandle(ctx) C.send( attempt(js("1+1")).addCallback(printIt))
C.send( attempt(js("thisWillFail")).addErrback(printIt)) """ def __init__(self, stuff): self.stuff = stuff defer.Deferred.__init__(self)
def flattenAttemptDeferred(d, ctx): def attemptComplete(ctx, result, reason=None): if result == 'success': d.callback(None) else: d.errback(ClientSideException(reason)) transient = IClientHandle(ctx).transient(attemptComplete) return flat.serialize([ _js("""try { """), d.stuff, _js(""" """), transient('success'), _js(""" } catch (e) { """), transient('failure', js.e), _js("}") ], ctx) flat.registerFlattener(flattenAttemptDeferred, attempt)
class IOutputEvent(Interface): pass
class IInputEvent(Interface): pass
class ExceptionHandler(object): def renderHTTP_exception(self, ctx, failure): log.msg("Exception during input event:") log.err(failure) request = inevow.IRequest(ctx) request.write("throw new Error('Server side error: %s')" % (failure.getErrorMessage().replace("'", "\\'").replace("\n", "\\\n"), )) request.finish()
def renderInlineException(self, ctx, reason): """TODO: I don't even think renderInlineException is ever called by anybody """ pass
jsExceptionHandler = ExceptionHandler()
def neverEverCache(request): """ Set headers to indicate that the response to this request should never, ever be cached. """ request.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate') request.setHeader('Pragma', 'no-cache')
def activeChannel(request): """Mark this connection as a 'live' channel by setting the Connection: close header and flushing all headers immediately. """ request.setHeader("Connection", "close") request.write('')
class LivePage(rend.Page): """ A Page which is Live provides asynchronous, bidirectional RPC between Python on the server and JavaScript in the client browser. A LivePage must include the "liveglue" JavaScript which includes a unique identifier which is assigned to every page render of a LivePage and the JavaScript required for the client to communicate asynchronously with the server.
A LivePage grants the client browser the capability of calling server-side Python methods using a small amount of JavaScript code. There are two types of Python handler methods, persistent handlers and transient handlers.
- To grant the client the capability to call a persistent handler over and over as many times as it wishes, subclass LivePage and provide handle_foo methods. The client can then call handle_foo by executing the following JavaScript::
server.handle('foo')
handle_foo will be invoked because the default implementation of locateHandler looks for a method prefixed handle_*. To change this, override locateHandler to do what you wish.
- To grant the client the capability of calling a handler once and exactly once, use ClientHandle.transient to register a callable and embed the return result in a page to render JavaScript which will invoke the transient handler when executed. For example::
def render_clickable(self, ctx, data): def hello(ctx): return livepage.alert(\"Hello, world. You can only click me once.\")
return ctx.tag(onclick=IClientHandle(ctx).transient(hello))
The return result of transient can also be called to pass additional arguments to the transient handler. For example::
def render_choice(self, ctx, data): def chosen(ctx, choseWhat): return livepage.set( \"choosable\", [\"Thanks for choosing \", choseWhat])
chooser = IClientHandle(ctx).transient(chosen)
return span(id=\"choosable\")[ \"Choose one:\", p(onclick=chooser(\"one\"))[\"One\"], p(onclick=chooser(\"two\"))[\"Two\"]]
Note that the above situation displays temporary UI to the user. When the user invokes the chosen handler, the UI which allowed the user to invoke the chosen handler is removed from the client. Thus, it is important that the transient registration is deleted once it is invoked, otherwise uncollectable garbage would accumulate in the handler dictionary. It is also important that either the one or the two button consume the same handler, since it is an either/or choice. If two handlers were registered, the untaken choice would be uncollectable garbage. """ refreshInterval = 30 targetTimeoutCount = 3
clientFactory = theDefaultClientHandleFactory
def renderHTTP(self, ctx): if not self.cacheable: neverEverCache(inevow.IRequest(ctx)) return rend.Page.renderHTTP(self, ctx)
def locateHandler(self, ctx, path, name): ### XXX TODO: Handle path return getattr(self, 'handle_%s' % (name, ))
def goingLive(self, ctx, handle): """This particular LivePage instance is 'going live' from the perspective of the ClientHandle 'handle'. Override this to get notified when a new browser window observes this page.
This means that a new user is now looking at the page, an old user has refreshed the page, or an old user has opened a new window or tab onto the page.
This is the first time the ClientHandle instance is available for general use by the server. This Page may wish to keep track of the ClientHandle instances depending on how your application is set up. """ pass
def child_livepage_client(self, ctx): return theDefaultClientHandlesResource
# child_nevow_glue.js = static.File # see below
def render_liveid(self, ctx, data): warnings.warn("You don't need a liveid renderer any more; just liveglue is fine.", DeprecationWarning) return ''
cacheable = False # Set this to true to use ***HIGHLY*** # EXPERIMENTAL lazy ID allocation feature, # which will allow your LivePage instances to # be cached by clients.
def render_liveglue(self, ctx, data): if not self.cacheable: handleId = "'", self.clientFactory.newClientHandle( self, self.refreshInterval, self.targetTimeoutCount).handleId, "'" else: handleId = 'null'
return [ tags.script(type="text/javascript")[ "var nevow_clientHandleId = ", handleId ,";"], tags.script(type="text/javascript", src=url.here.child('nevow_glue.js')) ]
setattr( LivePage, 'child_nevow_glue.js', static.File( util.resource_filename('nevow', 'liveglue.js'), 'text/javascript'))
glue = tags.directive('liveglue')
##### BACKWARDS COMPATIBILITY CODE
ctsTemplate = "nevow_clientToServerEvent('%s',this,''%s)%s" handledEventPostlude = '; return false;'
class handler(object): callme = None args = () identifier = None def __init__(self, *args, **kw): """**DEPRECATED** [0.5]
Handler is now deprecated. To expose server-side code to the client to be called by JavaScript, read the LivePage docstring. """ warnings.warn( "[0.5] livepage.handler is deprecated; Provide handle_foo methods (or override locateHandler) on your LivePage and use (in javascript) server.handle('foo'), or use ClientHandle.transient to register a one-shot handler capability.", DeprecationWarning, 2) ## Handle working like a 2.4 decorator where calling handler returns a decorator if not callable(args[0]) or isinstance(args[0], _js): self.args = args return self.callme = args[0] self(*args[1:], **kw)
def __call__(self, *args, **kw): if self.callme is None: self.callme = args[0] args = args[1:]
self.args += args self.outsideAttribute = kw.get('outsideAttribute') bubble = kw.get('bubble') if bubble: self.postlude = ';' else: self.postlude = handledEventPostlude
if 'identifier' in kw: self.identifier = kw['identifier']
return self
content = property(lambda self: flt(self))
def flattenHandler(handler, ctx): client = IClientHandle(ctx) iden = handler.identifier if iden is None: iden = client.nextId() iden = '--handler-%s' % (iden, ) ## TODO this should be the IHandlerFactory instead of IResource setattr(IHandlerFactory(ctx), 'handle_%s' % (iden, ), handler.callme) isAttrib = not handler.outsideAttribute new = JavascriptContext(ctx, tags.invisible[handler.args], isAttrib=isAttrib)
rv = flat.flatten( js.nevow_clientToServerEvent(*(iden, this, '') + handler.args), new) rv += handler.postlude return tags.xml(rv) flat.registerFlattener(flattenHandler, handler)
def flt(stan, quote=True, client=None, handlerFactory=None): """Flatten some stan to a string suitable for embedding in a javascript string.
If quote is True, apostrophe, quote, and newline will be quoted """ warnings.warn("[0.5] livepage.flt is deprecated. Don't use it.", DeprecationWarning, 2) from nevow import testutil fr = testutil.FakeRequest() ctx = context.RequestContext(tag=fr) ctx.remember(client, IClientHandle) ctx.remember(handlerFactory, IHandlerFactory) ctx.remember(None, inevow.IData)
fl = flat.flatten(stan, ctx=ctx) if quote: fl = fl.replace('\\', '\\\\').replace("'", "\\'").replace('\n', '\\n') return fl
|