%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright 2001 by Object Craft P/L, Melbourne, Australia.
% LICENCE - see LICENCE file distributed with this software for details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Summary of Changes\label{changes}}

This chapter describes the changes made to Albatross between releases.

\section{Release 1.35\label{rel-1.35}}

This section describes the changes in release 1.35 of Albatross that were
made since release 1.34. Note that release 1.34 was an internal release.

\subsection{New Features\label{rel-1.35-new}}

\subsubsection{New FastCGI module\label{rel-1.35-fcgiappnew}}

A drop-in replacement for the \texttt{fcgiapp} module, called
\texttt{fcgiappnew} has been added. This version implements the FastCGI
protocol itself, rather than relying on an external module to implement
the protocol (we have not been able to clarify the license of the
fcgi.py module). This new module addresses several minor problems
with fcgi.py, and should be faster, although it should not be used
in critical applications until it has received wider testing. This
module will eventually be renamed to replace fcgiapp (at which point,
the fcgiappnew name will dropped).

\subsection{Functional Changes\label{rel-1.35-func}}

\subsubsection{Validate extension tag names\label{rel-1.35-check-ext-tag}}

When extension tags (alx-*) are registered, their name is now checked
against the template parsing regexp to ensure they can subsequently
be matched.

\subsection{Bug Fixes\label{rel-1.35-bug}}

\subsubsection{Enhance AnyTag with knowledge of empty HTML tags\label{rel-1.35-empty-anytag}}

The AnyTag functionality was given knowledge of HTML tags for which
the close tag is forbidden, so it can avoid generating XHTML empty tag
(which could cause the page to fail HTML validation).

\subsubsection{Input tags with disabledbool attribute\label{rel-1.35-disabledbool}}

When the disabledbool attribute was used on input tags, the disabled
state was not being passed through to the input registry within the
\class{NameRecorderMixin}.

\subsubsection{Improve session server handling of aborted connections\label{rel-1.35-sess-srv-abort}}

If a client closed it's connection to the session server while the
server had data pending for the client, a subsequent del\_write\_file
would generate an exception, killing the session server.

\section{Release 1.33\label{rel-1.33}}

This section describes the changes in release 1.33 of Albatross that
were made since release 1.32.

\subsection{Bug Fixes\label{rel-1.33-bug}}

\subsubsection{ctx.set\_value()\label{rel-1.33-set-value}}

Fixed handling of tree iterator backdoor and improved error reporting.

\section{Release 1.32\label{rel-1.32}}

This section describes the changes in release 1.32 of Albatross that
were made since release 1.31.

\subsection{Bug Fixes\label{rel-1.32-bug}}

\subsubsection{\_caller\_globals()\label{rel-1.32-bug-frame}}

To obtain a reference to the current frame, \_caller\_globals was
raising and catching an exception, then extracting the tb\_frame member
of sys.exc\_traceback. sys.exc\_traceback was deprecated in python
1.5 as it is not thread-safe. It now appears to be unreliable in 2.4,
so \_caller\_globals has been changed to use sys.\_getframe().

\subsubsection{ctx.set\_page() from start page\label{rel-1.32-start-page}}

If ctx.set\_page() was called from within the start page, then the
wrong page methods (page\_enter, page\_display, etc) would be called
(those of the initial page, rather than the page requested via set\_page).

\section{Release 1.31\label{rel-1.31}}

This section describes the changes in release 1.31 of Albatross that
were made since release 1.30.

\subsection{Bug Fixes\label{rel-1.31-bug}}

\subsubsection{RandomPage error handling\label{rel-1.31-randompage}}

Fixes to handling of missing RandomPage page modules.

\section{Release 1.30\label{rel-1.30}}

This section describes the changes in release 1.30 of Albatross that
were made since release 1.20.

\subsection{Functional Changes\label{rel-1.30-func}}

\subsubsection{Evaluate any attribute of any tag\label{rel-1.30-anytag}}

Arbitrary HTML tags can now access the templating engine by prefixing the
tag with "al-". Attributes of the tag can then be selectively evaluated
to derive their value.  Appending "expr" to the attribute name causes
the result of evaluating the expression to be substituted for the value
of the attribute. Appending "bool" results in the attribute value being
evaluated in a boolean context, and if true, a boolean HTML attribute
is emitted. For example:

