This talk gives an overview of Deliverance, a middleware tool that makes it easy to theme any website. In particular, we discuss how to make it work with the Plone, open source CMS.

1. Deliverance
a compelling way to Plone sites
Nate Aune
www.jazkarta.com
Plone Conference 2009

2. Slides to add
• if-content
• used to match certain templates
• proxy to live site
• jquery.com example - show theme=
• how to handle theming of elements inside the
HTML that Plone generates in the static theme
• does the XML file need to be well-formed?
what about the HTML? does it need to be valid
XHTML.
• can Plone's authoring interface be themed to
look like the Deliverance-themed site?
jazkarta

3. Obstacles
Plone theming has a
high barrier to entry

4. 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
jazkarta

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

6. Does your head hurt yet?
jazkarta

7. What is Deliverance?
• Middleware tool that serves as a proxy
• Maps content HTML into design HTML
• Keeps presentation separate from content
jazkarta

8. Who is it for?
jazkarta

9. Who is it for?
• Designers
jazkarta

10. Who is it for?
• Designers
• Integrators
jazkarta

11. Who is it for?
• Designers
• Integrators
• Developers
jazkarta

12. Who is it for?
• Designers
• Integrators
• Developers
• Customers
jazkarta

13. How does it work?
jazkarta

14. How does it work?
move elements from your content
jazkarta

15. How does it work?
move elements from your content
jazkarta

16. How does it work?
move elements from your content
into placeholders in your theme
jazkarta

17. How does it work?
move elements from your content
into placeholders in your theme
jazkarta

18. How does it work?
move elements from your content
into placeholders in your theme
... without touching the theme or content
jazkarta

19. How does it work?
move elements from your content
into placeholders in your theme
... without touching the theme or content
jazkarta

20. Python
is
magical
http://xkcd.com/353/ jazkarta

21. jazkarta

22. Deliverance
jazkarta

23. Knowledge needed
• HTML
• CSS
• Firebug
• simple editing of XML file
jazkarta

24. Four simple rules
• drop
• replace
• prepend
• append
jazkarta

25. Deliverance benefits
• web designer doesn't need to learn CMS templating
• separation of concerns
• theme multiple apps with one design
(trac, wiki, blog, etc.)
jazkarta

26. Who is using Deliverance?
jazkarta

27. Who is using Deliverance?
• plone.org
jazkarta

28. Who is using Deliverance?
• plone.org
• plone.tv
jazkarta

29. Who is using Deliverance?
• plone.org
• plone.tv
• Harvard School of Engineering (subsites)
jazkarta

30. Who is using Deliverance?
• plone.org
• plone.tv
• Harvard School of Engineering (subsites)
• ploneconf2009.org (get the buildout!)
jazkarta

31. Who is using Deliverance?
• plone.org
• plone.tv
• Harvard School of Engineering (subsites)
• ploneconf2009.org (get the buildout!)
• repoze.org (multi-app theming)
jazkarta

32. Who is using Deliverance?
• plone.org
• plone.tv
• Harvard School of Engineering (subsites)
• ploneconf2009.org (get the buildout!)
• repoze.org (multi-app theming)
• and many others...
jazkarta

33. Case study
A real world example of using Deliverance

34. jazkarta

35. jazkarta

36. jazkarta

37. jazkarta

38. "Replace our custom backend with Plone CMS."
HaiVision
jazkarta

39. "Replace our custom backend with Plone CMS."
HaiVision
"Sure, we can do that."
Jazkarta
jazkarta

40. "Replace our custom backend with Plone CMS."
HaiVision
"Sure, we can do that."
Jazkarta
"Keep the frontend design the same."
HaiVision
jazkarta

41. "Replace our custom backend with Plone CMS."
HaiVision
"Sure, we can do that."
Jazkarta
"Keep the frontend design the same."
HaiVision
"No problem."
Jazkarta
jazkarta

42. "Replace our custom backend with Plone CMS."
HaiVision
"Sure, we can do that."
Jazkarta
"Keep the frontend design the same."
HaiVision
"No problem."
Jazkarta
"We're going to change the design soon, and
we want to be able to change the HTML/CSS
HaiVision
ourselves."
jazkarta

43. "Replace our custom backend with Plone CMS."
HaiVision
"Sure, we can do that."
Jazkarta
"Keep the frontend design the same."
HaiVision
"No problem."
Jazkarta
"We're going to change the design soon, and
we want to be able to change the HTML/CSS
HaiVision
ourselves."
"Umm. Ok, you will be able to do that."
Jazkarta
jazkarta

