Plone Developer Manual, take #0.1

The first public version of  Plone developer manual is available here.

It is still very much draft, but I assure you will find it useful. You will find it even more useful after you put in the answers for your own problems.

In my previous Plone developer documentation rant my flow of though was little abstract and I couldn’t clearly explain how I want the community to maintain this crucial piece of documentation.  This time I made a comic.

* How to get support

** How to update Plone Developer Manual

Putting views, like sitemap, into Plone content tree using Easy Template add-on

Plone has two kind of pages

• Content pages which have a path and will appear in the navigation and in the sitemap. These are stored in the database.
• View based pages and template based pages which usually present an action  (accessibility, sitemap, contact info form). They do not appear in the navigation. They are stored as source code on the file system. You cannot navigate to view based pages and just click edit. To change them you need to use various customization methods (add-on product, Zope management interface) to modify the code.

Sometimes it is desirable, for the sake of uniformness, to put view based pages (accessibility, sitemap) into the content tree. For example, one could want to have the sitemap link appearing only in the navigation tree under the site section “About this site”.

Plone add-on product Easy Template provides an easy method to show any Plone view(s) on a normal page. Easy Template uses Django like template syntax (Jinja 2 engine). It gives you great power to drop dynamic content easily on pages. Easy Template also has some security awarness ensuring the members using it cannot escape from their sandbox.

Easy Template works in WYSIWYG and non-WYSIWYG modes

• You can directly mix templates into text in Visual Editor (Kupu). This is mostly useful for non-HTML aware content editors, who use WYSIWYG editor and can use snippets from a reference card prepared by a developer. Note: Visual Editor has some limitations or undesired behavior. Sometimes it tries to put arbitary HTML tags into text (  which breaks the template code).
• You can write templatized HTML source code in “raw” mode. You can write source code on “Template” schemata in Edit view.

Example how to show a sitemap on an arbitary Plone page

1. Install Easy Template (if you are a developer I suggest you to try trunk version)
2. Create a Templated document content
3. Write some arbitary text in Kupu
4. Put in the code snippet {{ view(“sitemap”, “createSiteMap”) }} which triggers the sitemap view rendering
5. Save and view the document in View mode

It turns out to be:

There is no such thing as a “views reference” for Plone. View names and functions can be figured out by searching and reading through ZCML and Python files in Plone source tree. Some developer insight is needed. For example. for sitemap we can do the grep search:

grep -Ri --include="*.zcml" sitemap *

Then read Products/CMFPlone/browser/configure.zcml and Products/CMFPlone/browser/sitemap.py.

The same thing works in portlets. Use Templated Portlet portlet type. See Easy Template PyPi homepage for the full reference of the product’s potential.

About the author Mikko Ohtamaa

• LinkedIn
• Twitter

XHTML mobile profile transformer and cleaner for Python

Mobile phones, and especially mobile site validators, are very picky about the validy of XHTML. It must not be any XHTML, but special mobile profile XHTML. Also, search engines like Google, will punish you in the mobile search results if your site fails to conform to mobile profile.

This is especially troublesome if you display external content (RSS feeds, ATOM feeds) on your mobile site. Incoming HTML cannot be guaranteed to follow any specification.

To solve this problem, we have created gomobile.xhtmlmp Python library which helps you to transform any HTML to content to valid XHTML MP. The library is piloted on plonecommunity.mobi site which  uses aggregated content from varying sources. The library is based on lxml.html.Cleaner. The library is part of GoMobile project which aims to create world class Python mobile web development tools.

Highlights

• Turn any incoming HTML/XHTML to mobile profile compatible
• Enforce ALT text on images – especially useful for external tracking images (feedburner tracker). ALT texts are required by XHTML MP.
• Protect against Cross-Site Scripting Attacks (XSS) and other nastiness, as provided by lxml.xhtml.clean
• Unicode compliant – eats funky characters

As an example we integrated gomobile.xhtmlmp  to Feedfeeder Plone add-on product.

Enjoy.

Designing a high usability Plone theme

This is my brain dump of instructions for artists how to design good Plone themes. I hope I can receive some comments, some feedback from the artists itself and then publish this as a plone.org tutorial.

Often external artist is used to design a site theme. Artists might or might not have seen Plone, artists might or might not have any basic usability know how. This article should explain the elements which “must be there” to make a match between the theme and Plone easily.

The basic layout

This document describes the elements of multilingual high usability Plone theme. It is based on fluid div layout, meaning that the content stays very readable on small screens or when CSS is not loaded (screen readers). See the example layout.

