Z Object Publishing Environment

Search | Download | Documentation | Resources | Members

Search  

 

 Guest

Join Zope.org
Log in


Developer Home
Get Involved!
The Fishbowl
Resources
Proposals
Projects


 Zope Exits

ZopeZen
Zope Newbies
Appwatch.com


page served by app2

Proposals Table of Contents Last edited on Jan 20, 2001 4:33 pm
zope_fish.jpg

DTMLExpressionSyntax Proposal

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.

Contact

Chris Petrilli (petrilli@digicool.com)

Problem

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:

  • Different attributes for literals and expressions

  • Differentiation based on the use of quoting semantics

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
                        provided.

                        - '<...  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 to differentiate name and 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:

  • <dtml-foo x=bar>

  • <dtml-foo x="bar">

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.

Proposed Solution

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 notation of:

  • <dtml-TAGNAME ATTRIBUTE-FORMATx="VALUE">

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 FORMAT that will be supported will be expr, which will be give you the following example tag:

                                <dtml-var value-python="foo">

which would be equivelent to the current DTML notation of:

                                <dtml-var expr="foo">

The first thing you will notice is that we use the value attribute, 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 evaluation.

In the future, potential other formatting options would be:

  • -perl: providing a Perl expression access at the DTML level

  • -xslt: providing access to XSL transform operations

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:

  • -literal: noting that this is a literal to be passed directly

  • -name: noting that the string passed is to be looked up in the namespace and its value used.

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 value 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 requirements.

  • No implicit attributes. This means that you can no longer say things like <dtml-var foo>, you must now say it in the full form of <dtml-var name="foo">.

  • 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 value="">.

  • <dtml-var expr=""> would cease to function, and would be replaced by the more explicit <dtml-var value-python="">.

  • 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 <dtml-var name="foo">.

  • 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 removed.

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 transition.

Risk Factors

  • 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.

Scope

This project is focused on improving Zope simplicity by providing a consistent and uniform interface to a relatively complex existing problem.

Deliverables

  • 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 provided utilities

  • 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.

Document Revisions

This section covers revisions to documents and what those revisions encompassed. It does not discuss exact changes.

2000/9/29

Updated to reflect comments receieved as of that date. Clarified some points, updated to discuss quoting and format attributes a bit more.

View source DTMLExpressionSyntax
Advanced Actions / History
Visitor: Anonymous User
Jump to:
... by pagename prefix or search term.
For a plain search:
SearchPage
 
 
Privacy policy       Printable Page       Feedback about Zope.org