Note - this document is still a work in progress. Please do not make
inline comments in the proposal - use the DTMLExpressionSyntaxFeedback page
to make comments.
Chris Petrilli (email@example.com)
Over the space of the past few years, many people have become
frustrated by the inability to interchange literals and expressions in
many places inside of DTML tags, having instead to offer patches that
provide a solution to the individual problems that they are trying to
solve. This has introduced two mutual incompatible solutions:
For the sake of simplicity, only one convention should be used, and it
should be capable of solving all situations with equal aplomb.
The issue with the current solutions is that using different attributes
creates a situation of namespace collision potential, and the
requirement to find two words to be equivlent in meaning, but somehow
different in interpretation, for example:
- '<... sort="foo"...>' means that you should sort on the literal
- '<... order="foo+1"...>' means that you should sort based on the
resulting value of the expression.
As should be obvious, this introduces needless complexity in learning
DTML, as well as potentially difficult debugging issues as one is
confronted with "side effects" of the naming convention. To correctly
provide calculated attributes for all possible attributes, you would
have to double the number of attributes, creating a learning nightmare.
The second options, differentiating based on the use of quoting
semantics, derives from the current "shortcut" notation of DTML
allowing you to skip the attribute specification and simply use quotes
expr in the
<dtml-var> tag. This is
most definately an eggregious example of programming by side effect,
causing the following two tags to be interpreted differently:
The first would be a literal, the second an expression. This not only
violates the principle of least surprise, but also makes it nearly
impossible to write code that conforms to the SGML specification.
This project proposes to introduce a new semantical representation of
expression syntax as well as a modification to the requirements of DTML
code. Each will be introduced in turn.
Changes to DTML Syntax
The first change, and the one most visible to the end user is a
syntactical change to the DTML tag notation. After careful
consideration, various options were elminated and the abstract
was proposed. In this case, TAGNAME represents the tag that is being
described, attribute is required, and the -FORMAT is optional. If
the format is not provided, it is assumed to be a literal and will
not be evaluated as an expression. Initially, the only
will be supported will be
expr, which will be give you the
following example tag:
which would be equivelent to the current DTML notation of:
The first thing you will notice is that we use the
rather than the
name attribute. This is because
name is now a
format notation, not an attribute. At first this seems like needless
complication, but in fact it allows you to do things such as:
<dtml-var value-python="foo" size-python="browsersize.x/32">
which would take the expression in size and calculate it before doing
the rest of the work. This allows for much more dynamicism, and
eventually enormous customization without the huge if/then clauses
that can currently clutter the code. Or a simple example for other
situations would be:
<dtml-in value="foo" size-name="browserSetVariable">
which would allow you to use a browser set attribute when doing the
In the future, potential other formatting options would be:
The options are virtually unlimited. In addition, it should be wise
to provide a format that provides the "default" behaviours, and this
is proposed to be:
The combination of all of these allow for more expressiveness with
more explicitness for clarity.
Please note that it is probably recommended that the normal
attribute for all tags (which currently is called
name and is being
renamed for clarification) should perform name lookup by default,
which is in direct opposition to all other attributes, which are by
default literals. This is because that is the 90% use case of that
attribute, and any other situation could needlessly encumber users.
Change to the Requirements of DTML Code
One of the most difficult things that arises when working to maintain
someone else's code that was written perhaps several months prior, is
that there are many short-cuts in DTML which at first blush seem an
advantage, but when in maintenance mode quickly become a nightmare.
The following changes are proposed in order to clean up this
situatioin. In addition, this brings DTML more in line with SGML
No implicit attributes. This means that you can no longer say
<dtml-var foo>, you must now say it in the full
No quote significance. No longer will the use of quotes have
anything to do with the expression syntax notation.
Trailing slashes will be allowed. This allows one to write
reasonably well formed XMLishx code, most especially XHTML, which
would potentially increase the number of parsers.
Transition and Backward Compatibility
This proposal introduces a couple of backward incompatibilities that
provide for cleaner code in the long run, but will need a transition
time in the interim. The proposed incompatibilities are:
<dtml-var name=""> would no longer work, and would be
replaced by the more explicit
<dtml-var expr=""> would cease to function, and would be
replaced by the more explicit
Tags with implicit attributes would be forbidden, this means that
you could no longer write
<dtml-var foo>, but would instead
have to write the full form of
Expression syntax shortcuts would be eliminated, so you could no
longer use quoting (
"") to signify expressions, it would have to
be explicitly stated in the above specified options.
All tags which currently use the "separate attribute" method of
notation would have those separate tags deprecated and eventually
This would break a large amount of code in the near term, so it is
proposed that the following be done:
Provide support for "as-built" systems for 1-2 more releases
Provide a utility that can fix most (if not all) issues in
existing DTML by scanning through the object database and fixing
them, and pointing out those it can not fix, but can detect.
This provides for a solution which allows for a more gradual
There will be some small percentage of tags which will not be
"auto-fixable" and that will be the major risk.
Backlash in the community against more verbose specification. This
is mitigated by the improved parsability of tags.
This project is focused on improving Zope simplicity by providing a
consistent and uniform interface to a relatively complex existing
New DTML engine that provides the specified behaviour
Modified tag implementations, simplified wherever possible, and all
code marked as deprecated where appropriate
Transition guide that explains how to convert code and use the
Updated DTML reference documentation with many examples that show the
power and flexibility of the new interface.
Updated stock DTML code that is distributed with Zope to be fully
in compliance with this. This is the first DTML many people see, it
should be flawless.
This section covers revisions to documents and what those revisions
encompassed. It does not discuss exact changes.
Updated to reflect comments receieved as of that date.
Clarified some points, updated to discuss quoting and format attributes
a bit more.