44. Customers
change their
mind about
their identity
all the time.
Don't make it painful than
it already is for them.

45. "Oh, and we need this done
HaiVision in two weeks."
Jazkarta

46. "Oh, and we need this done
HaiVision in two weeks."
"WTF!?" Jazkarta

47. DELIVERANCE
Deliverance
to the rescue!

48. Why Deliverance?
• They have three different sections of the
site, each needing to be themed differently.
• They want to change the design, but their
staff only knows HTML/CSS.
• They might want to theme another web
app to have the same look-n-feel as their
website.
• Oh, and they want this done ASAP.
jazkarta

49. Why not a Plone theme?
• Significant man hours to make a pixel perfect Plone
theme
• Difficult to apply a different theme for different
sections of the site
• The customer should not have to learn Plone
theming technology to make design changes.
• One less piece of software that we have to maintain
• Difficult to upgrade to newer versions of Plone
when there are many theme customizations
jazkarta

50. Seven Steps to Heaven
jazkarta

51. Seven Steps to Heaven
1. Check out and run the Deliverance demo buildout
jazkarta

52. Seven Steps to Heaven
1. Check out and run the Deliverance demo buildout
2. Prepare your HTML/CSS files (might need to do
some cleanup)
jazkarta

53. Seven Steps to Heaven
1. Check out and run the Deliverance demo buildout
2. Prepare your HTML/CSS files (might need to do
some cleanup)
3. Stick the files in a /static folder in buildout dir
jazkarta

54. jazkarta

55. 4. Identify the CSS selectors of the elements in the
Plone site that we wish to map to the static
theme.
jazkarta

56. 4. Identify the CSS selectors of the elements in the
Plone site that we wish to map to the static
theme.
5. Identify the CSS selectors in the static theme that
should serve as placeholders for the dynamic
content coming from Plone.
jazkarta

57. 4. Identify the CSS selectors of the elements in the
Plone site that we wish to map to the static
theme.
5. Identify the CSS selectors in the static theme that
should serve as placeholders for the dynamic
content coming from Plone.
6. Create a rules file that maps Plone content
elements to placeholder elements in the theme
jazkarta

58. 4. Identify the CSS selectors of the elements in the
Plone site that we wish to map to the static
theme.
5. Identify the CSS selectors in the static theme that
should serve as placeholders for the dynamic
content coming from Plone.
6. Create a rules file that maps Plone content
elements to placeholder elements in the theme
7. Set up an Apache vhost to proxy to Deliverance
jazkarta

59. Start your engines! jazkarta

60. 1. Check out and run
the demo buildout
svn co http://svn.plone.org/svn/collective/deliverancedemo/trunk/ dd
Run the bootstrap command and run the buildout
cd dd
python bootstrap.py
bin/buildout -v
This will install Deliverance and it's dependencies (lxml)
and install a Plone site at /Plone
jazkarta

61. 2. Prepare your HTML/CSS
• An HTML/CSS template that you downloaded
from somewhere
• Design assets that were given to you by a
customer, design agency or your designer
• A design from an existing website
jazkarta

62. jazkarta

63. 3. Stick them in a /static
dir in your buildout
jazkarta

64. 3. Stick them in a /static
dir in your buildout
jazkarta

65. 4. Identify elements in
Plone to map to design
• Firebug is your friend (www.getfirebug.com)
• Click on elements to get their class or id
• Can also get XPath expression by right-
clicking on element
jazkarta

66. jazkarta

67. jazkarta

68. 5. Identify the corresponding
element in the theme
• You may need to add a class or ID to better
identify the element.
• You can use an absolute path to the element in
the DOM, but if the element gets moved, the
mapping rule will not work anymore.
• So it's best to always use a class or ID to avoid
breakage.
jazkarta

69. jazkarta

70. jazkarta

71. rules-training.xml
<?xml version="1.0" encoding="UTF-8"?>
<ruleset>
<server-settings>
<server>0.0.0.0:5000</server>
<execute-pyref>true</execute-pyref>
<dev-allow>127.0.0.1</dev-allow>
<dev-user username="guest" password="guest" />
</server-settings>
<proxy path="/static" class="static" editable="1">
<dest href="{here}/static/" />
</proxy>
<proxy path="/" class="plone">
<dest href="http://localhost:8080/VirtualHostBase/http/
localhost:5000/Plone/VirtualHostRoot/" />
</proxy>
<rule class="static" />
jazkarta

