Gloss - Build a dynamic site by assigning content areas to your static HTML theme

What if you could make a static HTML page into a living breathing dynamic site simply by "tagging" sections of your page as dynamic? Gloss aims to be just that, simply "tag" or "assign" sections of your static page with special gl- css classes and it will magically transform into a dynamic site. Currently we built Gloss as an extension of the Plone CMS and it has changed the way we look at the design/prototype/build workflow.

Here's a short video explaining Gloss.

For more information about Gloss visit the documentation page at http://the-gloss-project.readthedocs.org

Introducing the Diazo Snippets Library (and less Arcane)

TL;DR.

Roughly a year ago today, I wrote a blog post entitled "Diazo theming is great, now we need a snippets library". It is therefore somewhat appropriate that I am able to reveal my first simple attempts at addressing the snippets library problem in a blog post almost exactly 1 year later.

update April 16, 2015:  Now available as a Chrome Extension

A Diazo Snippets Library

One year later to the day, we now have a basic Diazo snippets library. You can check it out at http://pigeonflight.github.io/lessArcane/.

Not much to see, but it scratches an itch I've had for a while. The library makes it possible to locate useful Diazo rules snippets, filtered by different categories, not much more yet.

Background

It all started with Gistbox

To pull this off, I first started aggregating snippets from around the web in Gistbox and also solicited help from others to submit their own snippets.

After shopping around a bit I came upon Gistbox which supported the idea of groups. So I set up a group for Diazo snippets.

The drawback with using Gistbox groups was that the snippets were only available to persons who joined the group. I wanted them to be more public so I set about working on a way to export the snippets. It turns out that Gistbox passes around their data in JSON format, so I was able to "sniff" out the JSON data and export it as a data file.

A new Open Source JS library is born (kinda)

With the help of front-end developer and GIS man +Rhys Allister I set about putting together a static system for displaying the Diazo snippets based on the outputted JSON. From that work we developed a very alpha library with the working title "less Arcane".

One nice spin off of the collaboration with Rhys is that we now have the beginnings of a generic library which can be used to display JSON retrieved from Gistbox.  I like that, being straight JS, it is cheap and trivial to deploy.

Check out Diazo Snippets Library here:  http://pigeonflight.github.io/lessArcane/

Check out the lessArcane Library code here: https://github.com/rhysallister/lessArcane.

Diazo theming is great, now we need a snippets library

TL;DR: Diazo is how theming should be done, you can even integrate new functionality into your site via a Diazo theme but be responsible and aware when doing so. XSLT makes Diazo more powerful but can be complex, a library of useful Diazo snippets could go a long way in making Diazo more approachable.

Just checked out +Nathan Van Gheem's rethemed site. His blog post is worth reading. He basically purchased a theme and used a few Diazo rules to make it work with Plone. He even went as far as integrating Disqus into his site using only Diazo rules, no touching of the underlying CMS code.

I like.

Adding functionality to your site via Diazo is a powerful thing but be careful, if you need to switch themes you'll need to add the functionality again or risk "breaking" your site. Diazo does leave your site vulnerable to sins of omission. Leave something out of your new theme that was previously in your old theme and you've lost it (until you put it back). One possible solution is to have themes that promise a minimum implementation, e.g. all valid themes might promise to include footers, menus, themed portlets and breadcrumbs.

