Log of /PEAK/src/peak/web/templates.py

Parent Directory

No default branch
Bookmark a link to HEAD: (view) (download) (as text)

Fix page templates sending unicode content-type header, as reported by
Alexander Smishlajev.

The old 'peak.security' implementation has been removed, and replaced with
a simpler, more flexible implementation based on generic functions (using
less than half the code and seven fewer interfaces).  Complete docs
and API tests for the new implementation can be found in 'rules.txt' in
the 'peak.security' package directory.

(Note: as a side-effect of this change, the old 'security.IInteraction'
interface and 'security.Interaction' class can now be temporarily found
as 'web.IInteraction' and 'web.Interaction' respectively.  Both will soon
be refactored out of existence, however, so please update your code
accordingly!)

Also, the new implemetation does not require redundant
'security.allow(security.Anybody)' declarations just because you've
declared other permissions for a class, so these declarations have been
removed from ``peak.web``.  They don't do any harm, however, so you can
leave them in your own code as long as you change them to use
'binding.metadata()' instead of the deprecated 'security.allow()'.

Deprecated 'security.allow()'; please use 'binding.metadata()' instead.

Added ':uses', ':unless', and ':expects' attributes to PWT.

Implemented 'with:content-type="whatever"', 'this:is="page"',
'with:fragment-layout="layoutpath"', etc., as described in:

  http://www.eby-sarna.com/pipermail/peak/2004-October/001835.html

Note that this means existing PWT pages will no longer function as web
pages unless you add 'with:page-layout="/default"' or 'this:is="page"' to
the top-level element.  You can use the shorter form if you don't need any
text outside the top-level element (such as whitespace, <!DOCTYPE, a DTD
fragment, or the <?xml PI).  Otherwise, you should use the longer
'with:page-layout="/default"' form, which means, "use the whole file as
a page.  The intended tradeoff is to favor page fragments over full pages,
pushing most HTML details into one or more page layouts.  But, it's not
clear just yet if this is the right thing to do, so this decision could
be reversed or tweaked later.

Implemented 'with:name="value"' parameter passing for PWT, with lazy path
evaluation, and binding of ':is' parameters such that they keep the context
of the calling template.

Major functionality upgrades for peak.web:

* Added 'sitemap' reference type, to allow launching an application with
  'ref:sitemap@file:/wherever.xml'

* Added parameter validation for DOMlets, including single vs. multi-value
  parameters

* Fix a problem with '++id++' lookups generating an error with an invalid
  context if the lookup failed

* Expanded IDOMletState interface to allow for variables such as 'params',
  and to allow decorating traversal context with those variables

* Fix items found in Location containers from having their '..' reference
  the container, instead of the Location

* Added integration tests to run a simple "site" with a sitemap, views,
  templates, and so on.

* Added '<location configure="iniURL">'

* Allow ':replace' and ':xml' DOMlets to invoke views implemented as
  DOMlets, and pass parameters to them

Got rid of TemplateResource and DOMletAsHTTP, folding them directly into
TemplateDocument, which will need to handle its own HTTP directly in the
future, not to mention its own context munging.  Also, made it easy to
use subclasses of TemplateDocument as resources, where previously you had
to also sublcass TemplateResource.

Move from absolute to relative URLs:

* Added 'web.relativeURL(base,url)' to compute relative URLs

