======
 TODO
======

1.0b1
=====

Definitely
----------

 [ ] Rename namespaces to:
    - http://namespaces.plone.org/diazo/1
    - http://namespaces.plone.org/diazo/css

 [ ] <notheme /> directive
    - Analogous to <theme />
    - Requires if-path, if-content, if-host or similar
    - Same precedence
    - Can turn off the theme for a given condition
 
 [ ] Add if-host condition for
    - All rules
    - <theme />
    - Nested <rules />

 [ ] Implement theme-children attribute and remove <copy /> directive
    - <replace css:theme-children="td#main" css:content="div#content" />
    - <replace theme-children="//td[@id='main']" content="//*[@id='content']" />

 [ ] Implement content-children as a way to select all child nodes, including
     text nodes, of a content selector, e.g.:
    - <replace css:theme="#content .placeholder" css:content-children="div#content" />
    - <replace css:theme="#content .placeholder" content-children="//div[@id='content']" />
    - <drop css:content-children="#foo" />
    - <drop css:theme-children="#foo" />
    - Ditto for other rules as applicable

 [ ] Add namespace upgrade from XDV
    - and also the "old" Diazo namespace?

 [ ] Put README.txt on diazo.org

Maybe
-----

[ ] <omit /> directive (see below)

[ ] Debugger (see below)

[ ] Fix CSS to XPath translation to be more robust with expressions like
    ".foo div"

Details
=======

Refactor compiler (complete)
----------------------------

Move to a pipeline. Running compiler.xsl in Apache did not work out in
practise.

# css -> xpath
# rules.xml + themes merged together
# annotate
# compile theme

Group directive (implemented as nested <rules>)
-----------------------------------------------

It would be useful to group together rules that share the same condition::

    <group css:if-content="body.section-documentation">
     <copy css:content="#foo" css:theme="#header" />
     <append css:content="#bar" css:theme="#footer />
    </group>

Nested conditions would be allowed and simply ANDed together.

* Maybe this should be called ``rules`` instead.


Path conditions (implemented as a single if-path attribute)
-----------------------------------------------------------

So far, Diazo has taken the view that path configuration belongs in your
webserver .conf file (or collective.diazo control panel / paste ini file). But
it might be nice to centralise configuration in the rules.xml::

    <copy if-path-starts="/foo/bar/" ... />
    <copy if-path-ends="/index.html" ... />

To match multiple paths in a single rule separate them with spaces::

    <copy if-path-starts="/foo/   /bar/" ... />

This would be limited to simple string matching. Regexp would also be
possible, with the extension included in lxml or the libxslt-regexp-plugin_
for apache / nginx usage::

    <copy if-path-match=".*html" ... />

($path would be supplied to the template as a parameter)

.. _libxslt-regexp-plugin: http://fr.rpmfind.net/pub/libxml/plugins/


Refactor generated xslt (complete)
----------------------------------

The xslt generated by the diazo compiler is currently uses three passes,
an initial-stage where drop rules are applied, an apply-theme stage
and a final-stage which ensures script and style element content is
unquoted. By collapsing this into a single stage we should see a
30-50% speedup (from my initial experiments).

The initial-stage and final-stage passes were also a plugin point to
include custom xslt, but diazo 0.3 now allows you to write inline xsl
should you wish::

    <diazo:replace css:theme="#details">
       <dl id="details">
           <xsl:for-each css:select="table#details > tr">
               <dt><xsl:copy-of select="td[1]/text()"/></dt>
               <dd><xsl:copy-of select="td[2]/node()"/></dd>
           </xsl:for-each>
       </dl>
    </diazo:replace>

extra.xsl is may also be used for output directives, such as
``<xsl:strip-space elements="*" />``. This would be put into the rules file
instead.

There is one slight complication. Take a content document as follows::

    <div class="bar">ONE</div>
    <div class="foo><div class="bar">TWO</div></div>

And rules::

    <drop css:theme=".foo"/>
    <copy css:content=".bar" theme="#info"/>

Should this give the output (as currently)::

    <div id="info"/>
    <div class="bar">ONE</div>
    </div>

or (the easier to implement in a single pass template)::

    <div id="info"/>
    <div class="bar">ONE</div>
    <div class="bar">TWO</div>
    </div>

I guess the former might be implemented by prefixing
ancestor-or-self::, though that may interact badly with complex xpath
selectors.


Include directive (rejected)
----------------------------

The current xinclude syntax is complex, maybe we need a dedicated directive::

    <include href="rules2.xml"/>

* Lars noted that by placing an id on groups, it would be possible to pull in
  groups with xinclude. e.g.:

  In rules.xml::

    <rules>
      <xi:include href="common.xml#ruleset1">
    <rules>

  In common.xml::

    <rules>
      <group id="ruleset1">
        <copy css:theme="#content" css:content="#content" />
      </group>
      <group id="ruleset2">
        <copy css:theme="#footer" css:content="#footer" />
      </group>
    </rules>

  With the result::

    <rules>
      <group id="ruleset1">
        <copy css:theme="#content" css:content="#content" />
      </group>
    </rules>

* Nested <rules> now works, so this is not necessary.

Theme directive / multiple theme support (complete)
---------------------------------------------------

It would be nice to specify the theme in the rules file itself::

    <theme href="theme.html"/>

Multiple themes may be used with conditions::

    <theme css:if-content="body.section-foo" href="foo.html"/>
    <theme href="theme.html"/>

When no conditional theme matches and there is no unconditional theme, the
page would still be parsed and serialized through libxml2.


Better debugging support
------------------------

There needs to be some mechanism to feedback to the integrator which rules are
being matched, probably by writing out information into comments.


Omit directive
--------------

Similar to TAL's omit-tag, it leaves the contents of the matched node
in place, while omitting the start and end tags (along with any
attributes)::

    <omit css:theme="#foo"/>

* Martin points out that ``omit`` is a synonym for ``drop``, though we already
  have ``copy`` and ``replace``.


Maybe sometime in the future
============================


pyref support
-------------

It might be useful to add pyref_ support for collective.diazo and dv.diazoserver.

.. _pyref


i18n support
------------

It would be nice to be able to leverage the existing gettext translation
machinery for message strings within the template. I don't know exactly what
syntax we should use, but it would be quite easy to implement with lxml (see
this perl example_.) For Apache / Nginx use we would need a C libxslt plugin,
but that shouldn't be too hard.

Maybe something like::

    <translate css:theme="#footer-text" id="copyright-message"/>

.. _example: <http://xims.info/presentations/200801107_tcpw2008-I18N_with_XSLT_and_what_Perl_has_got_to_do_with_it/>`_
