2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
<html xmlns="http://www.w3.org/1999/xhtml">
6
<title>Nevow Athena from Scratch: Echo Application</title>
10
<h2>What is an "Echo Application?"</h2>
13
Our first foray into building an Athena application will be an easy venture:
14
we want to type something in an input box and have it echoed back to us on
15
the same page, without having to reload anything. Why? Well, our eventual
16
goal is to have a working chat server, with all sorts of technical bells
17
and whistles (persistent storage, authentication,
18
etc.), but that's a bit heady for right now. Many of the same principles
19
which we will eventually employ in our chat application exist for a simple
20
case of sending textual messages between a web browser and a server. This
21
is the essence of our "Echo" application.
24
<h2>Mental Preparation</h2>
27
<a href="../intro.html">Introduction</a> and the
28
<a href="../concepts.html">Concepts</a> pages, we had a refresher on AJAX and
29
COMET and we learned a little bit about what that looks like for Athena. But
30
as we sit down to actually write an Athena application, what do we need to
31
wrap our heads around?
34
<p>Given the introductory knowledge we have, we know that we will need to
35
write some JavaScript, some Python, and if our past experience in developing
36
web applications is any guide, some form of template. This indeed is the
37
case, but here's something big: we're not working with pages and page
38
templates; we're working with "elements", or parts of the DOM tree. We will
39
not be creating page resources; we will be creating just the parts of a
40
"traditional" page that will be dynamic and interactive.
45
<p>Now that we've pumped ourselves up and before we start clacking away at the
46
keyboard, we need to get pointed in the right direction. We need a
47
plan. Here's what we know:</p>
50
<li>We will have a server that:
52
<li>serves dynamic elements in a resource accessible via a URL;</li>
53
<li>communicates with a client.</li>
56
<li>We will have a client that:
58
<li>communicates with the server;</li>
59
<li>updates its DOM tree.</li>
64
<p>The user experience of this application will be the following:</p>
66
<li>they will type text in an input on a form; and</li>
67
<li>the typed text will be rendered to a different part of the page upon
68
hitting a submit button.</li>
71
<p>We will not simply write user input to a <code>div</code> with JavaScript
72
DOM manipulation, but will instead pass data like we expect will be necessary
73
when we write our chat application. After all, it's probably best to build
74
towards our goal. In order to accomplish this, the application will do
75
something like the following:</p>
78
<li>JavaScript client code will extract user input and send
79
it to our server;</li>
80
<li>Python code will receive messages from the client;</li>
81
<li>Python code will send messages to the client; and</li>
82
<li>a template file (or <code>stan</code> code) will be used for
88
<h2>Let the Coding Begin</h2>
90
<p>In a future installment, we will outline the development process from
91
the perspective of test-driven development, in order to not only show how
92
to write unit tests for Athena (Python and JavaScript), but to encourage
93
good programming practices while working with Athena. For now, though, we will
94
just dive right in.</p>
98
<p>Let's start with the easy bit: what our app will look like. Here is the
99
template for our echo application:</p>
101
<a href="listings/echothing/template.html" class="html-listing" />
103
<p>Things to note:</p>
105
<li>This is not a complete HTML document, but is an XHTML template for an
107
<li>The name space declarations in the top <code>div</code> tag are necessary
108
for the operation of Athena.</li>
109
<li>When we hit the "Send" button, our JavaScript class will call the
110
<code>doSay()</code> method.</li>
113
<h3>Writing the Client</h3>
115
<p>Next up is the JavaScript. We need to send our data to the server. In a
116
full chat application, it would be necessary to send the data to the server
117
so that we could propagate the message to all connected clients. In this
118
case, with the simple echo, we're not going to do anything with the data
119
that gets sent to the server, except send it back, of course.</p>
121
<p>Our JavaScript will need to do several things:</p>
123
<li>import required modules;</li>
124
<li>inherit <code>callRemote</code> functionality from the base
125
<code>Widget</code> class;</li>
126
<li>setup convenience attributes;</li>
127
<li>implement the <code>doSay()</code> method we put in our template above;
129
<li>implement a method for updating the DOM with data it receives from
133
<a href="listings/echothing/js/EchoThing.js" class="py-listing" />
135
<p>Points to note:</p>
137
<li>Those import statements aren't just pretty: they are necessary! In Athena,
138
you need to treat those like you treat the import statements in Python.
140
<li>The attributes set in the <code>__init__()</code> method are for
141
convenience when we reference them in other methods.</li>
142
<li>Note the <code>callRemote()</code> method in <code>doSay()</code>,
143
As mentioned in the <a href="../concepts.html">Concepts</a> section, this
144
is how JavaScript is communicating with our Python server.</li>
145
<li>Another thing about <code>doSay</code>: this is the submit handler. As
146
such, it needs to return false so that the browser is prevented from doing a
147
normal form submission.</li>
148
<li><code>addText()</code> is the method that will be updating the browser
149
DOM once the server sends the data back.</li>
152
<p>There's not much to say about the next one. This is what sets up the
153
relationship between our module name and the actual file itself (so that
154
the JavaScript can be loaded):</p>
156
<a href="listings/nevow/plugins/echothing_package.py" class="py-listing" />
158
<h3>Writing the Server</h3>
160
<p>Despite what one might think, writing the server may be the easiest
161
part! If you've created Nevow applications before, then this will look
162
very familiar. The only method we need is one that will send data back to
163
the client. Besides importing the necessary modules and creating a class
164
with some boilerplate, that's about it.
167
<p>Let's take a look at the code:</p>
169
<a href="listings/echothing/echobox.py" class="py-listing" />
171
<p>As promised, simple as can be. We do make use of a Twisted utility that
172
simplifies typing the path to our template. Some very important points:</p>
174
<li>The <code>jsClass</code> assignment is what connects this code to your
175
JavaScript code.</li>
176
<li>As discussed in the <a href="../concepts.html">Concepts</a> section,
177
the <code>expose</code> decorator is required if our JavaScript is going
178
to be able to call the <code>say()</code> method.</li>
181
<h3>Putting it All Together</h3>
183
<p>Now that we've got all the code in front of us, we can trace out exactly
186
<li>the user loads the resource in their browser, and the template is
188
<li>after typing a message in the input box, the user hits submit;</li>
189
<li>upon hitting submit, the client code <code>doSay()</code> method is
191
<li><code>doSay()</code> makes a remote call to the Python server method
192
<code>say()</code>;</li>
193
<li>the Python server receives the data when <code>say()</code> is called, and
194
then it passes that data to the client code's <code>addText()</code> method;</li>
195
<li>with control back in the client code and data fresh from the server,
196
JavaScript can now update the page's DOM with the new data, and this is
197
what the <code>addText()</code> method does;</li>
198
<li>when <code>addText()</code> finishes, the cycle has completed and the
199
browser now displays the latest data input by the user.</li>
202
<h3>The Fruits of Our Labor</h3>
204
<p>Now we get to run it! This is a little different than what you may be
205
used to, if you have written Twisted applications in the past. We are using
206
the plugin architecture of Twisted and Nevow such that <code>twistd</code>
207
will publish our element in an HTTP service. To do this, we will use
208
<code>twistd</code>'s <code>athena-widget</code> command:</p>
211
cd Nevow/doc/howto/chattutorial/part00/listings
212
twistd -n athena-widget --element=echothing.echobox.EchoElement
215
<p>If you executed this against the tutorial code on your local machine,
216
you can now visit <a href="http://localhost:8080">localhost:8080</a> and start
217
echoing to your heart's content.</p>
221
<p>As you can see, our echo application is a toy app that doesn't do
222
anything very useful. However, it has provided us with a basis for learning how
223
to write working Athena code that lets a browser and server communicate
224
with each other, both sending and receiving data. As such, we now have a
225
solid foundation upon which we can build a functional, useful <i>and</i>
226
instructional chat application.</p>
added
removed
Nevow/doc/howto/chattutorial/part00/index.xhtml
