One of the first things that people want to do with their Plone site is customize the look-n-feel. This usually requires making a Plone theme product which is an involved process and demands someone with programming skills. The process to take an existing website design and implement it in Plone requires a good knowledge of Plone theming engine, and usually the ones most skilled to create the design are the least skilled to implement it in Plone.
But what if you could make your Plone look like any website design knowing only basic HTML/CSS skills? Well, there is a tool available that lets you do just that. Deliverance is a middleware service that sits in between your Plone site and your website design. The website design template can be any arbitrary HTML/CSS - there's nothing Plone specific about it. This talk will give clear examples of how to get started using Deliverance to cut down your Plone theming from days to hours.
3. jazkarta
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
3
6. jazkarta
What is Deliverance?
• Middleware tool that serves as a proxy
• Maps content HTML into design HTML
• Keeps presentation separate from content
6
27. jazkarta
Deliverance benefits
• web designer doesn't need to learn CMS templating
• separation of concerns
• theme multiple apps with one design
(trac, wiki, blog, etc.)
16
30. jazkarta
Who is using Deliverance?
• Harvard School of Engineering
• City of Albuquerque
17
31. jazkarta
Who is using Deliverance?
• Harvard School of Engineering
• City of Albuquerque
• HaiVision.com
17
32. jazkarta
Who is using Deliverance?
• Harvard School of Engineering
• City of Albuquerque
• HaiVision.com
• ploneconf2009.org (get the buildout!)
17
33. jazkarta
Who is using Deliverance?
• Harvard School of Engineering
• City of Albuquerque
• HaiVision.com
• ploneconf2009.org (get the buildout!)
• and many others...
17
42. jazkarta
HaiVision
"Replace our custom backend with Plone CMS."
"Sure, we can do that."
Jazkarta
"Keep the frontend design the same."
HaiVision
"No problem."
Jazkarta
22
43. jazkarta
HaiVision
"Replace our custom backend with Plone CMS."
"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
ourselves."
HaiVision
22
44. jazkarta
HaiVision
"Replace our custom backend with Plone CMS."
"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
ourselves."
HaiVision
"Umm. Ok, you will be able to do that."
Jazkarta
22
49. jazkarta
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.
26
50. jazkarta
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
27
53. jazkarta
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)
28
54. jazkarta
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
28
56. jazkarta
4. Identify the CSS selectors of the elements in the
Plone site that we wish to map to the static
theme.
29
57. jazkarta
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.
29
58. jazkarta
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
29
59. jazkarta
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
29
61. jazkarta
1. Check out and run
the demo buildout
svn co http://svn.plone.org/svn/collective/deliverancedemo/trunk/ dd
cd dd
python bootstrap.py
bin/buildout -v
Run the bootstrap command and run the buildout
This will install Deliverance and it's dependencies (lxml)
and install a Plone site at /Plone
31
62. jazkarta
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
32
66. jazkarta
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
35
69. jazkarta
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.
37
74. jazkarta
The "plone" rule class
<rule class="plone">
<!-- Theme -->
<theme href="/static/index.html" />
<!-- Put your rules below this line -->
</rule>
</ruleset>
40
78. jazkarta
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>
44
79. jazkarta
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
45
91. 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.
49
101. jazkarta
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>
55
110. jazkarta
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
60
113. jazkarta
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.
62
115. jazkarta
Append the id/class
attributes from the body tag
<append content="attributes(id,class):/html/body"
theme="attributes:/html/body" />
Here is an example from the Haivision site:
<body class=”section-products template-document-view”>
64
116. jazkarta
Drop the right column on
pages with a particular
template
<drop if-content=".searchPage ||
.template-login_form ||
body.template-mail_password_form ||
.template-default_error_message"
theme=".col2" />
65
124. jazkarta
Place the portlets in order
<replace content="children:/html/body/div/table/tbody/tr/td/div/div[1]/dl/dd"
theme="children:#leftboxpink" />
<replace content="/html/body/div/table/tbody/tr/td/div/div[2]/dl"
theme="children:#leftboxpurple" />
<replace content="/html/body/div/table/tbody/tr/td/div/div[3]/dl"
theme="children:#leftboxgreen" />
We don’t know the name of the portlets, so we use XPath.
69
126. jazkarta
One replace rule to
embed the menubar
<replace href="/static/menubar.html"
content="children:#menu"
theme="children:#menu" />
71
127. jazkarta
Copy the edit bar
<prepend content='div.contentActions'
theme='#body-content' />
<prepend content='#content-views'
theme='#body-content' />
72
128. jazkarta
Make sure all the proper CSS
and Javascripts get imported
<prepend content="link[href *= 'authoring']"
theme="link[href *= 'style']" />
<append content="link[href *= 'public']"
theme="children:/html/head" />
<prepend content="/html/head/style"
theme="link[href *= 'style']" />
<append content="/html/head/script"
theme="children:/html/head" />
CSS files need their settings change from the default 'import'
to 'link' in order for the rules to work
73
131. jazkarta
PyQuery
for link in doc('#menu a'):
li = doc('<li></li>')
link.after(li)
link.remove()
li.append(link)
76
132. jazkarta
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
77
138. jazkarta
Deliverance vs
XDV/Diazo
• Both use CSS selectors or XPath
• Deliverance
• <replace theme="#main" content="#portal-content > *" />
• XDV
• <copy css:theme="#main" css:content="#portal-content > *" />
78
139. jazkarta
Deliverance vs
XDV/Diazo
• Both use CSS selectors or XPath
• Deliverance
• <replace theme="#main" content="#portal-content > *" />
• XDV
• <copy css:theme="#main" css:content="#portal-content > *" />
• Can combine multiple themes without Apache magic
78
140. jazkarta
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 (HTML, CSS,
rules.xml) through-the-web
79