Diazo is really a wrapper around an XSLT engine (I hope I'm understanding it correctly), the Diazo directives hide a lot of the underlying XSLT and generally make transforming your site more friendly. However, like Nathan, I've found that taking advantage of "raw" XSLT in my Diazo themes gives me more power, the price I pay is a more verbose file. Though raw XSLT is powerful I think it adds a barrier of entry to the average CSS guy. One way to lower the barrier is to document how common transformations are achieved using  Diazo and XSLT through some kind of snippets repository.

Below is a simple example of transforming a portlet using XSLT into markup suitable for a Bootstrap 3.x based template.

Before and After: The portlet on the left has been transformed using XSLT with Diazo

And here's the Diazo rule (with lots of XSLT) used to achieve it. The resulting transformation is elegant but requires a understanding XSLT and the related XPATH if you needed to construct it from scratch.

<!-- transform all portlets -->
<replace css:content=".portletWrapper">
<div class="pWwrapper">
<div class="portletWrapper">
<xsl:attribute name="data-portlethash"><xsl:value-of select="@data-portlethash"/></xsl:attribute>
<div class="panel panel-default">
    <xsl:for-each css:select=".portletWrapper > dl">
        <div class="panel-heading">
          <xsl:copy-of select="dt/node()"/>
       </div>
      <div class="panel-body">
       <xsl:for-each css:select="dd">
         <div>
            <xsl:if test="@class[contains(.,'portletFooter')]">
              <xsl:attribute name="class">panel-footer footer</xsl:attribute>
           </xsl:if>
          <xsl:copy-of select="node()"/>
       </div>
    </xsl:for-each>
 </div>
</xsl:for-each>
</div>
</div>
</div>
</replace>

Diazo is how theming should be done. I now feel that Diazo as a theming framework is almost there*. It's good enough for persons willing to invest in understanding XSLT but will be helped along the way with a good snippets library.
* I'm aware that in some way, passing judgement like this, may oblige me to contribute somehow to the improvement of the Diazo ecosystem.

Plone Drills - Mastery through practice

Inspired from a post on performing Code Katas I would like to introduce my own spin on things. I call them “Plone Drills”. The goal is to develop a series of exercises which, if practiced regularly, will help to make Plone development a reflex for new developers.  This is about brain rewiring through practice, it also focuses on giving persons the opportunity to imitate then innovate. Finally, somewhere wrapped in all of this is a methodology for documenting processes.

The Components

A Drill

The goal is to design a Drill that lasts less than 10 minutes and reinforces a valuable skill required for implementing some aspect of Plone.

A Session

A scheduled time to practice drills. Sessions can be done as individuals but there is great value in performing them in group settings. The length of the session depends on the number of participants.

During the session a drill is repeated as many times as possible by as many participants as possible. I recommend that the drill be performed in order of experience, from the most experienced to the least experienced and then repeated. Each participant aims to become more fluent in their performance on each iteration. These are only my thoughts at the moment, think of them as a template, I'm open to improvements.

Conducting a Session

If you don't have a projector use a screen-sharing technology of your choice (or both can be implemented). Before the session, invite participants and state clearly which drills will be performed, preferably with a link to the documented drills.

A session involves the following:

• Setup - Make sure all the technology is working (projector, screenshare etc..)
• The Drills - Perform the selected drill
• Review - Discuss any important ideas or observations
• Closure - Pack up

I recommend having a cheat-sheet easily accessible for participants who are not familiar with some of the tools (e.g. buildout, git, unix terminal, bash, ssh, public private keys etc..)

I've created two drills so far, they are works in progress, see the next section for details.

Official Home for Plone Drills

For now I'm hosting Plone Drills in a Google Drive Folder. Contact me if you want to contribute a new drill.

Drills that already exist

• Install Package from Private Git Repository on Cloud based Plone Development Box
• Create new dexterity package and add to private repository

Drills I hope to create or would like to see

• Theme Template Override
• Theme Diazo Rules
• Theme GenericSetup
• Development: Add new fields to user profiles

Progress on the Plone Theming Guide

TL;DR; I'm working on a document that helps designers get started with Plone theming. It fits into the idea of making Plone more approachable. At the bottom of this post is a checklist of things needed to fuel Plone adoption.

Warning! this post will use terms like dogfooding, flexslider and Plone. Don't panic, it is mostly harmless and, apart from the current sentence, is written in a manner accessible enough for the general public.

Plone's Diazo system is, to date, the most elegant approach to theming among content management systems. In an effort to spread the Plone and Diazo love I started writing a document on Plone theming.

This really wasn't supposed to happen. It all started because I wanted to "rub together" a few quick pointers to help to get a designer up to speed with Plone theming. I assumed that there was enough Diazo theming documentation on the web that I could simply point at the correct details and they'd be on their way. Out of that exercise, this happened.

It's actually a side project, being done in my nearly non-existent spare time. After spending about two and a half weeks, the "few quick pointers" now span more than 40 pages. The document fills many of the gaps that I discovered. I'm not finished, but it's definitely taking shape and at least it provides a more structured approach to getting started.

Sliders: The Best Part

The theming document is at the stage where a motivated reader should be able to create a theme for Plone. I'm especially pleased with the section that covers rules for custom sliders and Plone carousels.

It guides the reader through the rules needed to transform the output of the common Plone add-ons collective.carousel and Products.Carousel into markup compatible with Flexslider. The principles are applicable to other sliders.

More to do

Some gaps still exist, for example there are not yet specific details on how to package a finished theme. Also I'd like to explore in more detail the best practices for bringing in Plone's dynamic functionality (JS and CSS) without "clobbering" the theme's JS and CSS.

The Vision

Plone is an extremely user friendly content management system yet it can be very overwhelming to the uninitiated. The big picture is about making Plone more approachable to the self learner. This ties in nicely with ideas from Mikko Ohtamaa, who captures his thoughts on how to stimulate Plone adoption in the diagram below.

As I tweeted recently:

... I see a core doc plus a http://patterntap.com type facility (built with Plone if we're dogfooding*) and low barrier to contribution

* Look up dogfooding (I was once shot down in class for suggesting that "dogging" was a verb :) I hope some of my former English and Communication teachers are reading this).