* Added 'url' attribute to 'web.ITraversalContext' to supply the canonical
  relative URL (or absolute URL if it can't be made relative)

* PWT 'url' operations use the new 'url' attribute

Also, slightly simplified PWT parse algorithm .

Misc. peak.web refactorings/cleanups: traversing to '/' with a
TraversalPath (e.g. in PWT templates) traverses to the context object
itself, allowing you access to absoluteURL, relativeURL, environ, and many
other items.  Attribute traversal now pretends an attribute doesn't exist
if it has no security declaration, instead of raising NotAllowed.  This
makes it easier to e.g. bypass attributes with views of the same name.
'IWebTraversable.preTraverse()' has been renamed to 'beforeHTTP()', to help
clarify its limited role.  Removed the 'root' attribute from 'IPolicyInfo'
and friends, as it was no longer used by anything.  (Use the 'app'
attribute instead, if you were using it.)

PWT Reloaded, Part 1.  Implemented most of the features described at:

 http://www.eby-sarna.com/pipermail/peak/2004-August/001713.html

except for the 'with:' namespace and ':on-error' attributes.  Also, I
discovered (and recorded in pwt.__doc__) a couple of minor open issues
with the current design.

Refactor 'peak.web.templates' to use the negotiating XML parser.  This is a
first step towards "PWT Reloaded", although this refactoring doesn't add
any new functionality, and shouldn't have changed the old functionality.

Port all of PEAK's internal and example apps from IRerunnableCGI to
IWSGIApplication, and add a new 'WSGI' command wrapper that lets you run
non-PEAK WSGI applications in PEAK's containers.  For the time being, we're
keeping IRerunnableCGI around, however, because it's a more natural
interface for the CGI/FastCGI containers to use.  See CHANGES.txt for more
details on these issues.  Also, fixed an issue with templates outputting
Unicode instead of ASCII (which is all they really support at the moment.)

Folded more of the 'peak.web' API into the ITraversalContext interface.
Added a new 'ctx.clone()' API for easy creation of new contexts with
altered settings (e.g. for '++skin++' and '++setuid++' support).  Fixed
some broken headers that didn't comply with PEP 333.  Reduced
environ-munging to an absolute minimum.  This is still just an interim
stage of refactoring; much more breakage is yet to come.

Initial refactoring of 'peak.web' to align its internal interfaces with
PEP 333, and to support extensible namespace traversal (as described in:
http://www.eby-sarna.com/pipermail/peak/2004-August/001712.html ).  Also,
added unit tests for new functionality and some refactored functionality.

This refactoring will almost certainly break any non-trivial peak.web
application: that is, any application that publishes callables or defines
any 'handle_http()' or 'traverseTo()' methods.  Even if your app works,
there may be more breakage soon when the traversal mechanism itself gets
refactored, and even more when the template system gets refactored.

Change SOX to do a literal pass-through of any unrecognized text such as
&nbsp;, &raquo;, <!DOCTYPE> declarations, etc.  Fix typos in SOX and
peak.web.templates, and adjust tests since literal pass-thru now includes
top-level whitespace following the document-level tag.

Change all adapter factories to use only a single argument.

The 'config.iterParents' API has moved to 'binding.iterParents', and all
'binding' functions that walk the component hierarchy use it.  It has also
been changed to avoid infinite loops in the case of a pathological
component structure.

Slight adjustments to 'SOX.IXMLBuilder' interface: give all methods an
'_xml_' prefix to avoid naming conflicts, and pass the parser as a
parameter to possibly support getting file/line/column info in the future.
(XXX There really should be an 'IXMLParser' added to define the parser
interface.)

Make SOX and p.w.t use the same expat-based XML processor, as a prelude to
adding XML configuration/serialization.  See 'CHANGES.txt' for impact
details.

Massive refactoring of 'peak.web' to remove all Zope dependencies.  See
'CHANGES.txt' for details.  Note that this is only the beginning of the
refactoring, so please promptly report any problems you may find!  That
way, I hopefully won't get too far ahead, building on anything that might
be broken.

Minor 'peak.web' enhancements, to better support the "app as resource dirs"
paradigm, as described in:

http://www.eby-sarna.com/pipermail/peak/2004-January/001166.html

Except that this is to support creating DDT document directories that are
web-publishable.  The main changes are to make resources traversable-to,
add a 'basename' attribute for filesystem resources (base filename, ala
Zope's 'id'), and add 'header' and 'footer' options to the 'list' DOMlet.

Working with this a bit has shown me that nameless security checks (i.e.
'interaction.allows(ob)') need a bit of work.  We should probably assume
that access to an object as a collection member is safe unless declared
otherwise, since the use case is to allow application objects to exclude
themselves from appearing in a collection.  But that'll need to change in
'peak.security', not 'peak.web'.

Also, traversal implementations are starting to proliferate, and probably
need a mini-framework added to pull them back together.

Fixed 'text' DOMlet not XML-quoting output.  Added 'xml' DOMlet for
outputting already-quoted output.  Added 'notag', 'text.notag', and
'xml.notag' variants that throw away their opening/closing tags.  'notag'
does nothing except throw away the open/close tags, which is useful when
'pwt:define'-ing a block that has multiple elements in it, among other
things.  With 'text.notag' or 'xml.notag', you can now embed text in other
text without needing to keep the "span" in the output.

Removed all uses of deprecated binding APIs.

Converted 'return NOT_ALLOWED/NOT_FOUND' -> 'raise NotAllowed/NotFound', as
per:

   http://www.eby-sarna.com/pipermail/transwarp/2003-August/000678.html

Also, fixed some bugs in the previous handling of these conditions, and
added a 'traversedName' attribute to 'WebException' so that templates can
render what name was being looked up when traversal failed.

Added 'url.*' family of DOMlets.  'url.foo' causes the tag's 'foo'
attribute to be replaced with the absolute URL of the current traversal
location.  'url.foo+bar' caused the attribute 'foo:bar' to be replaced.
'url' alone replaces the contents of the tag, and 'url.notag' replaces
the entire element with just the URL.  (The spelling for these latter
behaviors may get tweaked a bit.)  Testing this shook a few typos and other
bugs out of the woodwork.  Also, this gives an example of how to create
a DOMlet factory that isn't a class, but a function that decides what class
to create.

Draft implementation of error handling system for not found/allowed, etc.
Still need to create a default error template, though.

More cleanup/refactoring of URL handling and traversables/contexts:

- Most 'ITraversalContext' services are now available as attributes,
  rather than methods.

- Solidified the concept of a resource to include a fixed
  'resourcePath', and the ability of an interaction to determine a
  resource's URL.  Removed the need for traversables in general to
  know their location; this is a resource-specific matter.  It's now
  a cinch to turn a traversal context into the most-useful possible
  URL for the traversed-to item.

- Created a separate class for the root of a traversal, which makes it
  easier to start a traversal and allowed some conditionals in the
  TraversalContext class to be removed.

What we probably need to do next, is spruce up NOT_FOUND/NOT_ALLOWED
handling (which is rather broken right now).  Adding some tests for
resource  retrieval and URL computation would be a good idea too.

Factor out some traversable responsibilities into a new interface:
ITraversalContext.  Now, the interaction deals only with traversal
contexts, and the traversal context is responsible for most of the
housekeeping associated with traversal and rendering.  Traversables no
longer need to be bound to an interaction-based context, or deal with
adapting objects found in traversal.  This also simplifies some of the
traversal mechanics for templates as well.  Pages' 'render()' method now
takes a traversal context instead of an interaction.  The main areas of
confusion remaining now are with respect to URL computation and resource
bindings.  Some of the other interfaces and implementations still need
review and possible tuning.  It may be that there is a lot of unnecessary
overhead still being managed by traversables to keep track of a URL or
context information that isn't really needed anymore.

Lots of peak.web enhancements for resources and templates:

- Added 'web.bindResource("name")'.

- Documented IWebTraversable.preTraverse() better.

- Made IWebTraversable.getObject() take the interaction as a parameter;
  this is ugly but was necessary in order to get bindResource to work.

- Added TestInteraction.simpleTraverse(), to minimize duplicated code in
  interaction-driven tests.

- Made interactions deal in lists of objects traversed so far, rather
  than keeping only the last object.  This was needed so that resources
  used as methods can be bound to their context (the object whose method
  they are) rather than their container (a layer of the skin).  This is
  also ugly but necessary.  :(

- Added caching to ResourceDirectory and Skin, to prevent repeated
  object creation and retrievals.

- Created 'TemplateResource', so you can 'bindResource()' to peak.web
  template files.  Made '.pwt' file extension map to 'TemplateResource'.

At this point, it's clear to me that the traversal mechanisms used by
'peak.web' are ugly as sin and need critical review.  It is *very*
hard to reason clearly about what traversal components do, in part
because they may or may not be decorators over some "real" object.

Skins and Resources further complicate matters by possibly having
different parents, or mixing MultiTraversers into the mix.  Right
now, things seem to work okay, but I'd feel more comfortable if I
could predict/visualize *how* they work.  I keep finding things not
working as I expect, and although I'm able to understand how they
actually work long enough to make them do what I want, I forget soon
afterwards because it's just too darn complicated!

On the bright side, we now have the minimum required functionality, so
perhaps we can now understand the detailed requirements enough to be
able to refactor the implementation appropriately.

Many peak.web enhancements and fixes:

Added 'resourcePrefix' property/attribute to manage coming
/++resources++ support

Added 'IWebTraversable.getAbsoluteURL()' method, w/default
implementations

Rename SimpleTraversable -> Traversable and ComponentAsTraversable ->
Decorator

Added ability for Decorator subclasses to overlay their own attributes
(e.g. web pages) onto their subjects

Added experimental 'MultiTraverser' that simultaneously traverses a
sequence of other traversables, returning another multi-traverser that
contains all the children of the wrapped traversables.

Added experimental 'Skin' class that serves as a traversal root, and in
future will support access to resources.  The NullSkinService now
actually instantiates a Skin, and Interaction uses its skin as a
traversal root.

Changed "default method" traversal to check whether the default method
actually exists, so as not to cause spurious "not found" errors in that
case.

Changed Interaction's page.render() handling so that if the subject
of a request doesn't support IWebPage, it's simply returned as-is.
This allows simple attribute values (e.g. strings, numbers,
dictionaries, etc.) to be rendered as strings.

Fixed 'List' DOMlet not informing list items of their parent traversable.

Location terminology changes, also made 'interaction.callObject()' suggest
the *parent* of the traversable where the page was found, as the parent of
the page.  This seems to make more sense than making it a child of its own
traversal adapter, and removed a bit of kludginess from the DOMlet->webpage
adapter.

Added 'findState()' method missed in last checkin.

Refactored DOMlet execution to use 'IDOMletState' interface, as per
http://www.eby-sarna.com/pipermail/transwarp/2003-July/000634.html

Rename/refactor from model/view/pattern to domlet/define.  Fixed broken
XML namespace support.  (Expat doesn't give you namespace events unless you
also have it skip xmlns: attributes, which doesn't work for us because we
need to reproduce the input document as closely as possible.)  Added
another unit test, which is what caught the xmlns problem.  RenderTo()
signature still needs review.  (And not just because it still includes a
'currentModel' parameter!)

The templates have landed!  We can parse and render templates, and use them
as web methods on locations.  There's even a (yes, just one) unit test.
Big TODO lists both in the package and its test suite, but at least it's
working.  Made minor adjustments to publishing algorithms so that locations
know their parent locations, and methods know the location that they were
found in. Bumped package version to 0.5a3, since we've been in the alpha 3
cycle for a while now.

Drafted rough equivalents to "var" and "in".  Refactored model and
publishing traverals to use a name class (LocationPath) that knows how to
do traversal.  Moved Zope request subclasses to a separate module, so that
you don't have to have Zope installed just to use templates (important for
testing!).  Made 'peak.naming' name classes (compound/composite and any
derivative thereof) support 'adapt(stringOrUnicode,nameClass)' by parsing.

Initial draft implementations of basic template node/element types.  We
should be able to create some tests around these and get them debugged,
even before we create a parser.