Deliverance: Theming Decoupled
==============================

:author: Ian Bicking
:organization: `The Open Planning Project <http://topp.openplans.org>`_
:site: http://deliverance.openplans.org

Outline Of This Talk
--------------------

1. A demonstration of what Deliverance does
2. Why Deliverance
3. How Deliverance Works (from the outside)

Installation
------------

* Installation:

  - "Quickstart" on deliverance.openplans.org
  - Uses pyinstall/pybundles
  - Regular snapshots, but not automated

paster startup
--------------

::

    $ pyinstall.py -E DelivTest Deliverance-snapshot-latest.pybundle
    $ cd DelivTest
    $ source bin/activate
    $ paster create -t deliverance_plone .

Demo
----

See the demo...

Why Deliverance?
----------------

Why Do *I* Work With Deliverance?
---------------------------------

* I've been through a lot of frameworks

* Using a new framework, platform, or existing application shouldn't be a repudiation of any other system


Why Do *I* Work With Deliverance?
---------------------------------

* This lets me do things with Plone without poking around in the internals

* It is built on technologies I **know** will stay relevant:

  - HTTP

  - HTML


Why Should *You* Care?
----------------------

* Theming with no (visible) Python

* Rules and content are entirely separate (vs. Page Templates)

* Aggregation is relatively straight-forward


Why Should *You* Care?
----------------------

* Clear path for creating exceptions (e.g., ``class="sphinx"``)

* Everything is based on visible information: URLs and markup


Why You Should Want Heterogeneity
---------------------------------

* Plone, the community, can't be everything to everyone

  - For example, Plone will never have the best blog

* Without heterogeneity, every platform and specialization of a platform creates smaller and smaller audiences


Heterogeneous Stacks Are Hard
-----------------------------

