Deliverance: Plone theming without the learning curve from Plone Symposium East 2009
1. Deliverance
Deliverance
Plone theming without the learning curve
Plone Symposium East 2009
State College, PA
May 29, 2009
Nate Aune
www.jazkarta.com
2. Who am I?
• Using Plone since 2002
• Founder/President of Jazkarta since 2004
• Not a designer but work with many designers
17. Agenda
• What is the problem with Plone theming?
• What is Deliverance?
• Who is it for?
• When might you consider using Deliverance?
• Who is using it?
• How do you use it?
• Q&A
18. Theming in Plone
an exercise in patience
• Install dependencies (Python, XCode, GCC)
• Create a theme egg using paster
• Put your stylesheets and images in /browser
• But override Plone assets in /skins
• To turn off viewlets, must edit configure.zcml
• To make new viewlets must code Python
• Must learn ZPT to edit page templates
20. Designers are not coders
quot;It is a significant disadvantage if
the designers and HTML/CSS
coders are not familiar with Plone,
but it's incredibly difficult to find top
designers who have even heard of
Plone.quot;
- Scott Paley (Abstract Edge)
21. Who is it for?
• Designers
• Integrators
• Customers
• First-timers
22. When you might consider
using Deliverance?
• Consulting projects
• Heterogenous environment
• Designers are not familiar with Plone
23. Why use it?
• Designers don't want to learn unusual stuff
• Sometimes the design already exists
• Reduce size of stuff-unique-to-Plone
• Performance and flexibility
• Works with Python (and non-Python)
24. Why not?
• Plone 2.5/3.0 is easy enough to theme
• Might be hard, but worth it
• I'm both the developer and UI person
• I'll need to stray over the line anyway
• Plone needs to stop changing
25. Who is using it?
• The Open Planning Project
• repoze.org
• plone.tv
• plone.org
26. TOPP
• Many different
systems
• All being themed
using Deliverance
• topp.openplans.org
35. How does it work?
move elements from your content
into placeholders in your theme
... without touching the theme or content
36. Black magic?
(well, not really)
• uses a rule file to govern the merging
• rules are verbs of common actions
• use CSS selectors or XPath to identify
elements to act on
37. What are the verbs?
• drop
• append
• prepend
• replace
Rules documentation:
http://deliverance.openplans.org/configuration.html
42. Replace the logo
• Replace the logo in the theme with the
logo in the Plone site.
• Use Firebug to identify the CSS selectors
• Use the <replace> verb since we only want
one logo.
51. Slightly more complex
example
• Replace horizontal navigation tabs with
Plone's portal_tabs
• Uses children: to select the children
elements
• Keeps parent which has the proper CSS
attributes for the theme style.
60. Introducing XPath
• Replace page title and description and body
text
• Theme doesn't have explicit identifiers for
the description and body text fields
• We can use Firebug to tell us the XPath
expression for these elements.
70. XPath
• The XPath expression that Firebug gives us:
• /html/body/div/div/div[3]/div[2]/p
• since the <div> above the <p> has an ID,
we can use this shorthand notation:
• //*[@id=quot;leftbarquot;]/p
71. Replace the first
paragraph with the
document description
<replace content=quot;p.documentDescriptionquot; theme=quot;//*[@id=quot;leftbarquot;]/pquot; />
75. What is the XPath for
the 2nd paragraph?
• children://*[@id=quot;leftbarquot;]/p[2]
76. Map body text to 2nd
paragraph
<replace content=quot;children:#parent-fieldname-textquot;
theme=quot;children://*[@id=quot;leftbarquot;]/p[2]quot; />
80. Remove the more link
with drop
<drop theme='/html/body/div/div/div[3]/div/a' />
81. Other cool features of
Deliverance 0.3
• modify attributes
• drop a particular CSS file
• conditionals (when logged in, when not)
• load content from external sources
• rewriting - don't need a local dev environment
• debugging console
90. paste.ini
[pipeline:zope] [filter:deliverance]
pipeline = egg:Paste#cgitb use = egg:deliverance#main
egg:Paste#httpexceptions rule_filename = %(here)s/rules.xml
egg:repoze.retry#retry
egg:repoze.tm#tm [server:main]
egg:repoze.vhm#vhm_xheaders use = egg:repoze.zope2#zserver
errorlog host = localhost
zope2 port = 8080cat
[pipeline:blog] [composite:main]
pipeline = egg:Paste#cgitb use = egg:Paste#urlmap
egg:Paste#httpexceptions /blog = blog
errorlog /zope = zope
deliverance
zine
91. rules.xml
<ruleset>
<theme href=quot;/zope/Plone/main_templatequot; />
<rule>
<prepend theme=quot;//headquot; content=quot;//head/linkquot; nocontent=quot;ignorequot; />
<prepend theme=quot;//headquot; content=quot;//head/stylequot; nocontent=quot;ignorequot; />
<append theme=quot;//headquot; content=quot;//head/scriptquot; nocontent=quot;ignorequot; />
<append theme=quot;//headquot; content=quot;//head/metaquot; nocontent=quot;ignorequot; />
<replace theme=quot;//head/titlequot; content=quot;//head/titlequot; nocontent=quot;ignorequot; />
<!-- we don't need the reddit zine links -->
<drop content=quot;//div[@class='reddit']quot;/>
<!-- let's drop the breadcrumbs from the plone theme -->
<drop theme=quot;#portal-breadcrumbsquot;/>
<!-- let's drop the plone login box -->
<drop theme=quot;//td[@id='portal-column-one']/div/divquot;/>
<!-- put the zine portlets in column one -->
<append theme=quot;//td[@id='portal-column-one']/divquot; content=quot;//div[@class='sidebar']/*quot; nocontent=quot;ignorequot;/>
<!-- put the body of the zine in the content region -->
<append theme=quot;children:#region-contentquot; content=quot;children://div[@class='contents']quot; nocontent=quot;ignorequot; />
<!-- put the administrative links in column two -->
<prepend theme=quot;children:#portal-column-twoquot; content=quot;//div[@class='body']/ulquot; nocontent=quot;ignorequot;/>
<!-- make sure the login box has a spot when we need it -->
<append theme=quot;#viewlet-above-contentquot; content=quot;//div[@class='login-box']quot; nocontent=quot;ignorequot;/>
</rule>
</ruleset>
93. collective.xdv
• tightly integration solution with Plone
• applies a transformation to Plone's HTML
output, using the XDV compiler
• XDV is an implementation of Deliverance,
specifically the original Deliverance XML-
based syntax
• Compiles the theme (an HTML file) and
rules (an XML file) into a single XSLT file,
which is then applied to Plone's HTML on
render.
97. Pros for xdv
• Deployment is simpler, as pure XSLT
• No runtime overhead of another long-
running Python process
98. Cons for xdv
• Somewhat less natural selectors/rules (i.e.
you can't use CSS selectors, at least not
directly)
• Less momentum
• The dv.xdvproxy that lets you use xdv on-
the-fly with WSGI has some issues and is
not intended for production use.
99. Pros for Deliverance 0.3
• Has a dedicated maintainer
• More powerful - can combine multiple
themes without requiring Apache magic, for
example
• CSS selectors
100. Cons for Deliverance 0.3
• More power means people will start doing crazy
things
• Makes most sense (for Plone) in a WSGI pipeline,
but that aspect is not quite as developed yet, and
Plone is not WSGI-ified until 4.0.
• Requires a long-running process until we're talking
about a full WSGI stack or mod_wsgi
106. Your chance to
contribute and learn!
Deliverance documentation sprint
• produce the Definitive
Deliverance tutorial
• help promote and
disseminate information
about Deliverance
• make Plone theming
easier for all!
107. Your chance to
contribute and learn!
Deliverance documentation sprint
• produce the Definitive • learn the easiest way
to theme your Plone
Deliverance tutorial
sites
• help promote and • learn hands-on how
disseminate information
Deliverance works
about Deliverance
• make Plone theming • get all your
Deliverance questions
easier for all!
answered
Designers - \"for people who think Photoshop is lickable\" as Paul Everitt says)
Integrators (\"People who's job it is to make Plone work for other people\")
Customers (who already have and manage a corporate identity)
First-timers (who want a quick win without too many new concepts)
Consulting projects (where \"branding\" is already managed by non-developer)
Heterogenous environment where the same theme must be shared across multiple applications (wiki, blog, mailman, bug tracker)
Designers are not familiar with Plone and you need to iterate rapidly with design
- Performance and flexibility (designers' css, js, images can be served up from disk, rather than plone)
- Works with Python (and non-Python) \"we catch the markup on the way out the door and modify it\"
- I'm both the developer and UI person (separation of concerns is overhead)