When this core document is completed I'd like to see a facility that makes it easy for persons to contribute snippets/recipes. Good examples are useful when you're just starting out.

My other recent side project focuses on getting started with Plone really quickly and is inline with this vision of making Plone approachable.

The Checklist

If the Plone community can be excellent in these areas, Plone adoption will take off.

• Improved theming documentation and ready made themes
• Make getting started with development easier (I'd like to hear more about Plone IDE)
• Product Bundles (distributions of Plone that address different markets, ftw.inflator is looking good for this.)
• An easy way to deploy finished code into production 

Get Plone Themeeditor Up and Running in 15 minutes or less

Assuming you start with a working buildout (I recommend downloading the unified installer to have this setup for you)

Steps to get an instance of Plone Themeeditor up and running quickly:

1. If you don't have an instance of Plone yet, download and Install Unified Installer
2. Edit your buildout.cfg so that plone.app.themeeditor is in the eggs and zcml and zope.schema is pinned to 3.6.0 (see the snippet below). Then rerun buildout (bin/buildout)

*note: the zcml slug is needed, even though plone.app.themeeditor has an autoinclude in its setup.py (still trying to figure why).

[buildout]

...

eggs =

plone.app.themeeditor

zcml =

plone.app.themeeditor

[versions]

....

zope.schema = 3.6.0

About Themeeditor

Plone Themeeditor (plone.app.themeeditor) is a tool that helps to simplify the way that Plone themes are built and distributed. It aims to make life easier for the designer.

AntHill Skinner, yet another theming approach for Plone

Anthill Skinner is another approach to theming Plone, developed by Simon Pamies of banality.de. It is inspired by collective.skinny and collective.editskinswitcher It claims to be easy..."er".

It provides utilities to create a nice public facing theme while relying on the default Plone theme as the administrative "backend" interface. This approach allows a developer to quickly create a front end, without being contrained by some of the considerations associated with being compatible with the plone publishing tools. Instead the publishing tools exist in a familiar, consistent and well thought out, default Plone UI.

For scenarios where there are a few contributors and the site is largely aimed at anonymous visitors, anthill.skinner is good enough (tm). The traditional Plone approach is important for membership sites where users are expected to log in and see the same look and feel as when they are logged out and anthill.skinner won't replace that use case.

AntHill Skinner Tools

Tools that will help to simplify your anthill.skinner theming experience:

• anthill ZopeSkel template – I created a custom ZopeSkel branch which includes a plone3_anthill_theme template to help you get started quickly (still very alpha).
• GloWorm – quickly identify the full path to a viewlet, useful when customizing and you need to reuse an existing viewlet.
• Buildout – This will simplify the setup, the instructions below assume familiarity with buildout.
  

The fastest way to get started is to use my customized branch of ZopeSkel which makes it possible to generate an anthill theme.

Checkout the anthill ZopeSkel branch:

cd $YOURBUILDOUT
svn export http://svn.plone.org/svn/collective/ZopeSkel/branches/anthill_skinner/ src/ZopeSkel

Add ZopeSkel to your buildout.cfg

(It is important to add the src/ZopeSkel line.)

develop =
 src/ZopeSkel
eggs =
...
ZopeSkel

Then re-run buildout

bin/buildout

Now you can create your theme. Remember to locate it in the 'src' directory of your buildout. Leave out the --svn-repository command if you don't want to have the project managed by subversion.

bin/paster create -t plone3_anthill_theme \
       mytheme.example --svn-repository=http://myrepo.mycompany.com/svn/{projectname}

Answer all the questions and you'll have an anthill ready theme.

Remember to move the resulting theme to the 'src' directory of your buildout.

Now edit your buildout.cfg to resemble what you see below, note the use of 'z3c.autoinclude' as a part of the eggs section:

develop =
     ...
     src/mytheme.example

eggs =
       ...
       mytheme.example
       anthill.skinner
        z3c.autoinclude
       anthill.tal.macrorenderer

 zcml =
       ...
       mytheme.example
        anthill.skinner
      

Then run

bin/buildout

Installing the theme

Go to the ZMI of your plone instance > portal_quickinstaller.

1. Install anthill.skinner first
2. Install your new theme

update: one "gotcha", before the public view of my newly installed theme would work as advertised, I found that I needed to restarted zope/plone.

Customizing the theme

When you first generate and install your theme, the public view (what an visitor sees) will look like this.

The administrator will standard plone (note the ability to "Show preview", which allows an admin to see the public view:

When registering your skin via profiles/default/skins.xml, note that 'portal_skins' default_skin will be "Plone Default" NOT the name of your theme (this is the default behaviour of the anthill paster template).


Most of the rest of your work will be focused on customizing the 'skins/...custom_templates/main_template.pt' and stylesheets, this is discussed on the anthill.skinner page.