\begin{verbatim}
<al-td colspanexpr="i.span()"> 
\end{verbatim}
could produce 
\begin{verbatim}
<td colspan="3">
\end{verbatim}
and:
\begin{verbatim}
<al-input name="abc.value" disabledbool="abc.isdisabled()">
\end{verbatim}
could produce 
\begin{verbatim}
<input name="abc.value" disabled>
\end{verbatim}

\subsubsection{Enforce only one definition of macros and lookups\label{rel-1.30-checkdefs}}

Since macros and lookups are an application global resource, they can
only be defined once per application, however this was not previously
enforced. Redefinition of macros or lookups will now result in an
ApplicationError exception.

\subsubsection{In-line expansion of \texttt{<al-lookup>}\label{rel-1.30-inlinelookup}}

The \texttt{<al-lookup>} tag can now be optionally expanded in place. If
the tag has an expr= attribute, this will be evaluated and used as
the value to look up, and the results of the lookup substituted for the
tag. 

Functionality of named lookups remains unchanged.

\subsubsection{New \texttt{<al-require>} tag\label{rel-1.30-require}}

A new <al-require> tag has been added to allow templates to assert
that specific Albatross features are available, or templating scheme
version number is high enough. For instance, the addition of the "Any
Tag" functionality has resulting in the templating version incrementing
from 1 to 2.

\subsubsection{Set Cache-Control header\label{rel-1.30-cachecontrol}}

\texttt{Cache-Control: no-cache} is now set in addition to \texttt{Pragma:
no-cache}. 

\texttt{Cache-Control} was introduced in HTTP/1.1, prior to this the same
effect was achieved with \texttt{Pragma}. Some browsers change their
behaviour depending on whether the page was delivered via HTTP/1.1
or HTTP/1.0.

\subsubsection{Simplified Session Cookie handling\label{rel-1.30-simplecookie}}

Session cookie handling has been simplified.

\subsection{Bug Fixes\label{rel-1.30-bug}}

\subsubsection{FastCGI finalisation\label{rel-1.30-fcgifinalise}}

FastCGI apps were not being explicitly finalised, relying instead on their
object destructor, with the result that writing application output (or
errors) would be indefinitely deferred if object cycles existed. We now call
\texttt{fcgi.Finish()} from the fcgiapp \texttt{Request.return_code()}
method.

\subsubsection{Delete traceback objects\label{rel-1.30-tbcycle}}

When handling exceptions, the traceback is now explicitly deleted
from the local namespace to prevent cycles (otherwise the garbage
collection of other objects in the local namespace will be delayed).

\subsubsection{\texttt{<al-select>} fixes\label{rel-1.30-alselect}}

Two fixes to the \texttt{<al-select>} tag: the albatross-specific "list"
attribute was leaking into resulting markup, and the use of the "expr"
attribute would result in invalid markup being emitted.

\subsubsection{Illegal placement of \texttt{<input>} tag\label{rel-1.30-hiddeninput}}

Thanks to Robert Fendt for picking this up: the Albatross-generated hidden
field input element must not appear naked inside a form element for strict
HTML conformance.  The solution is to wrap the input elements in div.

\subsubsection{Allow BranchingSessions to be deleted\label{rel-1.30-branchsessdel}}
BranchingSession sessions could not be "deleted" because each interaction
is a separate session. The solution implemented is to add a dummy
"session" shared by all branches, which is deleted when one branch
"logs out".


\section{Release 1.20\label{rel-1.20}}

This section describes the changes in release 1.20 of Albatross that
were made since release 1.11.

\subsection{Functional Changes\label{rel-1.20-func}}

\subsubsection{New \texttt{BranchingSessionContext}\label{rel-1.20-branchingsession}}

A persistent problem with server-side sessions is the browser state
getting out of synchronisation with the application state. This occurs
when the user reloads the page or uses the "back" button. 

A new \texttt{BranchingSessionContext} application context class has
been added that attempts to work around this problem by creating a new
server-side session for every interaction with the browser. The unique
session identifier is stored in a hidden form field, rather than a cookie.

The new Context class is intended to be used with the server-side
Application classes, and provides a similar experience to storing the
context in a hidden form field, without the overhead and security issues
of sending the context on a round-trip through the user's browser.

No effort is made at this time to control the resources used by these
server-side sessions, other than expiring them after \texttt{session_age}
seconds.

\subsubsection{Improved Request classes\label{rel-1.20-refactorrequest}}

The Request classes provide the interface between specific application
deployment models (CGI, FastCGI, mod_python, etc), and the Albatross
application. These classes have been refactored to extract common
functionality into a new RequestBase class. The Request classes also
now have methods for passing status back to browser.

