Class n.a.LiveElement(_LiveMixin, Element):

Part of nevow.athena View Source View In Hierarchy

Base-class for a portion of a LivePage.  When being rendered, a LiveElement
has a special ID attribute added to its top-level tag.  This attribute is
used to dispatch calls from the client onto the correct object (this one).

A LiveElement must use the `liveElement' renderer somewhere in its document
template.  The node given this renderer will be the node used to construct
a Widget instance in the browser (where it will be saved as the `node'
property on the widget object).

JavaScript handlers for elements inside this node can use
C{Nevow.Athena.Widget.get} to retrieve the widget associated with this
LiveElement.  For example:

    <form onsubmit="Nevow.Athena.Widget.get(this).callRemote('foo', bar); return false;">

Methods of the JavaScript widget class can also be bound as event
handlers using the handler tag type in the Athena namespace:

    <form xmlns:athena="http://divmod.org/ns/athena/0.7">
        <athena:handler event="onsubmit" handler="doFoo" />
    </form>

This will invoke the C{doFoo} method of the widget which contains the
form node.

Because this mechanism sets up error handling and otherwise reduces the
required boilerplate for handling events, it is preferred and
recommended over directly including JavaScript in the event handler
attribute of a node.

The C{jsClass} attribute of a LiveElement instance determines the
JavaScript class used to construct its corresponding Widget.  This appears
as the 'athena:class' attribute.

JavaScript modules may import other JavaScript modules by using a special
comment which Athena recognizes:

    // import Module.Name

Different imports must be placed on different lines.  No other comment
style is supported for these directives.  Only one space character must
appear between the string 'import' and the name of the module to be
imported.  No trailing whitespace or non-whitespace is allowed.  There must
be exactly one space between '//' and 'import'.  There must be no
preceeding whitespace on the line.

C{Nevow.Athena.Widget.callRemote} can be given permission to invoke methods
on L{LiveElement} instances by passing the functions which implement those
methods to L{nevow.athena.expose} in this way::

    class SomeElement(LiveElement):
        def someMethod(self, ...):
            ...
        expose(someMethod)

Only methods exposed in this way will be accessible.

L{LiveElement.callRemote} can be used to invoke any method of the widget on
the client.

Elements with id attributes will be rewritten so that the id is unique to
that particular instance. The client-side C{Nevow.Athena.Widget.nodeById}
API is provided to locate these later on. For example:

    <div id="foo" />

and then:

    var node = self.nodyById('foo');

On most platforms, this API will be much faster than similar techniques
using C{Nevow.Athena.Widget.nodeByAttribute} etc.