This talk describes how to theme a Plone site using Deliverance, and discusses why you might want to use Deliverance.

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

3. Put this nav and content...

4. Put this nav and content...

5. Put this nav and content...

6. ...into this website design.

7. ...into this website design.

8. ...into this website design.

9. Voila!

10. Voila!

11. Voila!

12. How long did this take?

13. 2 minutes

14. How many lines of code?

15. 2 rules

16. And I didn't touch
www.psu.edu
(honest)

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

19. Knowledge needed
• Buildout
• Paster
• Zope page templates (ZPT)
• Python
• ZCML
• resource registry (for CSS and JS)
• /skins vs. /browser

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

27. TOPP
One Deliverance
theme for:
• Plone site
• Wordpress site
• Task tracker

28. repoze.org
nginx Deliverance
proxy proxy

29. Home page

30. Blog

31. Issue tracker

32. Mailing lists

33. plone.tv uses Deliverance

34. plone.org uses Deliverance

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

38. Let's look at an example

39. How do I make this...

40. ...look like this?
http://www.oswd.org/design/preview/id/3293

41. With Deliverance!
Deliverance

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.

44. #portal-logo img

46. #logo h1

47. Rule to replace logo
<replace content=quot;____________quot; theme=quot;_______quot; />

48. Rule to replace logo
<replace content=quot;#portal-logo imgquot; theme=quot;________quot; />

49. Rule to replace logo
<replace content=quot;#portal-logo imgquot; theme=quot;#logo h1quot; />

50. Logo placeholder is
replaced with real 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.

53. children:#portal-globalnav

55. children:#links ul

56. Rule to replace navigation
<replace content=quot;__________________quot; theme=quot;____________quot; />

57. Rule to replace navigation
<replace content=quot;children:#portal-globalnavquot; theme=quot;____________quot; />

58. Rule to replace navigation
<replace content=quot;children:#portal-globalnavquot; theme=quot;children:#links ulquot; />

59. Dummy text for top
navigation is replaced

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.

62. children:#parent-fieldname-title

64. children:div#leftbar h2

65. Rule to replace heading
<replace content=quot;children:#parent-fieldname-titlequot;
theme=quot;children:div#leftbar h2quot; />

67. p.documentDescription

68. No class or id for this

69. Use XPath to get the
element identifier

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; />

73. children:#parent-fieldname-text

74. What is the XPath for
the 2nd paragraph?

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; />

77. Logo, nav, heading,
description, body text

78. Logo, nav, heading,
description, body text

79. XPath of more link

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

82. Modify attributes
Replace tags

83. Debugging console

84. Edit rules TTW

85. Ways to run
deliverance
• proxy
• WSGI middleware using repoze
• xdv (using Martin's collective.xdv)

86. Proxy
• Deliverance runs on port 5000 and
forwards requests on to port 8080
• Two separate Python processes

87. WSGI Middleware
• Deliverances runs as WSGI middleware
• Only one Python process
• Example showing Zope and Zine running in
same process

88. Make your blog look
like your Plone site

89. Zine - python blogging tool

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>

92. Zine themed as Plone

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.

94. collective.xdv

95. xdv vs. Deliverance 0.3
Pros and Cons

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

101. Thanks to...
Paul Everitt

102. Thanks to...
Paul Everitt

103. Thanks to...
Paul Everitt Ian Bicking

104. Thanks to...
Paul Everitt Ian Bicking

105. Thanks to...
Paul Everitt Ian Bicking Aaron VanDerlip

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

108. More info
• http://svn.plone.org/svn/collective/deliverancedemo/
• http://www.openplans.org/projects/deliverance/
introduction
• http://deliverance.openplans.org/configuration.html
• http://plone.tv/media/1884178516/view (Ian's talk)
• http://plone.tv/media/1099397680/view (Paul's talk)
• http://pypi.python.org/pypi/collective.xdv/
• http://www.sixfeetup.com/blog/2009/4/27/deploying-
plone-and-zine-together-with-deliverance-using-
repoze

109. Photo credits
• http://www.flickr.com/photos/sir_mervs/
2697096089/