[Checkins] SVN: z3c.pt/trunk/docs/ Updated documentation; the sections on TAL, I18N and METAL have been moved to the 'chameleon.zpt' documentation, while the present documentation instead details what's new in 'z3c.pt'.
Malthe Borch
mborch at gmail.com
Fri Mar 6 15:02:22 EST 2009
Log message for revision 97602:
Updated documentation; the sections on TAL, I18N and METAL have been moved to the 'chameleon.zpt' documentation, while the present documentation instead details what's new in 'z3c.pt'.
Changed:
U z3c.pt/trunk/docs/api.rst
U z3c.pt/trunk/docs/conf.py
U z3c.pt/trunk/docs/index.rst
U z3c.pt/trunk/docs/narr/i18n.rst
D z3c.pt/trunk/docs/narr/metal.rst
D z3c.pt/trunk/docs/narr/refimpls.rst
D z3c.pt/trunk/docs/narr/tal.rst
U z3c.pt/trunk/docs/narr/tales.rst
-=-
Modified: z3c.pt/trunk/docs/api.rst
===================================================================
--- z3c.pt/trunk/docs/api.rst 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/api.rst 2009-03-06 20:02:22 UTC (rev 97602)
@@ -1,19 +1,35 @@
.. _pagetemplate_api_module:
-:mod:`z3c.pt`
+:mod:`z3c.pt.pagetemplate`
--------------------------
``PageTemplate*`` constructors create templates from XML
-files. ``TextTemplate*`` constructors create templates from plaintext
files.
-.. automodule:: z3c.pt
+.. automodule:: z3c.pt.pagetemplate
.. autoclass:: PageTemplate
.. autoclass:: PageTemplateFile
+:mod:`z3c.pt.texttemplate`
+--------------------------
+
+``TextTemplate*`` constructors create templates from plaintext
+files.
+
+.. automodule:: z3c.pt.texttemplate
+
.. autoclass:: TextTemplate
.. autoclass:: TextTemplateFile
+:mod:`z3c.pt.loader`
+--------------------------
+
+A template loader class is provided (for use with Pylons and other
+platforms).
+
+.. automodule:: z3c.pt.loader
+
+ .. autoclass:: TemplateLoader
\ No newline at end of file
Modified: z3c.pt/trunk/docs/conf.py
===================================================================
--- z3c.pt/trunk/docs/conf.py 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/conf.py 2009-03-06 20:02:22 UTC (rev 97602)
@@ -31,7 +31,7 @@
# General substitutions.
project = 'z3c.pt'
-copyright = '2008 The Zope Community'
+copyright = '2007-2009 The Zope Community'
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
@@ -39,7 +39,7 @@
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
-release = '1.0dev'
+release = '1.0beta'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
Modified: z3c.pt/trunk/docs/index.rst
===================================================================
--- z3c.pt/trunk/docs/index.rst 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/index.rst 2009-03-06 20:02:22 UTC (rev 97602)
@@ -4,48 +4,28 @@
z3c.pt
======
-Python template compiler which supports the `Genshi
-<http://genshi.edgewall.org/wiki/Documentation/xml-templates.html>`_
-and `ZPT <http://wiki.zope.org/ZPT/TAL>`_ template language syntaxes
-including macro extensions and i18n internationalization.
+This package provides a fast implementation of the Zope Page Templates (ZPT) language which aims to be fully compatible with the reference implementation. The template engine is based on Chameleon.
-The compiler is developed by Malthe Borch and other contributors as
-part of the `Zope <http://zope.org>`_ project. It is written and
-distributed under the `ZPL license
-<http://www.zope.org/Resources/ZPL>`_.
+.. note:: If you're looking to use Chameleon outside a Zope 2 or 3 environment, the `chameleon.zpt <http://pypi.python.org/pypi/chameleon.zpt>`_ package provides a light-weight implementation of the ZPT language.
Zope Page Templates (ZPT) is a system which can generate HTML and XML.
-ZPT is formed by the *Template Attribute Language* (*TAL*) and the
-*TAL Expression Syntax* (*TALES*), and the *Macro Expansion Template
-Attribute Language* (*METAL*).
+ZPT is formed by the *Template Attribute Language* (*TAL*), the
+*Expression Syntax* (*TALES*), *Intertionalization* (*I18N*) and the *Macro Expansion Template Attribute Language* (*METAL*).
-Genshi provides an XML-based template language that is heavily inspired
-by `Kid <http://kid-templating.org/>`_, which in turn was inspired by
-a number of existing template languages, namely XSLT, TAL, and PHP.
+The package also implementation a text-mode which supports non-structural content like JavaScript.
-:mod:`z3c.pt` provides support for both ZPT and Genshi syntax.
+Language Reference
+==================
-TAL Support Documentation
-=========================
+For a general reference, see the `documentation <http://chameleon.repoze.org/docs/zpt>`_ for the :mod:`chameleon.zpt` package. In the present reference, the language details that are specific to this implementation are described.
-Documentation related to TAL support in :mod:`z3c.pt`.
.. toctree::
:maxdepth: 2
- narr/refimpls
- narr/tal
narr/tales
- narr/metal
narr/i18n
-Genshi Support Documentation
-============================
-
-Documentation related to Genshi support in :mod:`z3c.pt`.
-
-.. warning:: Need Genshi-related documentation.
-
API documentation
=================
@@ -59,8 +39,10 @@
Support and Development
=======================
-To report bugs, use the `bug tracker <http://code.google.com/p/z3c-pt>`_.
+This package is developed and maintained by `Malthe Borch <mailto:mborch at gmail.com>`_ and the Zope Community.
+To report bugs, use the `bug tracker <https://bugs.launchpad.net/z3c.pt/>`_.
+
If you've got questions that aren't answered by this documentation,
please contact the `maillist
<http://groups.google.com/group/z3c_pt>`_.
Modified: z3c.pt/trunk/docs/narr/i18n.rst
===================================================================
--- z3c.pt/trunk/docs/narr/i18n.rst 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/narr/i18n.rst 2009-03-06 20:02:22 UTC (rev 97602)
@@ -1,262 +1,11 @@
.. _i18n_chapter:
-Internationalization via the ``i18n`` Namespace
-===============================================
+Internationalization
+====================
-:mod:`z3c.pt` provides internationalization support via the ``i18n``
-namespace and a *translation domain*.
+Language negotation
+-------------------
-Registering a Translation Domain
---------------------------------
+Unless a ``target_language`` keyword argument is passed to the render-method of the template, an attempt to negotiate the language using ``zope.i18n.negotiate`` is made.
-A translation domain object is an object with a ``translate`` method
-which accepts certain arguments. It returns a translation for the
-given msgid or the default.
-
-You may register a translation domain within your own code by using
-the Zope Component Architecture::
-
- from zope import component
- from zope import interface
-
- class MockTranslationDomain(object):
- interface.implements(ITranslationDomain)
-
- def translate(self, msgid, mapping=None, context=None,
- target_language=None, default=None):
- if target_language != 'de':
- return default
-
- return "Mock translation of '%s'." % msgid
-
- td = MockTranslationDomain()
- component.provideUtility(td, ITranslationDomain, name="test")
-
-The domain's name is used to specify which translation to use. A
-favorite example is: How do you translate 'Sun'? Is it our star, the
-abbreviation of Sunday or the company? Specifying the domain name,
-such as ``Stars`` or ``DaysOfWeek`` will make it unambiguous. The
-domain name is referred to in ``18n:translate`` tags shown below.
-
-Standard arguments in the ``translate`` method are described below::
-
- msgid -- The id of the message that should be translated. This may be
- an implicit or an explicit message id.
-
- mapping -- The object to get the interpolation data from.
-
- context -- An object that provides contextual information for
- determining client language preferences.
-
- target_language -- The language to translate to.
-
- default -- This will be returned if no translation is found.
-
-.. warning:: We need a better Mock that shows usage of ``context`` and
- ``mapping``.
-
-The ``i18n`` Namespace
-----------------------
-
-The 'i18n' namespace URI and recommended prefix are currently defined as::
-
- xmlns:i18n="http://xml.zope.org/namespaces/i18n"
-
-This is not a URL, but merely a unique identifier. Do not expect a
-browser to resolve it successfully.
-
-The Attributes
---------------
-
-The allowable ``i18n`` attributes are:
-
-- ``i18n:translate``
-- ``i18n:domain``
-- ``i18n:source``
-- ``i18n:target``
-- ``i18n:name``
-- ``i18n:attributes``
-- ``i18n:data``
-
-i18n:translate
-~~~~~~~~~~~~~~~
-
-This attribute is used to mark units of text for translation. If this
-attribute is specified with an empty string as the value, the message
-ID is computed from the content of the element bearing this attribute.
-Otherwise, the value of the element gives the message ID.
-
-i18n:domain
-~~~~~~~~~~~~
-
-The ``i18n:domain`` attribute is used to specify the domain to be used
-to get the translation. If not specified, the translation services
-will use a default domain. The value of the attribute is used
-directly; it is not a TALES expression.
-
-i18n:source
-~~~~~~~~~~~
-
-The ``i18n:source`` attribute specifies the language of the text to be
-translated. The default is ``nothing``, which means we don't provide
-this information to the translation services.
-
-
-i18n:target
-~~~~~~~~~~~
-
-The ``i18n:target`` attribute specifies the language of the
-translation we want to get. If the value is ``default``, the language
-negotiation services will be used to choose the destination language.
-If the value is ``nothing``, no translation will be performed; this
-can be used to suppress translation within a larger translated unit.
-Any other value must be a language code.
-
-The attribute value is a TALES expression; the result of evaluating
-the expression is the language code or one of the reserved values.
-
-.. note:: ``i18n:target`` is primarily used for hints to text
- extraction tools and translation teams. If you had some text that
- should only be translated to e.g. German, then it probably
- shouldn't be wrapped in an ``i18n:translate`` span.
-
-i18n:name
-~~~~~~~~~
-
-Name the content of the current element for use in interpolation
-within translated content. This allows a replaceable component in
-content to be re-ordered by translation. For example::
-
- <span i18n:translate=''>
- <span tal:replace='here/name' i18n:name='name' /> was born in
- <span tal:replace='here/country_of_birth' i18n:name='country' />.
- </span>
-
-would cause this text to be passed to the translation service::
-
- "${name} was born in ${country}."
-
-i18n:attributes
-~~~~~~~~~~~~~~~
-
-This attribute will allow us to translate attributes of HTML tags,
-such as the ``alt`` attribute in the ``img`` tag. The
-``i18n:attributes`` attribute specifies a list of attributes to be
-translated with optional message IDs for each; if multiple attribute
-names are given, they must be separated by semi-colons. Message IDs
-used in this context must not include whitespace.
-
-Note that the value of the particular attributes come either from the
-HTML attribute value itself or from the data inserted by
-``tal:attributes``.
-
-If an attibute is to be both computed using ``tal:attributes`` and
-translated, the translation service is passed the result of the TALES
-expression for that attribute.
-
-An example::
-
- <img src="http://foo.com/logo" alt="Visit us"
- tal:attributes="alt here/greeting"
- i18n:attributes="alt"
- >
-
-In this example, we let ``tal:attributes`` set the value of the ``alt``
-attribute to the text "Stop by for a visit!". This text will be
-passed to the translation service, which uses the result of language
-negotiation to translate "Stop by for a visit!" into the requested
-language. The example text in the template, "Visit us", will simply
-be discarded.
-
-Another example, with explicit message IDs::
-
- <img src="../icons/uparrow.png" alt="Up"
- i18n:attributes="src up-arrow-icon; alt up-arrow-alttext"
- >
-
-Here, the message ID ``up-arrow-icon`` will be used to generate the
-link to an icon image file, and the message ID 'up-arrow-alttext' will
-be used for the "alt" text.
-
-i18n:data
-~~~~~~~~~
-
-Since TAL always returns strings, we need a way in ZPT to translate
-objects, one of the most obvious cases being ``datetime`` objects. The
-``data`` attribute will allow us to specify such an object, and
-``i18n:translate`` will provide us with a legal format string for that
-object. If ``data`` is used, ``i18n:translate`` must be used to give
-an explicit message ID, rather than relying on a message ID computed
-from the content.
-
-Relation with TAL processing
-----------------------------
-
-The attributes defined in the ``i18n`` namespace modify the behavior
-of the TAL interpreter for the ``tal:attributes``, ``tal:content``,
-``tal:repeat``, and ``tal:replace`` attributes, but otherwise do not
-affect TAL processing.
-
-Since these attributes only affect TAL processing by causing
-translations to occur at specific times, using these with a TAL
-processor which does not support the ``i18n`` namespace degrades well;
-the structural expectations for a template which uses the ``i18n``
-support is no different from those for a page which does not. The
-only difference is that translations will not be performed in a legacy
-processor.
-
-Relation with METAL processing
--------------------------------
-
-When using translation with METAL macros, the internationalization
-context is considered part of the specific documents that page
-components are retrieved from rather than part of the combined page.
-This makes the internationalization context lexical rather than
-dynamic, making it easier for a site builder to understand the
-behavior of each element with respect to internationalization.
-
-Let's look at an example to see what this means::
-
- <html i18n:translate='' i18n:domain='EventsCalendar'
- metal:use-macro='container/master.html/macros/thismonth'>
-
- <div metal:fill-slot='additional-notes'>
- <ol tal:condition="here/notes">
- <li tal:repeat="note here/notes">
- <tal:block tal:omit-tag=""
- tal:condition="note/heading">
- <strong tal:content="note/heading">
- Note heading goes here
- </strong>
- <br />
- </tal:block>
- <span tal:replace="note/description">
- Some longer explanation for the note goes here.
- </span>
- </li>
- </ol>
- </div>
-
- </html>
-
-And the macro source::
-
- <html i18n:domain='CalendarService'>
- <div tal:replace='python:DateTime().Month()'
- i18n:translate=''>January</div>
-
- <!-- really hairy TAL code here ;-) -->
-
- <div define-slot="additional-notes">
- Place for the application to add additional notes if desired.
- </div>
-
- </html>
-
-Note that the macro is using a different domain than the application
-(which it should be). With lexical scoping, no special markup needs
-to be applied to cause the slot-filler in the application to be part
-of the same domain as the rest of the application's page components.
-If dynamic scoping were used, the internationalization context would
-need to be re-established in the slot-filler.
-
+Consult the documentation of :mod:`zope.i18n` to learn how to implement a language negotiator.
\ No newline at end of file
Deleted: z3c.pt/trunk/docs/narr/metal.rst
===================================================================
--- z3c.pt/trunk/docs/narr/metal.rst 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/narr/metal.rst 2009-03-06 20:02:22 UTC (rev 97602)
@@ -1,195 +0,0 @@
-.. _metal_chapter:
-
-Macro Expansion Template Attribute Language (METAL)
-===================================================
-
-The *Macro Expansion Template Attribute Language* (METAL) standard is
-a facility for HTML/XML macro preprocessing. It can be used in
-conjunction with or independently of TAL and TALES.
-
-Macros provide a way to define a chunk of presentation in one
-template, and share it in others, so that changes to the macro are
-immediately reflected in all of the places that share it.
-Additionally, macros are always fully expanded, even in a template's
-source text, so that the template appears very similar to its final
-rendering.
-
-A single Page Template can accomodate multiple macros.
-
-METAL Namespace
----------------
-
-The METAL namespace URI and recommended alias are currently defined
-as::
-
- xmlns:metal="http://xml.zope.org/namespaces/metal"
-
-Just like the TAL namespace URI, this URI is not attached to a web
-page; it's just a unique identifier. This identifier must be used in
-all templates which use METAL.
-
-METAL Statements
-----------------
-
-METAL defines a number of statements:
-
-* ``metal:define-macro`` Define a macro.
-* ``metal:use-macro`` Use a macro.
-* ``metal:define-slot`` Define a macro customization point.
-* ``metal:fill-slot`` Customize a macro.
-
-Although METAL does not define the syntax of expression non-terminals,
-leaving that up to the implementation, a canonical expression syntax
-for use in METAL arguments is described in TALES Specification.
-
-``define-macro``: Define a macro
---------------------------------
-
-Syntax
-~~~~~~
-
-``metal:define-macro`` syntax::
-
- argument ::= Name
-
-Description
-~~~~~~~~~~~
-
-The ``metal:define-macro`` statement defines a macro. The macro is named
-by the statement expression, and is defined as the element and its
-sub-tree.
-
-Examples
-~~~~~~~~
-
-Simple macro definition::
-
- <p metal:define-macro="copyright">
- Copyright 2004, <em>Foobar</em> Inc.
- </p>
-
-``define-slot``: Define a macro customization point
----------------------------------------------------
-
-Syntax
-~~~~~~
-
-``metal:define-slot`` syntax::
-
- argument ::= Name
-
-Description
-~~~~~~~~~~~
-
-The ``metal:define-slot`` statement defines a macro customization
-point or *slot*. When a macro is used, its slots can be replaced, in
-order to customize the macro. Slot definitions provide default content
-for the slot. You will get the default slot contents if you decide not
-to customize the macro when using it.
-
-The ``metal:define-slot`` statement must be used inside a
-``metal:define-macro`` statement.
-
-Slot names must be unique within a macro.
-
-Examples
-~~~~~~~~
-
-Simple macro with slot::
-
- <p metal:define-macro="hello">
- Hello <b metal:define-slot="name">World</b>
- </p>
-
-This example defines a macro with one slot named ``name``. When you use
-this macro you can customize the ``b`` element by filling the ``name``
-slot.
-
-``fill-slot``: Customize a macro
---------------------------------
-
-Syntax
-~~~~~~
-
-``metal:fill-slot`` syntax::
-
- argument ::= Name
-
-Description
-~~~~~~~~~~~
-
-The ``metal:fill-slot`` statement customizes a macro by replacing a
-*slot* in the macro with the statement element (and its content).
-
-The ``metal:fill-slot`` statement must be used inside a
-``metal:use-macro`` statement.
-
-Slot names must be unique within a macro.
-
-If the named slot does not exist within the macro, the slot
-contents will be silently dropped.
-
-Examples
-~~~~~~~~
-
-Given this macro::
-
- <p metal:define-macro="hello">
- Hello <b metal:define-slot="name">World</b>
- </p>
-
-You can fill the ``name`` slot like so::
-
- <p metal:use-macro="container/master.html/macros/hello">
- Hello <b metal:fill-slot="name">Kevin Bacon</b>
- </p>
-
-``use-macro``: Use a macro
---------------------------
-
-Syntax
-~~~~~~
-
-``metal:use-macro`` syntax::
-
- argument ::= expression
-
-Description
-~~~~~~~~~~~
-
-The ``metal:use-macro`` statement replaces the statement element with
-a macro. The statement expression describes a macro definition.
-
-In :mod:`zc.pt` the expression will generally be a expression
-referring to a macro defined in another template which is passed in to
-the rendering template. See ``metal:define-macro`` for more
-information.
-
-The effect of expanding a macro is to graft a subtree from another
-document (or from elsewhere in the current document) in place of the
-statement element, replacing the existing sub-tree. Parts of the
-original subtree may remain, grafted onto the new subtree, if the
-macro has *slots*. See ``metal:define-slot`` for more information. If
-the macro body uses any macros, they are expanded first.
-
-When a macro is expanded, its ``metal:define-macro`` attribute is
-replaced with the ``metal:use-macro`` attribute from the statement
-element. This makes the root of the expanded macro a valid
-``use-macro`` statement element.
-
-Examples
-~~~~~~~~
-
-Basic macro usage::
-
- <p metal:use-macro="other/macros/header"> header macro from
- defined in other.html template </p>
-
-This example refers to the ``header`` macro defined in the ``other``
-template which has been passed as a keyword argument to ``zc.pt``'s
-``render`` method. When the macro is expanded, the ``p`` element and
-its contents will be replaced by the macro.
-
-.. note:: there will still be a ``metal:use-macro`` attribute on the
- replacement element.
-
Deleted: z3c.pt/trunk/docs/narr/refimpls.rst
===================================================================
--- z3c.pt/trunk/docs/narr/refimpls.rst 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/narr/refimpls.rst 2009-03-06 20:02:22 UTC (rev 97602)
@@ -1,48 +0,0 @@
-.. _reflimpl_chapter:
-
-Relationships to Reference Implementations
-==========================================
-
-:mod:`zc3.pt` implements both TAL and Genshi syntax.
-
-The :mod:`z3c.pt` compiler is largely compatible with the targeted
-dialects. The TAL implementation is based on the `1.4 language
-specification <http://wiki.zope.org/ZPT/TALSpecification14>`_ while
-the Genshi implementation is based on the documents for the `0.5
-release <http://genshi.edgewall.org/wiki/Documentation/xml-templates.html>`_.
-
-Notable Differences from TAL 1.4
---------------------------------
-
-#. Tuple unpacking is allowed when using ``tal:define`` to define
- variables:
-
- ``tal:define="(a, b, c) [1, 2, 3]"``
-
-#. Generators are allowed in ``tal:repeat`` statements. Note that the
- repeat variable is not available in this case
-
- ``tal:repeat="i <some generator>"``
-
-#. Attribute-access to dictionary entries is allowed in
- Python-expressions, e.g.
-
- ``dictionary.key``
-
- can be used instead of ``dictionary['key']``.
-
-#. The default expression type for a template can be set using the
- ``tal:default-expression`` attribute on an element. This is an
- alternative to providing the expression type before each
- expression.
-
-#. The ``global`` modifier for ``tal:define`` is not implemented.
-
-#. The ``tal:on-error`` statement is not implemented.
-
-Notable Differences from Genshi 0.5
------------------------------------
-
-#. The XPath select function provided to py:match-elements requires
- lxml and requires the use of the default namespace prefix "xmlns".
-
Deleted: z3c.pt/trunk/docs/narr/tal.rst
===================================================================
--- z3c.pt/trunk/docs/narr/tal.rst 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/narr/tal.rst 2009-03-06 20:02:22 UTC (rev 97602)
@@ -1,561 +0,0 @@
-.. _tal_chapter:
-
-Template Attribute Language (TAL)
-=================================
-
-The *Template Attribute Language* (TAL) is an attribute language used
-to create dynamic XML-like content. It allows elements of a document
-to be replaced, repeated, or omitted.
-
-An attribute language is a programming language designed to render
-documents written in XML markup. The input XML must be well-formed.
-The output from the template is usually XML-like but isn't required to
-be well-formed.
-
-The statements of the language are document tags with special
-attributes, and look like this::
-
- <p namespace:command="argument">Some Text</p>
-
-In the above example, the attribute ``namespace:command="argument"``
-is the statement, and the entire paragraph tag is the statement's
-element. The statement's element is the portion of the document on
-which this statement operates.
-
-Each statement has three parts: the namespace prefix, the name, and
-the argument. The prefix identifies the language, and must be
-introduced by an XML namespace declaration in XML and XHTML documents,
-like this::
-
- xmlns:namespace="http://example.com/namespace"
-
-The statements of TAL are XML attributes from the TAL namespace.
-These attributes can be applied to an XML or HTML document in order to
-make it act as a template.
-
-The TAL namespace URI is currently defined as::
-
- xmlns:tal="http://xml.zope.org/namespaces/tal"
-
-This is not a URL, but merely a unique identifier. Do not expect a
-browser to resolve it successfully. This definition is required in
-every file that uses ZPT. For example::
-
- <div xmlns="http://www.w3.org/1999/xhtml"
- xmlns:tal="http://xml.zope.org/namespaces/tal">
- .... rest of the template here ...
- </div>
-
-All templates that you use ZPT in *must* include the
-``xmlns:tal="http://xml.zope.org/namespaces/tal"`` attribute on some
-top-level tag.
-
-TAL Statements
---------------
-
-A **TAL statement** has a name (the attribute name) and an argument
-(the attribute value). For example, a ``tal:content`` statement might
-look like ``tal:content="string:Hello"``. The element on which a
-statement is defined is its **statement element**. Most TAL
-statements are *expressions*, but the syntax and semantics of these
-expressions are not part of TAL.
-
-.. note:: *TALES* is used as the expression language for the "stuff in
- the quotes" typically. TALES is documented separately.
-
-These are the available TAL statements:
-
-- ``tal:attributes`` - dynamically change element attributes.
-
-- ``tal:define`` - define variables.
-
-- ``tal:condition`` - test conditions.
-
-- ``tal:content`` - replace the content of an element.
-
-- ``tal:omit-tag`` - remove an element, leaving the content of the
- element.
-
-- ``tal:repeat`` - repeat an element.
-
-- ``tal:replace`` - replace the content of an element and remove the
- element leaving the content.
-
-- ``tal:default-expression`` - set the default expression type for a
- block of tags.
-
-.. warning:: The reference implementation of ZPT has an additonal command
- ``tal:on-error`` which :mod:`z3c.pt` does not implement.
-
-Order of Operations
--------------------
-
-When there is only one TAL statement per element, the order in which
-they are executed is simple. Starting with the root element, each
-element's statements are executed, then each of its child elements is
-visited, in order, to do the same.
-
-Any combination of statements may appear on the same element, except
-that the ``tal:content`` and ``tal:replace`` statements may not be
-used on the same element.
-
-TAL does not use use the order in which statements are written in the
-tag to determine the order in which they are executed. When an
-element has multiple statements, they are executed in this order:
-
-#. ``tal:define``
-
-#. ``tal:condition``
-
-#. ``tal:repeat``
-
-#. ``tal:content`` or ``tal:replace``
-
-#. ``tal:attributes``
-
-#. ``tal:omit-tag``
-
-There is a reasoning behind this ordering. Because users often want
-to set up variables for use in other statements contained within this
-element or subelements, ``tal:define`` is executed first.
-``tal:condition`` follows, then ``tal:repeat`` , then ``tal:content``
-or ``tal:replace``. It makes no sense to replace attributes and then
-throw them away, so ``tal:attributes`` happens next. Finally
-``tal:omit-tag`` happens.
-
-``tal:attributes``: Replace element attributes
-----------------------------------------------
-
-Syntax
-~~~~~~
-
-``tal:attributes`` syntax::
-
- argument ::= attribute_statement [';' attribute_statement]*
- attribute_statement ::= attribute_name expression
- attribute_name ::= [namespace-prefix ':'] Name
- namespace-prefix ::= Name
-
-.. warning:: The reference implementation of ZPT requires you to escape the semi-colon (;) literal by doubling it (``;;``). With :mod:`z3c.pt` this is only required when using the ``string`` expression and will result in the literal being printed twice otherwise.
-
-Description
-~~~~~~~~~~~
-
-The ``tal:attributes`` statement replaces the value of an attribute
-(or creates an attribute) with a dynamic value. The
-value of each expression is converted to a string, if necessary.
-
-.. note:: You can qualify an attribute name with a namespace prefix,
- for example ``html:table``, if you are generating an XML document
- with multiple namespaces.
-
-The expression language defines a value named ``nothing`` that is not
-a string. In particular, this value is useful for deleting elements
-or attributes. If the expression associated with an attribute
-assignment evaluates to ``nothing``, then that attribute is deleted
-from the statement element. If the expression evaluates to
-``default``, then the attribute is left unchanged. Each attribute
-assignment is independent, so attributes may be assigned in the same
-statement in which some attributes are deleted and others are left
-alone.
-
-If you use ``tal:attributes`` on an element with an active
-``tal:replace`` command, the ``tal:attributes`` statement is ignored.
-
-If you use ``tal:attributes`` on an element with a ``tal:repeat``
-statement, the replacement is made on each repetition of the element,
-and the replacement expression is evaluated fresh for each repetition.
-
-Examples
-~~~~~~~~
-
-Replacing a link::
-
- <a href="/sample/link.html"
- tal:attributes="href context.url()">
-
-Replacing two attributes::
-
- <textarea rows="80" cols="20"
- tal:attributes="rows request.rows();cols request.cols()">
-
-``tal:condition``: Conditionally insert or remove an element
-------------------------------------------------------------
-
-Syntax
-~~~~~~
-
-``tal:condition`` syntax::
-
- argument ::= expression
-
-Description
-~~~~~~~~~~~
-
- The ``tal:condition`` statement includes the statement element in the
- template only if the condition is met, and omits it otherwise. If
- its expression evaluates to a *true* value, then normal processing of
- the element continues, otherwise the statement element is immediately
- removed from the template. For these purposes, the value ``nothing``
- is false, and ``default`` has the same effect as returning a true
- value.
-
-.. note:: Like Python itself, ZPT considers None, zero, empty strings,
- empty sequences, empty dictionaries, and instances which return a
- nonzero value from ``__len__`` or ``__nonzero__`` false; all other
- values are true, including ``default``.
-
-Examples
-~~~~~~~~
-
-Test a variable before inserting it (the first example tests for
-existence and truth, while the second only tests for existence)::
-
- <p tal:condition="request.message|nothing"
- tal:content="request.message">message goes here</p>
-
- <p tal:condition="exists:request/message"
- tal:content="request.message">message goes here</p>
-
-Test for alternate conditions::
-
- <div tal:repeat="item range(10)">
- <p tal:condition="path:repeat/item/even">Even</p>
- <p tal:condition="path:repeat/item/odd">Odd</p>
- </div>
-
-``tal:content``: Replace the content of an element
---------------------------------------------------
-
-Syntax
-~~~~~~
-
-``tal:content`` syntax::
-
- argument ::= (['text'] | 'structure') expression
-
-Description
-~~~~~~~~~~~
-
-Rather than replacing an entire element, you can insert text or
-structure in place of its children with the ``tal:content`` statement.
-The statement argument is exactly like that of ``tal:replace``, and is
-interpreted in the same fashion. If the expression evaluates to
-``nothing``, the statement element is left childless. If the
-expression evaluates to ``default``, then the element's contents are
-unchanged.
-
-The default replacement behavior is ``text``, which replaces
-angle-brackets and ampersands with their HTML entity equivalents. The
-``structure`` keyword passes the replacement text through unchanged,
-allowing HTML/XML markup to be inserted. This can break your page if
-the text contains unanticipated markup (eg. text submitted via a web
-form), which is the reason that it is not the default.
-
-Examples
-~~~~~~~~
-
-Inserting the user name::
-
- <p tal:content="user.getUserName()">Fred Farkas</p>
-
-Inserting HTML/XML::
-
- <p tal:content="structure context.getStory()">marked <b>up</b>
- content goes here.</p>
-
-``tal:define``: Define variables
---------------------------------
-
-Syntax
-~~~~~~
-
-``tal:define`` syntax::
-
- argument ::= attribute_statement [';' attribute_statement]*
- attribute_statement ::= variable_name expression
- variable_name ::= Name
-
-.. warning:: The reference implementation of ZPT requires you to escape the semi-colon (;) literal by doubling it (``;;``). With :mod:`z3c.pt` this is only required when using the ``string`` expression and will result in the literal being printed twice otherwise.
-
-Description
-~~~~~~~~~~~
-
-The ``tal:define`` statement defines variables. When you define a
-local variable in a statement element, you can use that variable in
-that element and the elements it contains. If you redefine a variable
-in a contained element, the new definition hides the outer element's
-definition within the inner element.
-
-.. warning:: The reference implementation of ZPT allows "global"
- (full-template-scope) variable definitions. :mod:`z3c.pt` does not
- have such a concept.
-
-If the expression associated with a variable evaluates to ``nothing``,
-then that variable has the value ``nothing``, and may be used as such
-in further expressions. Likewise, if the expression evaluates to
-``default``, then the variable has the value ``default``, and may be
-used as such in further expressions.
-
-Examples
-~~~~~~~~
-
-Defining a variable::
-
- tal:define="company_name 'Zope Corp, Inc.'"
-
-Defining two variables, where the second depends on the first::
-
- tal:define="mytitle context.title; tlen len(mytitle)"
-
-``tal:omit-tag``: Remove an element, leaving its contents
----------------------------------------------------------
-
-Syntax
-~~~~~~
-
-``tal:omit-tag`` syntax::
-
- argument ::= [ expression ]
-
-Description
-~~~~~~~~~~~
-
-The ``tal:omit-tag`` statement leaves the contents of an element in
-place while omitting the surrounding start and end tags.
-
-If the expression evaluates to a *false* value, then normal processing
-of the element continues and the tags are not omitted. If the
-expression evaluates to a *true* value, or no expression is provided,
-the statement element is replaced with its contents.
-
-.. note:: Like Python itself, ZPT considers None, zero, empty strings,
- empty sequences, empty dictionaries, and instances which return a
- nonzero value from ``__len__`` or ``__nonzero__`` false; all other
- values are true, including ``default``.
-
-Examples
-~~~~~~~~
-
-Unconditionally omitting a tag::
-
- <div tal:omit-tag="" comment="This tag will be removed">
- <i>...but this text will remain.</i>
- </div>
-
-Conditionally omitting a tag::
-
- <b tal:omit-tag="not:bold">I may be bold.</b>
-
-The above example will omit the ``b`` tag if the variable ``bold`` is false.
-
-Creating ten paragraph tags, with no enclosing tag::
-
- <span tal:repeat="n range(10)"
- tal:omit-tag="">
- <p tal:content="n">1</p>
- </span>
-
-.. _tal_repeat:
-
-``tal:repeat``: Repeat an element
----------------------------------
-
-Syntax
-~~~~~~
-
-``tal:repeat`` syntax::
-
- argument ::= variable_name expression
- variable_name ::= Name
-
-Description
-~~~~~~~~~~~
-
-The ``tal:repeat`` statement replicates a sub-tree of your document
-once for each item in a sequence. The expression should evaluate to a
-sequence. If the sequence is empty, then the statement element is
-deleted, otherwise it is repeated for each value in the sequence. If
-the expression is ``default``, then the element is left unchanged, and
-no new variables are defined.
-
-The ``variable_name`` is used to define a local variable and a repeat
-variable. For each repetition, the local variable is set to the
-current sequence element, and the repeat variable is set to an
-iteration object.
-
-Repeat Variables
-~~~~~~~~~~~~~~~~~
-
-You use repeat variables to access information about the current
-repetition (such as the repeat index). The repeat variable has the
-same name as the local variable, but is only accessible through the
-built-in variable named ``repeat``.
-
-The following information is available from the repeat variable:
-
-- ``index`` - repetition number, starting from zero.
-
-- ``number`` - repetition number, starting from one.
-
-- ``even`` - true for even-indexed repetitions (0, 2, 4, ...).
-
-- ``odd`` - true for odd-indexed repetitions (1, 3, 5, ...).
-
-- ``start`` - true for the starting repetition (index 0).
-
-- ``end`` - true for the ending, or final, repetition.
-
-- ``first`` - true for the first item in a group - see note below
-
-- ``last`` - true for the last item in a group - see note below
-
-- ``length`` - length of the sequence, which will be the total number
- of repetitions.
-
-- ``letter`` - repetition number as a lower-case letter: "a" - "z",
- "aa" - "az", "ba" - "bz", ..., "za" - "zz", "aaa" - "aaz", and so
- forth.
-
-- ``Letter`` - upper-case version of *letter*.
-
-- ``roman`` - repetition number as a lower-case roman numeral:
- "i", "ii", "iii", "iv", "v", etc.
-
-- ``Roman`` - upper-case version of *roman*.
-
-You can access the contents of the repeat variable using path
-expressions or Python expressions. In path expressions, you write a
-three-part path consisting of the name ``repeat``, the statement
-variable's name, and the name of the information you want, for
-example, ``repeat/item/start``. In Python expressions, you use normal
-dictionary notation to get the repeat variable, then attribute access
-to get the information, for example, ``python:repeat['item'].start``.
-
-With the exception of ``start``, ``end``, and ``index``, all of the
-attributes of a repeat variable are methods. Thus, when you use a
-Python expression to access them, you must call them, as in
-``python:repeat['item'].length()``.
-
-Note that ``first`` and ``last`` are intended for use with sorted
-sequences. They try to divide the sequence into group of items with
-the same value. If you provide a path, then the value obtained by
-following that path from a sequence item is used for grouping,
-otherwise the value of the item is used. You can provide the path by
-passing it as a parameter, as in
-``python:repeat['item'].first('color')``, or by appending it to the
-path from the repeat variable, as in ``repeat/item/first/color``.
-
-Examples
-~~~~~~~~
-
-Iterating over a sequence of strings::
-
- <p tal:repeat="txt ('one', 'two', 'three')">
- <span tal:replace="txt" />
- </p>
-
-Inserting a sequence of table rows, and using the repeat variable
-to number the rows::
-
- <table>
- <tr tal:repeat="item here.cart">
- <td tal:content="path:repeat/item/number">1</td>
- <td tal:content="item.description">Widget</td>
- <td tal:content="item.price">$1.50</td>
- </tr>
- </table>
-
-Nested repeats::
-
- <table border="1">
- <tr tal:repeat="row range(10)">
- <td tal:repeat="column range(10)">
- <span tal:define="x path:repeat/row/number;
- y path:repeat/column/number;
- z x*y"
- tal:replace="string:$x * $y = $z">1 * 1 = 1</span>
- </td>
- </tr>
- </table>
-
-Insert objects. Separates groups of objects by type by drawing a rule
-between them::
-
- <div tal:repeat="object objects">
- <h2 tal:condition="path:repeat/object/first/meta_type"
- tal:content="object.type">Meta Type</h2>
- <p tal:content="object.id">Object ID</p>
- <hr tal:condition="path:repeat/object/last/meta_type" />
- </div>
-
-.. note:: the objects in the above example should already be sorted by
- type.
-
-``tal:replace``: Replace an element
------------------------------------
-
-Syntax
-~~~~~~
-
-``tal:replace`` syntax::
-
- argument ::= (['text'] | 'structure') expression
-
-Description
-~~~~~~~~~~~
-
-
-The ``tal:replace`` statement replaces an element with dynamic
-content. It replaces the statement element with either text or a
-structure (unescaped markup). The body of the statement is an
-expression with an optional type prefix. The value of the expression
-is converted into an escaped string if you prefix the expression with
-``text`` or omit the prefix, and is inserted unchanged if you prefix it
-with ``structure``. Escaping consists of converting ``&`` to
-``&amp;``, ``<`` to ``&lt;``, and ``>`` to ``&gt;``.
-
-If the value is ``nothing``, then the element is simply removed. If
-the value is ``default``, then the element is left unchanged.
-
-Examples
-~~~~~~~~
-
-The two ways to insert the title of a "context" object::
-
- <span tal:replace="context.title">Title</span>
- <span tal:replace="text template.title">Title</span>
-
-Inserting HTML/XML::
-
- <div tal:replace="structure table" />
-
-Inserting nothing::
-
- <div tal:replace="nothing">This element is a comment.</div>
-
-``tal:default-expression``: Set the default expression type for a block
------------------------------------------------------------------------
-
-Syntax
-~~~~~~
-
-``tal:default-expression`` syntax::
-
- argument ::= expression-type
-
-Description
-~~~~~~~~~~~
-
-The ``tal:default-expression`` statement sets the default expression
-type within a logical block of tags. If this tag is not used anywhere
-in the document, the default expression type is always ``python``.
-
-Examples
-~~~~~~~~
-
-Setting the default expression type to ``path`` within a block::
-
- <div tal:default-expression="path">
- <span tal:content="template/title">Title</span>
- </div>
Modified: z3c.pt/trunk/docs/narr/tales.rst
===================================================================
--- z3c.pt/trunk/docs/narr/tales.rst 2009-03-06 20:01:05 UTC (rev 97601)
+++ z3c.pt/trunk/docs/narr/tales.rst 2009-03-06 20:02:22 UTC (rev 97602)
@@ -1,15 +1,16 @@
.. _tales_chapter:
-Template Attribute Language Expression Syntax (TALES)
-=====================================================
+TALES Expressions
+=================
The *Template Attribute Language Expression Syntax* (TALES) standard
-describes expressions that supply :ref:`tal_chapter` and
-:ref:`metal_chapter` with data. TALES is *one* possible expression
-syntax for these languages, but they are not bound to this definition.
-Similarly, TALES could be used in a context having nothing to do with
-TAL or METAL.
+describes expressions that supply :term:`TAL` and :term:`METAL` with
+data. TALES is *one* possible expression syntax for these languages,
+but they are not bound to this definition. Similarly, TALES could be
+used in a context having nothing to do with TAL or METAL.
+.. note:: The TALES expression components used by the reference implementation are incompatible with :mod:`z3c.pt` and will not work. This :mod:`z3c.pt` package provides its own implementations.
+
TALES expressions are described below with any delimiter or quote
markup from higher language layers removed. Here is the basic
definition of TALES syntax::
@@ -20,9 +21,8 @@
Here are some simple examples::
a.b.c
- path:a/b/c
+ a/b/c
nothing
- path:nothing
python: 1 + 2
string:Hello, ${user/getUserName}
@@ -32,9 +32,6 @@
like. It also determines which expression type is indicated by
omitting the prefix.
-TALES Expression Types
-----------------------
-
These are the TALES expression types supported by :mod:`z3c.pt`:
* ``python`` - execute a Python expression
@@ -48,32 +45,41 @@
* ``string`` - format a string
.. note:: if you do not specify a prefix within an expression context,
- :mod:`z3c.pt`` assumes that the expression is a *python*
+ :mod:`z3c.pt`` assumes that the expression is a *path*
expression.
-.. warning:: The reference implementation of ZPT has an expression type ``exists``. :mod:`z3c.pt` has no such expression type.
-
.. _tales_built_in_names:
Built-in Names
--------------
-These are the names always available to TALES expressions in
+In addition to ``default`` and ``repeat``, the following names are always available to TALES expressions in
:mod:`z3c.pt`:
-- ``nothing`` - special value used by to represent a *non-value*
- (Python ``None``).
+- ``nothing`` - equal to the Python null-value ``None``.
-- ``default`` - special value used to specify that existing text
- should not be replaced. See the documentation for individual TAL
- statements for details on how they interpret *default*.
+The following names are available in TALES expressions when evaluated inside page templates:
-- ``repeat`` - the *repeat* variables; see :ref:`tal_repeat` for more
- information.
+- ``options`` - contains the keyword arguments passed to the render-method.
-- ``attrs`` - a dictionary containing the initial values of the
- attributes of the current statement tag.
+- ``context`` - the template context
+- ``request`` - the current request
+
+- ``template`` - the template instance
+
+- ``path`` - a method which will evaluate a path-expression, expressed as a string.
+
+- ``exists`` - a method which will evaluate an exists-expression, expressed as a string.
+
+- ``modules`` - provides access to previously imported system modules; using this variable is not recommended.
+
+- ``econtext`` - dynamic variable scope dictionary which keeps track of global variables brought into scope using macros; used internally by the engine, relying on this variable is not recommended (although some legacy applications do so).
+
+Finally, view page templates provide the following names:
+
+- ``view`` - the view instance
+
``nocall`` expressions
----------------------
@@ -147,7 +153,7 @@
Testing a sequence::
- <p tal:condition="not:context.keys()">
+ <p tal:condition="not:context/keys">
There are no keys.
</p>
@@ -195,11 +201,9 @@
of paths segments. To traverse a path, it first fetches the object
stored in the variable. For each path segment, it traverses from the
current object to the subobject named by the path segment. Subobjects
-are located according to standard :mod:`z3c.pt` traversal rules
+are located according to standard traversal rules.
-.. warning:: need to describe traversal rules here. I'd suggest we
- make them pluggable and not require zope.traversal or
- zope.security.
+.. note:: The Zope 3 traversal API is used to traverse to subobjects. The `five.pt <http://pypi.python.org/pypi/five.pt>`_ package provides a Zope 2-compatible path expression.
Once a path has been successfully traversed, the resulting object is
the value of the expression. If it is a callable object, such as a
@@ -210,7 +214,7 @@
evaluated.
The alternate expression can be any TALES expression. For example,
-``path:request/name | string:Anonymous Coward`` is a valid path
+``request/name | string:Anonymous Coward`` is a valid path
expression. This is useful chiefly for providing default values, such
as strings and numbers, which are not expressable as path expressions.
Since the alternate expression can be a path expression, it is
@@ -255,51 +259,37 @@
Description
~~~~~~~~~~~
-Python expressions evaluate Python code in a security-restricted
-environment. Python expressions offer the same facilities as those
+Python expressions evaluate Python code in a restricted
+environment (no access to variables starting with an underscore). Python expressions offer the same facilities as those
available in Python-based Scripts and DTML variable expressions.
-.. warning: Security restrictions?
+.. warning: Zope 2 page templates may be executed in a security-restricted environment which ties in with the Zope 2 security model. This is not supported by :mod:`z3c.pt`.
-Built-in Functions
-~~~~~~~~~~~~~~~~~~
-
-You can use any name passed in to the ``render`` method of a template
-within a Python expression.
-
-These functions are also available in Python expressions:
-
-``path(string)`` -- Evaluate a TALES path expression.
-
-``string(string)`` -- Evaluate a TALES string expression.
-
-``nocall(string)`` -- Evaluates a TALES nocall expression.
-
Examples
~~~~~~~~
Using a module usage (pick a random choice from a list)::
- <span tal:replace="random.choice(['one',
- 'two', 'three', 'four', 'five'])">
- a random number between one and five
+ <span tal:replace="python:random.choice([
+ 'one', 'two', 'three', 'four', 'five'])">
+ A random number between one and five
</span>
String processing (capitalize the user name)::
- <p tal:content="user.getUserName().capitalize()">
+ <p tal:content="python:user.getUserName().capitalize()">
User Name
</p>
Basic math (convert an image size to megabytes)::
- <p tal:content="image.getSize() / 1048576.0">
+ <p tal:content="python:image.getSize() / 1048576.0">
12.2323
</p>
String formatting (format a float to two decimal places)::
- <p tal:content="'%0.2f' % size">
+ <p tal:content="python:'%0.2f' % size">
13.56
</p>
More information about the Checkins
mailing list