python-nevow 0.10.0-4build1 / usr / share / pyshared / nevow / livepage.py

# -*- 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