Jazkarta Blog

Deliverance: Great Plone theming, no Zope after-taste.

A bit of a misleading title.  I like Zope, I just don’t think someone should have to absorb so much of its technology stack in order to theme a Plone site.  I have been using Deliverance on a number of projects and it is has proven itself to be a big time saver versus traditional theme-as-a-product development.

Using Deliverance creates a very clear separation between tasks regarding the look of a site versus task regarding creating views for a site. Most theme strategies conflate both the CSS and layout work with the data access work. These systems have to create guards to make sure that the two aspects do not stomp on each other, usually with mixed success.

This is not to say that using Deliverance removes the need to create custom templates. Deliverance cannot help you when you need for example, to expose additional information about a piece of content, such as displaying the ‘CreationDate’ for the default view of a Page. That is still a task for template work. Fear not Plone themers, your hard earned paster and ZPT skills are still needed. What using Deliverance does is reduce the need to understand viewlet managers, ZCML, registries, Generic Setup, in order to adjust layout and visual look of a site. I mean, the amount of Zope you had to digest to make simple changes is really kind of crazy using the product method.

So if you have not yet gone down this path, you should; it can save you a good amount of time.  In the interests of saving you even more time, I will share some of the things I have run into when using Plone + Deliverance.

ZMI Access

Assuming that you have a Plone site running on port 8080 you can use the following to provide a short cut to the ZMI:

<proxy path="/zmi/">
    <transform rewrite-links="1" keep-host="1" />
    <dest href="http://127.0.0.1:8080/VirtualHostBase/http/{Host}/VirtualHostRoot/_vh_zmi/" />
</proxy>

TinyMCE

To get TinyMCE to work properly with Deliverance you need to add some additional rules to account for the pop-ups that are part of TinyMCE’s UI.

Red Turtle has a post explaining how to get TinyMCE working with Deliverance

That blog in general has some great Plone information if you have not checked it out before.

Special Cases

Special cases are rules for those templates that might not work with your existing theme template. Say my site design uses portlets that are all placed in an elements in my theme template with a class ‘.col2‘. However, there a number of default Plone templates that do not have portlet columns, so what happens is when a user hits those pages, you can run into the situation where the placeholder content from the theme is displayed.  To get around this, I created a rule for ‘specialcases’ which is used to provide a sensible fallback view for Plone’s administrative templates.  The rule below will look for the existence of particular CSS classes in the content, if they are found, the ‘col2’ element from the theme is dropped entirely, no dummy content is displayed.

<rule class="specialcases">
    <!--special cases -->
    <drop if-content=".searchPage || .template-login_form || .template-mail_password_form 
|| .template-default_error_message"  theme=".col2" />
</rule>

Hopefully over time a list of such special cases can be developed for the larger community to reuse.

Do I still need viewlets if I have Deliverance?

Maybe not.  If you just need to push a third-party widget (you know your clients ask for this) or arbitrary piece of HTML into you Plone site, it might be easier to use a Deliverance rule.

For example, we had a client recently who needed to incorporate some third party payment forms into their website.  To do this just with Plone you could do the following:

1. Disable HTML filtering enough to allow the forms to be placed within the body text (not so great of an option)
2. Create product that captures the configuration necessary to place your HTML code in the appropriate viewlet manager (overkill?)
3. Extended an existing product like PloneFormGen to talk to the payment gateway (definitely overkill)

Since the only requirement was to place some arbitrary HTML code within the context of Plone, I opted to do this using Deliverance. I created the following match declarations

<!-- pulls in the payment gateway forms -->

<match path="/donate/in-honor-of"  class="honor"/>
<match path="/donate/in-memory-of"  class="memory"/>
<match path="/donate/personal" class="personal"/>

When the request path is matched, a rule is called that appends the form to the bottom of the page, so the end user could still modify the body of the Page using Plone. All of the html forms are in a directory /static/forms that lives on the file system.

<!--donation forms -->

<rule class="honor" >
    <theme href="/static/subpage.html" />
    <prepend href='/static/forms/honor.html' content="#honorform"  theme=".documentActions" />
</rule>

<rule class="memory">
    <theme href="/static/subpage.html" />
    <prepend href='/static/forms/memory.html' content="#honorform"  theme=".documentActions" />
</rule>

<rule class="personal">
    <theme href="/static/subpage.html" />
    <prepend href='/static/forms/donate.html' content="#honorform"  theme=".documentActions" />
</rule>

Not one line of ZCML was mangled or abused to achieve the above.  I can easily test and edit the forms independently of Plone or managing a Plone package.  I probably saved hours of fighting the framework when the end goal was something that was technically simple.

Things that are just not quite right still

Yes, Deliverance is magic-pixie-dust-goodness, but there are some gotchas when using  Plone 3.

The following resources used for the editing UI :

<style type="text/css" media="all"><!-- @import url(http://localhost:8080/testplonesite/content_types.css); --></style>
<style type="text/css" media="all"><!-- @import url(http://localhost:8080/testplonesite/jscalendar/calendar-system.css); --></style>

Are output in Deliverance as such:

<style type="text/css" media="all">&amp;lt;!-- @import url(http://localhost:8000/content_types.css); --&amp;gt;</style>
<style type="text/css" media="all">&amp;lt;!-- @import url(http://localhost:8000/jscalendar/calendar-system.css); --&amp;gt;</style>

One work-around is to add these resources back is to Plone’s portal_css registry.  I would be interested to find out if there are any solutions to the above that don’t require adjustments within Plone.