\subsubsection{Page Module loading\label{rel-1.20-pagemodule}}

The page module loader in PageModuleMixin has been reimplemented so
that it does not pollute \code{sys.modules}.  Page modules are now
loaded into a synthetic module's namespace, rather than the global
module namespace. This will break code that defined classes in page
modules and placed instances of those classes into the session.

\subsubsection{Multi-instance response headers now supported\label{rel-1.20-responsemultiheader}}

Some HTTP headers can appear multiple times (for example Set-Cookie)
- the response handling has been modified to allow multiple instances
of a header. \texttt{ResponseMixin.get_header()} now returns a list of
strings, rather than just a string. The httpdapp module has also been
updated to allow multiple instances of a header, keeping headers in a
list rather than a dictionary.

\subsubsection{simpler \texttt{req_equals()} matching with image maps\label{rel-1.20-reqequalsimgmap}}
\texttt{ctx.req_equals(name)} now checks for \texttt{name.x} if
\texttt{name} is not found. This makes using image maps as buttons
easier (from Michael C. Neel).

\subsection{Bug Fixes\label{rel-1.20-bug}}

\subsubsection{\texttt{redirect_url()} fixes\label{rel-1.20-fixredirecturl}}

Under some circumstances, \texttt{redirect_url()} would redirect to
incorrect or invalid URLs (for example, an https app would redirect
to http) - the URI parsing has been refactored, and this bug has been
fixed. Tests were also added for the refactored URI parsing.

\subsubsection{Improved request status handling\label{rel-1.20-requeststatus}}

\begin{enumerate}

\item
Symbolic names are now defined for the RFC1945 status header values,
such as HTTP_OK, HTTP_MOVED_PERMANENTLY, HTTP_MOVED_TEMPORARILY and
HTTP_INTERNAL_SERVER_ERROR

\item
The Request classes (deployment model adaptors) and Application
\texttt{run()} method have been updated to correctly pass the returned
status back to the client.

\end{enumerate}

\subsubsection{Response header matching now case-insensitive\label{rel-1.20-responseheadercase}}

Response header names were being matched in a case-sensitive way -
this was incorrect and has been fixed.

\subsubsection{Cookie handling fixes\label{rel-1.20-cookiefixes}}

\begin{enumerate}

\item
A Cookie path bug was noticed when Albatross applications were used
with the Safari browser. \texttt{absolute_base_url()} was generating
a trailing slash on the returned application URL (so /path/app.cgi/
instead of /path/app.cgi).  This was causing problems for requests like
/path/app.cgi?blah in that Safari did not send the cookie (probably
correctly).

\item
When an application was accessed via https, the \texttt{secure} attribute
on any resulting cookies was not being set. This attribute marks the
cookie to be only returned via an https connection. The \texttt{secure}
attribute is now set.

\item
Cookie max-age was being allowed to default - this is now explicitly
set to match the configured session age (from the Application
\texttt{session_age} parameter).

\end{enumerate}

\section{Release 1.11\label{rel-1.11}}

This section describes the changes in release 1.11 of Albatross that
were made since release 1.10.

\subsection{Functional Changes\label{rel-1.11-func}}

\subsubsection{\texttt{<al-select>/<al-input>} consistency\label{rel-1.11-alselectconsistency}}

\texttt{<al-select>} handling of \texttt{name}, \texttt{expr},
\texttt{valueexpr} and \texttt{value} attributes has been made consistent
with that of \texttt{<al-input>}.

\subsubsection{\texttt{absolute_base_url} method\label{rel-1.11-absbaseurl}}

New method \method{absolute_base_url()} has been added to the
\class{AppContext}.

\subsubsection{\texttt{al-httpd} enhancements\label{rel-1.11-httpd}}

Matt Goodall has continued to improve the capabilities of the
\texttt{al-httpd} program and \module{httpdapp.py} so that it is now
possible to run all of the CGI based sample applications.

You can now initialise the \code{static_resources} from the command
line.  For example, the tree samples can be executed to serve up their
images like this:

\begin{verbatim}
$ cd samples/tree2
$ al-httpd tree.app 8080 /alsamp/images ../images/
\end{verbatim}

\subsubsection{XHTML fixes\label{rel-1.11-xhtml}}

The \texttt{<al-input>} and \texttt{<al-img>} tags now output XHTML
compliant end tags.

\subsection{Bug Fixes\label{rel-1.11-bug}}