(I'm not going to deny it)


How Deliverance Works
---------------------

Moving Boxes Around
-------------------

* Deliverance moves boxes around between the content and theme, and some external resources (like the sidebar)

* Deliverance produces no content itself

* Deliverance doesn't care how the content was produced


From Content To Theme
---------------------

* "Content" is the response that was generated for the request -- what you'd see if there was no Deliverance and no theming

* "Theme" is the theme you've created

From Content To Theme
---------------------

* The response starts with the theme page

* Rules move stuff from the content into the theme

* If there were no rules, every response would be the identical theme page




The Rules
---------

Four rules:

* ``<replace>``

* ``<append>``

* ``<prepend>``

* ``<drop>``

replace, append, prepend
------------------------

``<replace theme="..." content="..." />``:
    Remove some stuff from the theme, and replace it with stuff from the content

``<append theme="..." content="..." />``:
    Take some stuff from the content and put it right after some stuff in the theme

``<prepend theme="..." content="..." />``:
    Like ``append``, but prepend

Rules
-----

``<replace>`` looks like::

  <replace
   content="...selector..."
   theme="...selector...">


Rules
-----

``<replace>`` looks like::

  <replace
   content="children:#content"
   theme="children:#content">

Replace all the children of ``#content`` in the theme, with the children of ``#content`` in the content.


Selectors
---------

* Selectors can be CSS selectors (``#content``) or XPath (``//*[@id='content']``)

* Selectors select *elements*

* Modifiers make it more clear what you want to do


Selectors (modifiers)
---------------------

``element:...``:
    Selects the element

``children:...``:
    Selects the children of the element

``tag:...``:
    Selects the *tag*, but not its children

Selectors (modifiers)
---------------------

``attributes:...``:
    Selects the attributes of the elmeent

``attributes(class):...``:
    Selects just the ``class`` attribute of the element


drop
----

Mostly to fix up problems:

``<drop theme="..." />``:
    Remove some stuff from the theme

``<drop content="..." />``:
    Remove some stuff from the content (only meaningful if you have later rules)



Examples
--------

::

  <append theme="chidren:#content" content="elements:.content" />

* Take the elements from the content with the class ``.content``

* The target is ``children:#content`` -- the element with the id ``content`` (e.g., ``<div id="content">``

* Because the target is ``children``, it will be appended *inside* the ``<div id="content">`` tag

Examples
--------

::

  <append theme="chidren:#content" content="elements:.content" />

(continued...)

* It will also preserve the children of that div; if you don't want to preserve that content (e.g., it looks like ``<div id="content">content goes here</div>`` use ``<replace>``

Examples
--------

::

  <drop content="tag:font" />

* This will remove the ``<font>`` tags, but *not* their children (will just clean the content)

Examples
--------

::

  <prepend content="attributes(class):body" theme="attributes:body" />

* This will move the ``class`` attribute from ``<body>`` in the content, into ``<body>`` in the theme.

* With ``<prepend>`` the *content* attributes get priority, with ``<append>`` the *theme* attributes get priority


Examples
--------

::

  <append theme="elements:div#footer" content="elements:div#copyright" />

* This adds the element ``<div id="copyright">`` from the content immediate *after* ``<div id="footer">`` in the theme

* This is probably not what you want

* Usually you want ``children:`` for the theme, and ``elements:`` or ``children:`` for the content


if-content
----------

* Rules can be conditional

* The only condition is "if this selection matches something in the content"

::

    <drop theme="#copyright" if-content=".creative-commons" />
    <append content="elements:.creative-commons" 
            theme="elements:#content" />



Runtime rule errors/exceptions
------------------------------

Consider the rule::

    <replace content="children:#content" 
             theme="children:#content" />

Your 404 page may not include ``<div id="content">``.  You do not want a 404 to turn into a theme page with no information



Runtime rule errors/exceptions
------------------------------

::

    <replace content="children:#content" 
             theme="children:#content" 
             nocontent="abort" />

If ``children:#content`` matches no elements, abort all theming.

Other corner cases can be specified.

href
----

* How do you make the theme dynamic?

* Deliverance produces **no content**

  - It only moves content around

* If everything you want to display is in your content or theme, you can move it all around appropriately, otherwise...


href
----

::

    <append href="/sidebar" content="children:#content"
            theme="children:#sidebar" />

Take the resource from ``/sidebar`` (which can be dynamic)

(In the future, this will be a URI Template, so you can implement more dynamicism)


Exceptional Places In The Site
------------------------------

* Usually the front page

* The simple way, don't theme it::

    <match path="exact:/" abort="1" />


Exceptional Places In The Site
------------------------------


Or change the theme::

    <match path="exact:/" class="frontpage" />
    <rule class="frontpage">
      <theme href="/_themes/frontpage.html" />
      ... rules ...
    </rule>

Exceptional Places In The Site
------------------------------

Or maybe you just want some extra rules::

    <match path="exact;/" class="frontpage default" />
    <rule class="frontpage">
        ... some extra rules ...
    </rule>
    <rule> <!-- no class means "default" -->
        <theme href="..." /> 
        ... other rules ...
    </rule>

Exceptional Places In The Site
------------------------------

Some application has a PITA bit of CSS::

    <match path="/trac" class="trac default" />
    <rule class="trac" />
        <drop content="link[href$='/trac.css']" />
    </rule>

Workarounds
-----------

Avoid theming...

A page name (any path that ends with ``/blank.html``)::

    <match path="wildcard:*/blank.html" abort="1">

Workarounds
-----------

Avoid theming...

Based on a request header::

    <match request-header="User-Agent: contains-insensitive:slurp" abort="1">

Workarounds
-----------

Avoid theming...

Based on a response header::

    <match response-header="X-No-Deliverate: bool:true" abort="1">

This includes "headers" that are in the page, like ``<meta http-equiv="X-No-Deliverate" content="1">``

CSS vs. XPath
-------------

``link[href$='trac.css']`` is CSS 3 which matches all ``<link>`` tags with an ``href`` attribute that ends with ``/trac.css`` (CSS 3).

Compare the CSS 3 with XPath 1.0::

    link[href$='trac.css']
    //link[substring(@href, string-length(@href)-len('/trac.css')) = '/trac.css']


CSS
---

* CSS is great, except for it being horrible

* CSS **classes** are the horrible part.  And ``#id``


CSS
---

* CSS is:

  - A way of mapping (vaguely) semantic HTML to a presentation (styles on tags)

  - A page layout description (layout, based mostly on ids)

  - A mapping from a custom semantic document language to presentation (styles on classes)

CSS
---

* Unfortunately, CSS is not portable

  - Page layout and CSS classes use an application-specific vocabulary

CSS
---

* And CSS is not encapsulated: you can't easily apply CSS to just a portion of a site

  - Rules are flat

  - HTML generally is flat

  - This is frustrating, I don't have a solution, I'm not sure what the solution would be (mostly not sure)

CSS
---

* Tag-based CSS (i.e., selectors without class or id conditions) should be dropped from applications, implemented by theme

* Large-scale page layout CSS (e.g., sidebars, etc.) should also be in the theme

* Small-scale page layout should remain with the application (e.g., laying out a form); this is typically done partially with ids and partially with classes

CSS
---

* The custom semantic language should be unified across all your applications, and defined by CSS in the theme

  - Like a CSS framework, but better than the CSS frameworks I've seen so far

  - Current CSS frameworks seem focused on making tricky designer problems easier, not to creating a consistent and application agnostic language

CSS & HTML 5
------------

* HTML 5 increases the number of tags to increase the expressiveness of content without using CSS classes

  - ``<article>``, ``<section>``...


The Many-Places Problem
-----------------------

* When someone sees a page, and wants to change something on the page, they now have yet more places to look for the content

* Deliverance has no solutions yet, this is just an acknowledgment

* What I'd like is if elements had attributes to show where the element was generated (typically a file or URL where the template that generated the content came from)

The Many-Places Problem
-----------------------

* Deliverance would have to mix and match these attributes as it moves things around, but I can only add that feature if there's something worth moving around

  - But I'd really like to add this feature

  - This should be applicable beyond Plone without trouble



Development Cycle
-----------------

* Theming is entirely separate from the aapplication

  - That also means you can many many themes for one application

  - Meaning, you can do theme development with a production application

* Link rewriting allows you to theme a live site

Development Cycle
-----------------

* You can change rules on the fly (though not the server and proxy settings without a restart)

* You can change the theme on the fly (*always*)

Deployment
----------

* Why the emphasis on separate server processes?

  - Deploy products in isolation (buildout, virtualenv, etc -- even PHP/apache)

  - *No* shared code

  - Avoid a version/release lockstep between large pieces of your stack

Deployment
----------

* Why the emphasis on separate server processes?

  - Upgrade pieces when you want to, get bug fixes, new features, etc., without cascading effects across your entire site

  - No migrations needed to update Deliverance


Opportunities: Caching
----------------------

* Everything talks HTTP

  - This means you can put a cache between any two pieces

* Pages can be assembled from multiple pieces

  - Some of the pieces might be cachable, even if the aggregate is not


The Many Implementations of Deliverance
---------------------------------------

* Paul Everitt is working on an XSLT implementation