72. rules-training.xml
<?xml version="1.0" encoding="UTF-8"?>
<ruleset>
Open the rules-training.xml file
<server-settings>
in the buildout directory.
<server>0.0.0.0:5000</server>
<execute-pyref>true</execute-pyref>
<dev-allow>127.0.0.1</dev-allow>
<dev-user username="guest" password="guest" />
</server-settings>
<proxy path="/static" class="static" editable="1">
<dest href="{here}/static/" />
</proxy>
<proxy path="/" class="plone">
<dest href="http://localhost:8080/VirtualHostBase/http/
localhost:5000/Plone/VirtualHostRoot/" />
</proxy>
<rule class="static" />
jazkarta

73. The "plone" rule class
<rule class="plone">
<!-- Theme -->
<theme href="/static/index.html" />
<!-- Put your rules below this line -->
</rule>
</ruleset>
jazkarta

74. Replace rule
for page heading
<replace content='children:_______________________'
theme='children:_________________' />
jazkarta

75. Replace rule
for page heading
<replace content='children:h1.documentFirstHeading'
theme='children:_________________' />
jazkarta

76. Replace rule
for page heading
<replace content='children:h1.documentFirstHeading'
theme='children:span.sectionTitle' />
jazkarta

77. 6. Insert our rule into the
rules-training.xml file
<rule class="plone">
<!-- Theme -->
<theme href="/static/index.html" />
<!-- Put your rules below this line -->
<replace content='children:h1.documentFirstHeading'
theme='children:span.sectionTitle' />
</rule>
</ruleset>
jazkarta

78. Let's start up Zope and
the Deliverance proxy
$ cd dd
$ bin/instance start
. . daemon process started, pid=3556
$ bin/deliverance-proxy rules-training.xml
To see logging, visit http://127.0.0.1:5000/.deliverance/login
after login go to http://127.0.0.1:5000/?deliv_log
serving on http://127.0.0.1:5000
jazkarta

79. Go to
http://localhost:5000
... to see the Plone site themed with Deliverance

82. jazkarta

83. jazkarta

84. Replace navigation tree

85. Replace navigation tree
<drop content='.portletNavigationTree dt.portletHeader' />

86. Replace navigation tree
<drop content='.portletNavigationTree dt.portletHeader' />
<drop content='li.navTreeItem img' />

87. Replace navigation tree
<drop content='.portletNavigationTree dt.portletHeader' />
<drop content='li.navTreeItem img' />

88. Replace navigation tree
<drop content='.portletNavigationTree dt.portletHeader' />
<drop content='li.navTreeItem img' />
<replace content="dl.portletNavigationTree"

89. Replace navigation tree
<drop content='.portletNavigationTree dt.portletHeader' />
<drop content='li.navTreeItem img' />
<replace content="dl.portletNavigationTree"
theme="children:#left-navigation" />

90. Replace navigation tree
<drop content='.portletNavigationTree dt.portletHeader' />
<drop content='li.navTreeItem img' />
<replace content="dl.portletNavigationTree"
theme="children:#left-navigation" />
Must place drop rules before replace rule.

91. How do you theme the
sections differently?

92. haivision.com/products
jazkarta

93. Apply page class by path
<match path="/" class="default" />
<match path="/applications" class="applications" />
<match path="exact:/" class="frontpage" />
jazkarta

94. haivision.com/applications
jazkarta

95. haivision.com/applications
jazkarta

96. Repurpose static portlet
jazkarta

97. Repurpose static portlet
jazkarta

98. Repurpose static portlet
jazkarta

99. Each page class can have
a separate theme & rules
jazkarta

100. Each page class can have
a separate theme & rules
<rule class="applications" suppress-standard="1">
<theme href="/static/applications.html" />
<replace content='children:p.documentDescription'
theme='children:span.SectionSubtitle' />
<replace content='children:#portal-column-two'
theme='children:#right-column' />
</rule>
jazkarta

101. frontpage: haivision.com/
jazkarta

102. frontpage: haivision.com/
jazkarta

103. Repurpose the news portlet
jazkarta

104. Repurpose the news portlet
jazkarta

105. Repurpose the news portlet
jazkarta

106. Frontpage has it's own
theme and rules
<rule class="frontpage">
<theme href="/static/frontpage.html"/>
<drop content=".portletNews dt.portletHeader" />
<drop content='.portletNews dd.portletFooter' />
<drop content='.portletNews dd.portletItem img' />
<replace content='dl.portletNews'
theme='children:#newsbox' />
</rule>
jazkarta

107. Serve up different web apps
jazkarta