\subsubsection{\texttt{mod_python} support\label{rel-1.11-modpython}}

Greg Bond fixed a \module{cgiapp} field handling incompatibility with
\texttt{mod_python} 3.

\subsubsection{\texttt{get_servername()} support\label{rel-1.11-servername}}

The \method{get_servername()} method of the \module{cgiapp} and
\module{fcgiapp} \class{Request} classes now use the
\texttt{HTTP_HOST} environment variable rather than
\texttt{SERVER_NAME}.

\subsubsection{Multiple cookies\label{rel-1.11-cookie}}

All session cookies now include a path attribute.  This prevents
multiple redundant cookies being set for all URI paths in an
application.

\section{Release 1.10\label{rel-1.10}}

This section describes the changes in release 1.10 of Albatross that
were made since release 1.01.

\subsection{Functional Changes\label{rel-1.10-func}}

\subsubsection{FastCGI support\label{rel-1.10-fastcgi}}

Matt Goodall developed support for deployment of applications via
FastCGI.  FastCGI applications import their \class{Request} class from
\module{albatross.fcgiapp}.

\subsubsection{Standalone BaseHTTPServer support\label{rel-1.10-standalone}}

Matt Goodall developed support for standalone deployment of
applications via the standard Python \module{BaseHTTPServer} module.
The \texttt{al-httpd} program can be used to deploy a CGI application
as a standalone \module{BaseHTTPServer} server.

\subsubsection{Exception Classes\label{rel-1.10-exc}}

All Albatross exceptions have been redefined to indicate the source of
the error; user (\exception{UserError}), programmer
(\exception{ApplicationError}), or Albatross itself
(\exception{InternalError}).  The \exception{ServerError} exception
reports problems related to the session server, 
\exception{SecurityError} reports either a programmer error, or a user
attempt to access restricted values in the execution context, and
\exception{TemplateLoadError} reports failures to load templates.

All of the exceptions inherit from \exception{AlbatrossError}.

The \module{albatross.common} module defines the exceptions.

\subsubsection{Response Header Management\label{rel-1.10-headers}}

All response header management has been moved to the
\class{ResponseMixin} class.  The \class{AppContext} class now
inherits from \class{ResponseMixin}.  The \class{Request} class no
longer tracks whether or not headers have been sent.

\class{ResponseMixin} provides the ability to set, get, delete, and
send headers.  Headers are automatically sent when the application
sends any content to the browser.

The \method{write_headers()} method has been deleted from the
following classes; \class{SimpleAppContext},
\class{SessionAppContext}, \class{SessionServerContextMixin},
\class{SessionFileContextMixin}, \class{SessionFileAppContext}.

For \class{SessionServerContextMixin} and
\class{SessionFileContextMixin} the \texttt{Set-Cookie} header is set
when session is created or loaded.

\subsubsection{HTTP Response Codes\label{rel-1.10-response}}

The \method{Application.run()} method no longer unconditionally
returns an HTTP response code of \texttt{200}.  The returned response
code is retrieved from the \class{Request.status()} method.  You can
call the \method{Request.set_status()} method to override the default
HTTP response code of \code{200}.

\subsubsection{File Uploading\label{rel-1.10-upload}}

The \texttt{<al-input>} tag now supports \texttt{type="file"} input
tags.  When you use file input tags the enclosing \texttt{<al-form>}
tag automatically adds the \texttt{enctype="multipart/form-data"}
attribute to the generated \texttt{<form>} tag.

The \module{albatross.cgiapp} and \module{albatross.apacheapp} modules
define a \class{FileField} class which provides access to uploaded
files.  During request merging the \method{Request.field_file()}
method returns instances of \class{FileField} for uploaded files.

\subsubsection{Session Changes\label{rel-1.10-session}}

The \method{Application.run()} method now saves the session before
flushing the response to the browser.  This allows applications to
support dynamically generated images.

The \method{SessionBase.add_session_vars()} method now raises an
\exception{ApplicationError} exception if you attempt to add variables
to the session which do not exist in the local namespace.

The \method{SessionBase.default_session_var()} method allows you to
add a variable to the session and place it in the local namespace at
the same time.

Session saving previously silently removed session values which could
not be pickled.  Now unpickleable values are reported via an
\exception{ApplicationError} exception.

Errors handling and reporting during session loading has been
improved.

\subsubsection{Exception Formatting and Handling\label{rel-1.10-excfmt}}

