+
−Wiki Example
+
−============
+
−
+
−:author: Ian Bicking <ianb@colorstudy.com>
+
−
+
−.. contents::
+
−
+
−Introduction
+
−------------
+
−
+
−This is an example of how to write a WSGI application using WebOb.
+
−WebOb isn't itself intended to write applications -- it is not a web
+
−framework on its own -- but it is *possible* to write applications
+
−using just WebOb.
+
−
+
−The `file serving example <file-example.html>`_ is a better example of
+
−advanced HTTP usage.  The `comment middleware example
+
−<comment-example.html>`_ is a better example of using middleware.
+
−This example provides some completeness by showing an
+
−application-focused end point.
+
−
+
−This example implements a very simple wiki.
+
−
+
−Code
+
−----
+
−
+
−The finished code for this is available in
+
−`docs/wiki-example-code/example.py
+
−<http://svn.pythonpaste.org/Paste/WebOb/trunk/docs/wiki-example-code/example.py>`_
+
−-- you can run that file as a script to try it out.
+
−
+
−Creating an Application
+
−-----------------------
+
−
+
−A common pattern for creating small WSGI applications is to have a
+
−class which is instantiated with the configuration.  For our
+
−application we'll be storing the pages under a directory.
+
−
+
−.. code-block::
+
−
+
−    class WikiApp(object):
+
−
+
−        def __init__(self, storage_dir):
+
−            self.storage_dir = os.path.abspath(os.path.normpath(storage_dir))
+
−
+
−WSGI applications are callables like ``wsgi_app(environ,
+
−start_response)``.  *Instances* of `WikiApp` are WSGI applications, so
+
−we'll implement a ``__call__`` method:
+
−
+
−.. code-block::
+
−
+
−    class WikiApp(object):
+
−        ...
+
−        def __call__(self, environ, start_response):
+
−            # what we'll fill in
+
−
+
−To make the script runnable we'll create a simple command-line
+
−interface:
+
−
+
−.. code-block::
+
−
+
−    if __name__ == '__main__':
+
−        import optparse
+
−        parser = optparse.OptionParser(
+
−            usage='%prog --port=PORT'
+
−            )
+
−        parser.add_option(
+
−            '-p', '--port',
+
−            default='8080',
+
−            dest='port',
+
−            type='int',
+
−            help='Port to serve on (default 8080)')
+
−        parser.add_option(
+
−            '--wiki-data',
+
−            default='./wiki',
+
−            dest='wiki_data',
+
−            help='Place to put wiki data into (default ./wiki/)')
+
−        options, args = parser.parse_args()
+
−        print 'Writing wiki pages to %s' % options.wiki_data
+
−        app = WikiApp(options.wiki_data)
+
−        from wsgiref.simple_server import make_server
+
−        httpd = make_server('localhost', options.port, app)
+
−        print 'Serving on http://localhost:%s' % options.port
+
−        try:
+
−            httpd.serve_forever()
+
−        except KeyboardInterrupt:
+
−            print '^C'
+
−
+
−There's not much to talk about in this code block.  The application is
+
−instantiated and served with the built-in module
+
−`wsgiref.simple_server
+
−<http://www.python.org/doc/current/lib/module-wsgiref.simple_server.html>`_.
+
−
+
−The WSGI Application
+
−--------------------
+
−
+
−Of course all the interesting stuff is in that ``__call__`` method.
+
−WebOb lets you ignore some of the details of WSGI, like what
+
−``start_response`` really is.  ``environ`` is a CGI-like dictionary,
+
−but ``webob.Request`` gives an object interface to it.
+
−``webob.Response`` represents a response, and is itself a WSGI
+
−application.  Here's kind of the hello world of WSGI applications
+
−using these objects:
+
−
+
−.. code-block::
+
−
+
−    from webob import Request, Response
+
−
+
−    class WikiApp(object):
+
−        ...
+
−
+
−        def __call__(self, environ, start_response):
+
−            req = Request(environ)
+
−            resp = Response(
+
−                'Hello %s!' % req.params.get('name', 'World'))
+
−            return resp(environ, start_response)
+
−
+
−``req.params.get('name', 'World')`` gets any query string parameter
+
−(like ``?name=Bob``), or if it's a POST form request it will look for
+
−a form parameter ``name``.  We instantiate the response with the body
+
−of the response.  You could also give keyword arguments like
+
−``content_type='text/plain'`` (``text/html`` is the default content
+
−type and ``200 OK`` is the default status).
+
−
+
−For the wiki application we'll support a couple different kinds of
+
−screens, and we'll make our ``__call__`` method dispatch to different
+
−methods depending on the request.  We'll support an ``action``
+
−parameter like ``?action=edit``, and also dispatch on the method (GET,
+
−POST, etc, in ``req.method``).  We'll pass in the request and expect a
+
−response object back.
+
−
+
−Also, WebOb has a series of exceptions in ``webob.exc``, like
+
−``webob.exc.HTTPNotFound``, ``webob.exc.HTTPTemporaryRedirect``, etc.
+
−We'll also let the method raise one of these exceptions and turn it
+
−into a response.
+
−
+
−One last thing we'll do in our ``__call__`` method is create our
+
−``Page`` object, which represents a wiki page.
+
−
+
−All this together makes:
+
−
+
−.. code-block::
+
−
+
−    from webob import Request, Response
+
−    from webob import exc
+
−
+
−    class WikiApp(object):
+
−        ...
+
−
+
−        def __call__(self, environ, start_response):
+
−            req = Request(environ)
+
−            action = req.params.get('action', 'view')
+
−            # Here's where we get the Page domain object:
+
−            page = self.get_page(req.path_info)
+
−            try:
+
−                try:
+
−                    # The method name is action_{action_param}_{request_method}:
+
−                    meth = getattr(self, 'action_%s_%s' % (action, req.method))
+
−                except AttributeError:
+
−                    # If the method wasn't found there must be
+
−                    # something wrong with the request:
+
−                    raise exc.HTTPBadRequest('No such action %r' % action).exception
+
−                resp = meth(req, page)
+
−            except exc.HTTPException, e:
+
−                # The exception object itself is a WSGI application/response:
+
−                resp = e
+
−            return resp(environ, start_response)
+
−
+
−The Domain Object
+
−-----------------
+
−
+
−The ``Page`` domain object isn't really related to the web, but it is
+
−important to implementing this.  Each ``Page`` is just a file on the
+
−filesystem.  Our ``get_page`` method figures out the filename given
+
−the path (the path is in ``req.path_info``, which is all the path
+
−after the base path).  The ``Page`` class handles getting and setting
+
−the title and content.
+
−
+
−Here's the method to figure out the filename:
+
−
+
−.. code-block::
+
−
+
−    import os
+
−
+
−    class WikiApp(object):
+
−        ...
+
−
+
−        def get_page(self, path):
+
−            path = path.lstrip('/')
+
−            if not path:
+
−                # The path was '/', the home page
+
−                path = 'index'
+
−            path = os.path.join(self.storage_dir)
+
−            path = os.path.normpath(path)
+
−            if path.endswith('/'):
+
−                path += 'index'
+
−            if not path.startswith(self.storage_dir):
+
−                raise exc.HTTPBadRequest("Bad path").exception
+
−            path += '.html'
+
−            return Page(path)
+
−
+
−Mostly this is just the kind of careful path construction you have to
+
−do when mapping a URL to a filename.  While the server *may* normalize
+
−the path (so that a path like ``/../../`` can't be requested), you can
+
−never really be sure.  By using ``os.path.normpath`` we eliminate
+
−these, and then we make absolutely sure that the resulting path is
+
−under our ``self.storage_dir`` with ``if not
+
−path.startswith(self.storage_dir): raise exc.HTTPBadRequest("Bad
+
−path").exception``.
+
−
+
−.. note::
+
−
+
−    ``exc.HTTPBadRequest("Bad path")`` is a ``webob.Response`` object.
+
−    This is a new-style class, so you can't raise it in Python 2.4 or
+
−    under (only old-style classes work).  The attribute ``.exception``
+
−    can actually be raised.  The exception object is *also* a WSGI
+
−    application, though it doesn't have attributes like
+
−    ``.content_type``, etc.
+
−
+
−Here's the actual domain object:
+
−
+
−.. code-block::
+
−
+
−    class Page(object):
+
−        def __init__(self, filename):
+
−            self.filename = filename
+
−
+
−        @property
+
−        def exists(self):
+
−            return os.path.exists(self.filename)
+
−
+
−        @property
+
−        def title(self):
+
−            if not self.exists:
+
−                # we need to guess the title
+
−                basename = os.path.splitext(os.path.basename(self.filename))[0]
+
−                basename = re.sub(r'[_-]', ' ', basename)
+
−                return basename.capitalize()
+
−            content = self.full_content
+
−            match = re.search(r'<title>(.*?)</title>', content, re.I|re.S)
+
−            return match.group(1)
+
−    
+
−        @property
+
−        def full_content(self):
+
−            f = open(self.filename, 'rb')
+
−            try:
+
−                return f.read()
+
−            finally:
+
−                f.close()
+
−    
+
−        @property
+
−        def content(self):
+
−            if not self.exists:
+
−                return ''
+
−            content = self.full_content
+
−            match = re.search(r'<body[^>]*>(.*?)</body>', content, re.I|re.S)
+
−            return match.group(1)
+
−
+
−        @property
+
−        def mtime(self):
+
−            if not self.exists:
+
−                return None
+
−            else:
+
−                return os.stat(self.filename).st_mtime
+
−
+
−        def set(self, title, content):
+
−            dir = os.path.dirname(self.filename)
+
−            if not os.path.exists(dir):
+
−                os.makedirs(dir)
+
−            new_content = """<html><head><title>%s</title></head><body>%s</body></html>""" % (
+
−                title, content)
+
−            f = open(self.filename, 'wb')
+
−            f.write(new_content)
+
−            f.close()
+
−            
+
−Basically it provides a ``.title`` attribute, a ``.content``
+
−attribute, the ``.mtime`` (last modified time), and the page can exist
+
−or not (giving appropriate guesses for title and content when the page
+
−does not exist).  It encodes these on the filesystem as a simple HTML
+
−page that is parsed by some regular expressions.
+
−
+
−None of this really applies much to the web or WebOb, so I'll leave it
+
−to you to figure out the details of this.
+
−
+
−URLs, PATH_INFO, and SCRIPT_NAME
+
−--------------------------------
+
−
+
−This is an aside for the tutorial, but an important concept.  In WSGI,
+
−and accordingly with WebOb, the URL is split up into several pieces.
+
−Some of these are obvious and some not.
+
−
+
−An example::
+
−
+
−  http://example.com:8080/wiki/article/12?version=10
+
−
+
−There are several components here:
+
−
+
−* req.scheme: ``http``
+
−* req.host: ``example.com:8080``
+
−* req.server_name: ``example.com``
+
−* req.server_port: 8080
+
−* req.script_name: ``/wiki``
+
−* req.path_info: ``/article/12``
+
−* req.query_string: ``version=10``
+
−
+
−One non-obvious part is ``req.script_name`` and ``req.path_info``.
+
−These correspond to the CGI environmental variables ``SCRIPT_NAME``
+
−and ``PATH_INFO``.  ``req.script_name`` points to the *application*.
+
−You might have several applications in your site at different paths:
+
−one at ``/wiki``, one at ``/blog``, one at ``/``.  Each application
+
−doesn't necessarily know about the others, but it has to construct its
+
−URLs properly -- so any internal links to the wiki application should
+
−start with ``/wiki``.
+
−
+
−Just as there are pieces to the URL, there are several properties in
+
−WebOb to construct URLs based on these:
+
−
+
−* req.host_url: ``http://example.com:8080``
+
−* req.application_url: ``http://example.com:8080/wiki``
+
−* req.path_url: ``http://example.com:8080/wiki/article/12``
+
−* req.path: ``/wiki/article/12``
+
−* req.path_qs: ``/wiki/article/12?version=10``
+
−* req.url: ``http://example.com:8080/wiki/article/12?version10``
+
−
+
−You can also create URLs with
+
−``req.relative_url('some/other/page')``.  In this example that would
+
−resolve to ``http://example.com:8080/wiki/article/some/other/page``.
+
−You can also create a relative URL to the application URL
+
−(SCRIPT_NAME) like ``req.relative_url('some/other/page', True)`` which
+
−would be ``http://example.com:8080/wiki/some/other/page``.
+
−
+
−Back to the Application
+
−-----------------------
+
−
+
−We have a dispatching function with ``__call__`` and we have a domain
+
−object with ``Page``, but we aren't actually doing anything.
+
−
+
−The dispatching goes to ``action_ACTION_METHOD``, where ACTION
+
−defaults to ``view``.  So a simple page view will be
+
−``action_view_GET``.  Let's implement that:
+
−
+
−.. code-block::
+
−
+
−    class WikiApp(object):
+
−        ...
+
−
+
−        def action_view_GET(self, req, page):
+
−            if not page.exists:
+
−                return exc.HTTPTemporaryRedirect(
+
−                    location=req.url + '?action=edit')
+
−            text = self.view_template.substitute(
+
−                page=page, req=req)
+
−            resp = Response(text)
+
−            resp.last_modified = page.mtime
+
−            resp.conditional_response = True
+
−            return resp
+
−
+
−The first thing we do is redirect the user to the edit screen if the
+
−page doesn't exist.  ``exc.HTTPTemporaryRedirect`` is a response that
+
−gives a ``307 Temporary Redirect`` response with the given location.
+
−
+
−Otherwise we fill in a template.  The template language we're going to
+
−use in this example is `Tempita <http://pythonpaste.org/tempita/>`_, a
+
−very simple template language with a similar interface to
+
−`string.Template <>`_.
+
−
+
−The template actually looks like this:
+
−
+
−.. code-block::
+
−
+
−    from tempita import HTMLTemplate
+
−
+
−    VIEW_TEMPLATE = HTMLTemplate("""\
+
−    <html>
+
−     <head>
+
−      <title>{{page.title}}</title>
+
−     </head>
+
−     <body>
+
−    <h1>{{page.title}}</h1>
+
−
+
−    <div>{{page.content|html}}</div>
+
−
+
−    <hr>
+
−    <a href="{{req.url}}?action=edit">Edit</a>
+
−     </body>
+
−    </html>
+
−    """)
+
−
+
−    class WikiApp(object):
+
−        view_template = VIEW_TEMPLATE
+
−        ...
+
−
+
−As you can see it's a simple template using the title and the body,
+
−and a link to the edit screen.  We copy the template object into a
+
−class method (``view_template = VIEW_TEMPLATE``) so that potentially a
+
−subclass could override these templates.
+
−
+
−``tempita.HTMLTemplate`` is a template that does automatic HTML
+
−escaping.  Our wiki will just be written in plain HTML, so we disable
+
−escaping of the content with ``{{page.content|html}}``.
+
−
+
−So let's look at the ``action_view_GET`` method again:
+
−
+
−.. code-block::
+
−
+
−        def action_view_GET(self, req, page):
+
−            if not page.exists:
+
−                return exc.HTTPTemporaryRedirect(
+
−                    location=req.url + '?action=edit')
+
−            text = self.view_template.substitute(
+
−                page=page, req=req)
+
−            resp = Response(text)
+
−            resp.last_modified = page.mtime
+
−            resp.conditional_response = True
+
−            return resp
+
−
+
−The template should be pretty obvious now.  We create a response with
+
−``Response(text)``, which already has a default Content-Type of
+
−``text/html``.
+
−
+
−To allow conditional responses we set ``resp.last_modified``.  You can
+
−set this attribute to a date, None (effectively removing the header),
+
−a time tuple (like produced by ``time.localtime()``), or as in this
+
−case to an integer timestamp.  If you get the value back it will
+
−always be a `datetime <>`_ object (or None).  With this header we can
+
−process requests with If-Modified-Since headers, and return ``304 Not
+
−Modified`` if appropriate.  It won't actually do that unless you set
+
−``resp.conditional_response`` to True.  
+
−
+
−.. note::
+
−
+
−    If you subclass ``webob.Response`` you can set the class attribute
+
−    ``default_conditional_response = True`` and this setting will be
+
−    on by default.  You can also set other defaults, like the
+
−    ``default_charset`` (``"utf8"``), or ``default_content_type``
+
−    (``"text/html"``).
+
−
+
−The Edit Screen
+
−---------------
+
−
+
−The edit screen will be implemented in the method
+
−``action_edit_GET``.  There's a template and a very simple method:
+
−
+
−.. code-block::
+
−
+
−    EDIT_TEMPLATE = HTMLTemplate("""\
+
−    <html>
+
−     <head>
+
−      <title>Edit: {{page.title}}</title>
+
−     </head>
+
−     <body>
+
−    {{if page.exists}}
+
−    <h1>Edit: {{page.title}}</h1>
+
−    {{else}}
+
−    <h1>Create: {{page.title}}</h1>
+
−    {{endif}}
+
−
+
−    <form action="{{req.path_url}}" method="POST">
+
−     <input type="hidden" name="mtime" value="{{page.mtime}}">
+
−     Title: <input type="text" name="title" style="width: 70%" value="{{page.title}}"><br>
+
−     Content: <input type="submit" value="Save"> 
+
−     <a href="{{req.path_url}}">Cancel</a>
+
−       <br>
+
−     <textarea name="content" style="width: 100%; height: 75%" rows="40">{{page.content}}</textarea>
+
−       <br>
+
−     <input type="submit" value="Save">
+
−     <a href="{{req.path_url}}">Cancel</a>
+
−    </form>
+
−    </body></html>
+
−    """)
+
−
+
−    class WikiApp(object):
+
−        ...
+
−
+
−        edit_template = EDIT_TEMPLATE
+
−
+
−        def action_edit_GET(self, req, page):
+
−            text = self.edit_template.substitute(
+
−                page=page, req=req)
+
−            return Response(text)
+
−
+
−As you can see, all the action here is in the template.  
+
−
+
−In ``<form action="{{req.path_url}}" method="POST">`` we submit to
+
−``req.path_url``; that's everything *but* ``?action=edit``.  So we are
+
−POSTing right over the view page.  This has the nice side effect of
+
−automatically invalidating any caches of the original page.  It also
+
−is vaguely `RESTful <>`_.
+
−
+
−We save the last modified time in a hidden ``mtime`` field.  This way
+
−we can detect concurrent updates.  If start editing the page who's
+
−mtime is 100000, and someone else edits and saves a revision changing
+
−the mtime to 100010, we can use this hidden field to detect that
+
−conflict.  Actually resolving the conflict is a little tricky and
+
−outside the scope of this particular tutorial, we'll just note the
+
−conflict to the user in an error.
+
−
+
−From there we just have a very straight-forward HTML form.  Note that
+
−we don't quote the values because that is done automatically by
+
−``HTMLTemplate``; if you are using something like ``string.Template``
+
−or a templating language that doesn't do automatic quoting, you have
+
−to be careful to quote all the field values.
+
−
+
−We don't have any error conditions in our application, but if there
+
−were error conditions we might have to re-display this form with the
+
−input values the user already gave.  In that case we'd do something
+
−like::
+
−
+
−    <input type="text" name="title"
+
−     value="{{req.params.get('title', page.title)}}">
+
−
+
−This way we use the value in the request (``req.params`` is both the
+
−query string parameters and any variables in a POST response), but if
+
−there is no value (e.g., first request) then we use the page values.
+
−
+
−Processing the Form
+
−-------------------
+
−
+
−The form submits to ``action_view_POST`` (``view`` is the default
+
−action).  So we have to implement that method:
+
−
+
−.. code-block::
+
−
+
−    class WikiApp(object):
+
−        ...
+
−
+
−        def action_view_POST(self, req, page):
+
−            submit_mtime = int(req.params.get('mtime') or '0') or None
+
−            if page.mtime != submit_mtime:
+
−                return exc.HTTPPreconditionFailed(
+
−                    "The page has been updated since you started editing it")
+
−            page.set(
+
−                title=req.params['title'],
+
−                content=req.params['content'])
+
−            resp = exc.HTTPSeeOther(
+
−                location=req.path_url)
+
−            return resp
+
−
+
−The first thing we do is check the mtime value.  It can be an empty
+
−string (when there's no mtime, like when you are creating a page) or
+
−an integer.  ``int(req.params.get('time') or '0') or None`` basically
+
−makes sure we don't pass ``""`` to ``int()`` (which is an error) then
+
−turns 0 into None (``0 or None`` will evaluate to None in Python --
+
−``false_value or other_value`` in Python resolves to ``other_value``).
+
−If it fails we just give a not-very-helpful error message, using ``412
+
−Precondition Failed`` (typically preconditions are HTTP headers like
+
−``If-Unmodified-Since``, but we can't really get the browser to send
+
−requests like that, so we use the hidden field instead).
+
−
+
−.. note::
+
−
+
−    Error statuses in HTTP are often under-used because people think
+
−    they need to either return an error (useful for machines) or an
+
−    error message or interface (useful for humans).  In fact you can
+
−    do both: you can give any human readable error message with your
+
−    error response.
+
−
+
−    One problem is that Internet Explorer will replace error messages
+
−    with its own incredibly unhelpful error messages.  However, it
+
−    will only do this if the error message is short.  If it's fairly
+
−    large (4Kb is large enough) it will show the error message it was
+
−    given.  You can load your error with a big HTML comment to
+
−    accomplish this, like ``"<!-- %s -->" % ('x'*4000)``.
+
−
+
−    You can change the status of any response with ``resp.status_int =
+
−    412``, or you can change the body of an ``exc.HTTPSomething`` with
+
−    ``resp.body = new_body``.  The primary advantage of using the
+
−    classes in ``webob.exc`` is giving the response a clear name and a
+
−    boilerplate error message.
+
−
+
−After we check the mtime we get the form parameters from
+
−``req.params`` and issue a redirect back to the original view page.
+
−``303 See Other`` is a good response to give after accepting a POST
+
−form submission, as it gets rid of the POST (no warning messages for the
+
−user if they try to go back).
+
−
+
−In this example we've used ``req.params`` for all the form values.  If
+
−we wanted to be specific about where we get the values from, they
+
−could come from ``req.GET`` (the query string, a misnomer since the
+
−query string is present even in POST requests) or ``req.POST`` (a POST
+
−form body).  While sometimes it's nice to distinguish between these
+
−two locations, for the most part it doesn't matter.  If you want to
+
−check the request method (e.g., make sure you can't change a page with
+
−a GET request) there's no reason to do it by accessing these
+
−method-specific getters.  It's better to just handle the method
+
−specifically.  We do it here by including the request method in our
+
−dispatcher (dispatching to ``action_view_GET`` or
+
−``action_view_POST``).
+
−
+
−
+
−Cookies
+
−-------
+
−
+
−One last little improvement we can do is show the user a message when
+
−they update the page, so it's not quite so mysteriously just another
+
−page view.
+
−
+
−A simple way to do this is to set a cookie after the save, then
+
−display it in the page view.  To set it on save, we add a little to
+
−``action_view_POST``:
+
−
+
−.. code-block::
+
−
+
−    def action_view_POST(self, req, page):
+
−        ...
+
−        resp = exc.HTTPSeeOther(
+
−            location=req.path_url)
+
−        resp.set_cookie('message', 'Page updated')
+
−        return resp
+
−
+
−And then in ``action_view_GET``:
+
−
+
−.. code-block::
+
−
+
−
+
−    VIEW_TEMPLATE = HTMLTemplate("""\
+
−    ...
+
−    {{if message}}
+
−    <div style="background-color: #99f">{{message}}</div>
+
−    {{endif}}
+
−    ...""")
+
−
+
−    class WikiApp(object):
+
−        ...
+
−
+
−        def action_view_GET(self, req, page):
+
−            ...
+
−            if req.cookies.get('message'):
+
−                message = req.cookies['message']
+
−            else:
+
−                message = None
+
−            text = self.view_template.substitute(
+
−                page=page, req=req, message=message)
+
−            resp = Response(text)
+
−            if message:
+
−                resp.delete_cookie('message')
+
−            else:
+
−                resp.last_modified = page.mtime
+
−                resp.conditional_response = True
+
−            return resp
+
−
+
−``req.cookies`` is just a dictionary, and we also delete the cookie if
+
−it is present (so the message doesn't keep getting set).  The
+
−conditional response stuff only applies when there isn't any 
+
−message, as messages are private.  Another alternative would be to
+
−display the message with Javascript, like::
+
−
+
−    <script type="text/javascript">
+
−    function readCookie(name) {
+
−        var nameEQ = name + "=";
+
−        var ca = document.cookie.split(';');
+
−        for (var i=0; i < ca.length; i++) {
+
−            var c = ca[i];
+
−            while (c.charAt(0) == ' ') c = c.substring(1,c.length);
+
−            if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length,c.length);
+
−        }
+
−        return null;
+
−    }
+
−    
+
−    function createCookie(name, value, days) {
+
−        if (days) {
+
−            var date = new Date();
+
−            date.setTime(date.getTime()+(days*24*60*60*1000));
+
−            var expires = "; expires="+date.toGMTString();
+
−        } else {
+
−            var expires = "";
+
−        }
+
−        document.cookie = name+"="+value+expires+"; path=/";
+
−    }
+
−
+
−    function eraseCookie(name) {
+
−        createCookie(name, "", -1);
+
−    }
+
−
+
−    function showMessage() {
+
−        var message = readCookie('message');
+
−        if (message) {
+
−            var el = document.getElementById('message');
+
−            el.innerHTML = message;
+
−            el.style.display = '';
+
−            eraseCookie('message');
+
−        }
+
−    }
+
−    </script>
+
−
+
−Then put ``<div id="messaage" style="display: none"></div>`` in the
+
−page somewhere.  This has the advantage of being very cacheable and
+
−simple on the server side.
+
−
+
−Conclusion
+
−----------
+
−
+
−We're done, hurrah!