108. Serve up different web apps
<proxy path="/trac" class="trac">
<dest href="http://localhost:10002" />
</proxy>
<proxy path="/blog" class="blog">
<dest href="http://localhost:10003" />
</proxy>
<proxy path="/" class="plone">
<transform rewrite-links="1" keep-host="1" />
<dest href="http://localhost:8081/VirtualHostBase/http/
{HOST}/sites/haivision-manage/VirtualHostRoot/" />
</proxy> jazkarta

109. How do I deploy Deliverance
into production?
• Run as a proxy on port 5000. Apache or
Nginx proxies to port 5000.
• two separate python processes
• Run as WSGI middleware.
• only one python process running
jazkarta

110. Where does Deliverance
sit in the stack?
Apache
Deliverance
!"#$
%&'($
jazkarta

111. Where does Deliverance
sit in the stack?
Apache
Deliverance
!"#$
%&'($
jazkarta

112. 7. Make the Apache vhost
<VirtualHost *:80>
ServerName www.haivision.com
ProxyPreserveHost On
RewriteEngine On
RewriteRule ^/(.*) http://127.0.0.1:5000/$1 [L,P]
</VirtualHost>
The ProxyPreserveHost is very important.
jazkarta

113. What about
performance?
• Deliverance respects caching headers
• Pages load fast because they don't have to
load all of Plone's assets
• Deliverance runs in small memory footprint
and takes hardly any server resources
jazkarta

114. How is Deliverance
better than xdv?
jazkarta

115. How is Deliverance
better than xdv?
• Has a dedicated maintainer
jazkarta

116. How is Deliverance
better than xdv?
• Has a dedicated maintainer
• Use CSS selectors instead of only XPath
jazkarta

117. How is Deliverance
better than xdv?
• Has a dedicated maintainer
• Use CSS selectors instead of only XPath
• Can combine multiple themes without Apache magic
jazkarta

118. More Deliverance advantages
• Serves static resources directly from the file system.
No need to make a skin or serve from Apache.
• Deliverance has a very useful debugging console
• Deliverance lets you edit files through-the-web
jazkarta

119. Debugging console

120. Edit rules TTW
http://codespeak.net/svn/z3/deliverance/trunk/deliverance/editor/

121. dvsites - wsgi middleware
Map domains to different rules files
[sites]
domains =
*.mysite %(here)s/rules/mysite.xml
anothersite.com %(here)s/rules/anothersite.xml
http://svn.plone.org/svn/collective/dvsites/

122. Future
• CSSZenGarden for Plone themes
• theme1.demo.plone.org
• theme2.demo.plone.org
• ...

123. Banjo
• jQuery-powered frontend to rules creation
• Make rules by point-n-click
• Still in proof-of-concept stage
jazkarta

124. Banjo demo
http://localhost:5000/banjo/

131. Thanks to...
Paul Everitt
Fred van Dijk
Reinout van Rees
Jordan Baker Eric Steele

132. Thanks to...
Paul Everitt
Fred van Dijk
Reinout van Rees
Jordan Baker Eric Steele

133. Thanks to...
Paul Everitt Ian Bicking
Fred van Dijk
Reinout van Rees
Jordan Baker Eric Steele

134. Thanks to...
Paul Everitt Ian Bicking
Fred van Dijk
Reinout van Rees
Jordan Baker Eric Steele

135. Thanks to...
Paul Everitt Ian Bicking Aaron VanDerlip
Fred van Dijk
Reinout van Rees
Jordan Baker Eric Steele

136. Project pages
http://coactivate.org/projects/deliverance/
http://coactivate.org/projects/banjo/
Deliverance documentation and tutorial
http://deliverance.openplans.org
http://plone.org/docu
Sample Deliverance buildouts
http://svn.plone.org/svn/collective/ploneconf/buildout/ploneconf/trunk/
http://svn.plone.org/svn/collective/deliverancedemo/trunk
jazkarta

137. Banjo sprint this wkend?
• jQuery help needed
• Python programmers wanted
• User interface gurus
Put your name on the interest list at:
http://www.coactivate.org/projects/banjo/plone-conference-banjo-sprint
jazkarta

138. Photo credits
• http://www.flickr.com/photos/sir_mervs/2697096089/
• http://www.flickr.com/photos/foxypar4/1004464889
• http://www.flickr.com/photos/pamilne/2271490945
• http://www.flickr.com/photos/motleye/1459699804
• http://www.flickr.com/photos/kaptainkobold/351967847
• http://www.flickr.com/photos/aldoaldoz/2332755401
• http://xkcd.com/353/
jazkarta