The exception formatting in \method{Application.handle_exception()}
has been moved into the \method{format_exception()} method.
Applications can perform their own exception formatting and/or send
formatted exceptions to locations other than the browser.

\subsubsection{Unicode\label{rel-1.10-unicode}}

The \method{ExecuteMixin.write_content()} method now converts unicode
to UTF-8.

\subsubsection{Execution Context Available to Template Expressions\label{rel-1.10-ctx}}

During \method{NamespaceMixin.eval_expr()} the execution context is
temporary placed into the local namespace as the variable
\var{__ctx__}.

\subsubsection{Request Merging\label{rel-1.10-merging}}

\method{NamespaceMixin.set_value()} ignores attempts to set Albatross
iterators that are not present in the namespace.

\method{NamespaceMixin.set_value()} produces a nice syntax error like
report when an illegal field name is used.

\subsubsection{Locating Globals for Template Expressions\label{rel-1.10-globals}}

The \function{_caller_globals()} function has been changed to use the
name of a function rather a stack frame count.  This is used by the
methods \method{AppContext.run_template()},
\method{AppContext.run_template_once()},
\method{RandomPageModuleMixin.display_response()}, and
\method{SimpleContext.__init__()} to locate the module whose globals
will be used as the global namespace for evaluating template
expressions.

\subsubsection{Tree Handling\label{rel-1.10-tree}}

The \texttt{<al-tree>} tag now has a \texttt{single} attribute which
enables the single select mode.  In single select mode, selecting a
node automatically deselects any previously selected node.

The \texttt{<al-input>} tag now supports the \texttt{treefold="expr"},
\texttt{treeselect="expr"}, and \texttt{treeellipsis="expr"}
attributes.  The expression specifies a tree node that is used to
construct a tree iterator input value.

The following methods have been added to the \class{LazyTreeIterator}
class; \method{load_children()}, \method{is_selected()},
\method{select_alias()}, \method{open_alias()}.

\subsubsection{Lookup Evaluation\label{rel-1.10-lookup}}

The \texttt{<al-lookup>} tag now registers the lookup during template
parsing rather than during evaluation.  This allows template code to
make use of lookups that are defined later in the same file.  The item
dictionary is created the first time that the lookup is used rather
than when the template is interpreted.

\subsubsection{Macro Argument Evaluation\label{rel-1.10-macro}}

Macro arguments are now evaluated when they are referenced rather than
before they are passed to a macro.

This removes a limitation where you could not define macros including
\texttt{<al-form>} tags that retrieved \texttt{<al-input>} tags from
their arguments.  Previously the \texttt{<al-input>} tags passed as
macro arguments would have been evaluated outside of the context of
the form defined in the macro.  This effectively made the input tags
invisible to the form recorder.

\subsubsection{\texttt{<select>/<option>} formatting\label{rel-1.10-select}}

The \texttt{<al-option>} and \texttt{<al-select>} tags always write
\texttt{</option>} close tags.

\subsubsection{\texttt{noescape} tag attribute\label{rel-1.10-noescape}}

The \texttt{noescape} attribute has been added to the
\texttt{<al-input>}, \texttt{<al-img>}, \texttt{<al-select>}, and
\texttt{<al-textarea>} tags.

\subsubsection{Documentation\label{rel-1.10-doc}}

The templates reference documentation has been completely restructured
to improve clarity.  All attributes of each tag have been documented.

\subsection{Bug Fixes\label{rel-1.10-bug}}

\subsubsection{Lingering Content Trap\label{rel-1.10-content}}

In some circumstances exceptions would leave a content trap in place
that prevented an error report from being written to the browser.

\subsubsection{Session Loading\label{rel-1.10-sesload}}

More exceptions are trapped by the session unpickling code to make
error handling more robust.

\subsubsection{Random Page Module Loading\label{rel-1.10-pageload}}

Fixed a bug where an import error inside a page module loaded by the
\class{RandomPageModuleMixin} was being handled as if page module
could not be located.

\subsubsection{Session Id Cookie Handling\label{rel-1.10-sescookie}}

Fixed cookie handling which previously could not cope with missing
session id when the cookie was present.

\subsubsection{\texttt{<al-input>} tag\label{rel-1.10-input}}

Fixed bug in checkbox.

Only prevent the generation of the \texttt{value} attribute when the
value is \code{None}.

\subsubsection{\texttt{<al-input>} tag\label{rel-1.10-modpython}}

The \module{apacheapp} \class{Request} class now works for mod_python
2.3 and 3.0.