The layout must not break down when user is using non-default font size. E.g. all element accept two rows text, even if the default case is usually one row.

Plone layout

Here we are designing a “normal” site theme where Plone is used to publish textual content for external readers. This might not always be the case – for example if Plone is used as a professional tool one might want to use all available screen space to display as much as possible action shortcuts to make the tool to quick to use. The latter is actual case I have seen in medical applications.

Plone layout is formed by seven main parts.

The layout must be designed so that

• The maximum width of content area newer exceeds a certain amount (1200px) so that characters-per-line count stays readable on wide screen displays. Left body padding and right body padding fill the wide screen gap to keep the content in sane max-width.
• Left portlets and right portlets parts can be missing, giving space to content part
• Header and footer are resizable. Usually logo is at the left site of the header and actions at the right side of the header. These sections should not overlap with the width of 780 px.
• Left body padding and right body padding can have shadow effect on the central column a la blogger.

Alternative layout cases

The layout must be formed from such a blocks that left or right portlets can be easily dropped without breaking the layout.

Right portlets missing:

Both portlets missing (front page view):

Header elements

The header should have the following elements

• Logo
• Language selector – either a drop down list, flag icons or language names
• Site action links with icons: site map, accessibility help, toggle easy read (make fonts larger), contact
• Search box
• Section (main level) navigation tabs
• Personal bar. Contains the username and log out buttons. Only available when logged in. To see an example, create plone.org account and login to ploen.org.

The header must scale between 780 – 1280 px. Section navigation tabs may trigger drop down menus, see http://www.jyu.fi/

Content area elements

The content area contains

• Content title
• Content description: one paragraph, no HTML formatting
• Breadcrumbs path bar displaying the position in the navigation hierarchy. Example.
• Content actions: send to, print, RSS feed. Icons with or without text labels. New Plone versions place these at the bottom, but they used to be at the top.
• Document byline: creator name w/link, creation date or edit date. This is usually only available for logged in members.
• Notification messages: When user performs actions (e.g. save) this feedback box is rendered with white i(nfo) letter in blue circle having a message like “Save succeeded.”
• The main body text and images

The whole portlet section can be dropped, making space for the content.

Portlets

Portlets are boxes on the left and right side of the content containing section specific actions.

Example portlets:

• Navigation

• Search (not the header search)

• News

• Recently changed

The portlet consists of

• Title (usually link)
• Content area
• Optional More link, located at the right bottom corner.

See http://www.siggraph.org/ for creative use of portlets.

Footer elements

The footer has

• Copyright clause
• Link to about page
• Contact information

The footer must scale between 780 – 1280 px.

Complete picture

Special cases

These are often required and might shoot you into a foot

• The current section (main level folder) where the user is located is identified somehow: a changing big topic picture, text. For example, see http://www.archred.com/updates/news and you see that there is big Updates title.
• To make more space available for front page or top level content, breadcrumbs and portlets are missing. A special front page animation may be used.See http://www.archred.com
• Breadcrumbs is also often disabled for top level elements
• There is a special print.css which is loaded when the document is printed. It sets display:none to porlets, header and footer so that only the main content area is printed.
• Visual editor (Kupu) text might require special CSS rules to have the same formatting rules as in non-edit mode to get real WYSIWYG.
• A special attention must be paid for the style of generic HTML elements like a, h1, h2 and p. They are used on the content area and outside it, often with different colors.

Colors

Plone uses mechanism to have color variables in CSS. See base_properties.prop to get an idea what colors there are and try to guess how they are used.

Icons

Plone uses generic icon mechanism to apply icons to any action available on site. Icons are 16×16, transparent with one pixel transparent border leaving 14×14 pixels for the content.

The icons should preferably be suitable for dark and light backgrounds. This might be hard to achieve, though, so it is suitable to use ligh background icons, since this is the Plone default.

Actions

• Search
• Smaller font
• Larger font
• Print
• Send to (email)
• Contact
• Sitemap
• Member icon
• Settings
• Log out
• Login
• RSS feed

Language flags

Plone default flags can be used

• Finnish
• English
• Swedish
• etc.

Content icons

These reflect different Plone content types

• Page
• Folder
• News
• Event
• Collection
• File

Link icons

Plone uses Javascript to apply special icons for external links

• HTTP link (globe)
• HTTPS link (lock)
• mailto link (letter)

Favorite icon

• The site bookmark icon, the one seen in the address bar, uses normal favicon.ico practices