Tips & tricks

Archetypes

Ah, archetypes. How I adore thee. Other ways of constructing Plone content are as nothing before me. You are quick to develop, flexible in your approach, sensible in your defaults. But cryptic in your errors.

A lesson or two on breaking archetypes: First, not all fields accept all widgets. This is only logical - a Boolean field can't take a Multiselect widget. However, there are some other pairings that seem reasonable but are wrong. What happens in this case is that Plone prangs when trying to render the page and you end up with a cryptic message on the White Wordy Page of Error. The error clearly points to a problem in the archetype machinery and rendering, but doesn't identify which widget or field. Charming.

Equally mysterious can be the errors that occur when you accidentally have two fields with the same name.

Structured text

Structured text is a fine format ... as long as the documents do not get too complicated. Once you get text with 3 or 4 nested levels of headings, it becomes difficult to keep track of the correct depth of indentation. Once you add in lists, preformatted chunks of text and the vagarity of the documentation, it can become impossible to render a document correctly. It also appears that there may be a few bugs in the STX implementation in Zope. I've had a case where a paragraph early in a document would persistently detach from its position and appear near the end of a document. Disecting the document showed no obvious cause. I eventually rewrote the doc in HTML. Restructured text (if available) is far easier to write and troubleshoot, and is also more powerful.

Moral: simple structured text for simple documents.

An under-publicised feature of structured text is that you can include HTML commands within it. For example, instead of using the primitive image include directives in STX (e.g. "My image" :img:my_pic.jpg), you can use the more powerful HTML img command (e.g. <IMG SRC="my_pic.jpg" class="fancyframe" align="right").

[1] Well understood problems in STX

[2] Text Formatting Surprises in STX

IDs

Plone doesn't (and can't) validate all the names and ids you give to objects at creation. The wrong name can lead to odd effects. While porting a site, I recreated a file named colophon. This caused Plone to spasm and complain about template errors if anything in that file was accessed. Eventually I had to delete the file using the ZMI.

Look-and-feel

While the visual design of Plone is excellent, one place it falls down is in distinguishing the lower order headers H3, H4 and beyond, which begin to be hard to dstinguish from each other and from the general text. As an improvement, I'd suggest making H1 and H3 larger and making headers stand out as a different colour or drop shadow. For example:

h1, h2, h3, h4, h5, h6 {
   text-shadow: gray 0.1em 0.2em 0.15em;
}

h1 {
   font-size: 180%;
}

h3 {
   font-size: 140%;
   border-bottom: none;
   font-weight: normal;
}

Changes you've made in your ploneCustom.css not working when you insert dtml property directives like dtml-fontFamily? You've probably made the elementary mistake of not placing them between the dtml-with tags, which are necessary to interpret the directives:

/* <dtml-with base_properties> (do not remove this :) */
/* <dtml-call "REQUEST.set('portal_url', portal_url())">
   (not this either :) */
/* THIS WORKS */
h3 {
   font-size: 140%;
   border-bottom: none;
   font-weight: normal;
}
/* </dtml-with> */
/* THIS DOESN'T */
pre {
   color:&dtml-fontColor;
}

Miscellaneous

The CMFBibliography product is a sophisticated way of managing references. However I've had nothing but problems with it. Twice when I attempted to uninstall it, it caused an error, rendering my plone site unsuable. Caveat user.

It is almost impossible to develop and debug Zope without a decent debugger. The error messages are cyrptic enough that anyhting cou,d be hapening. On the Mac I make an alias debuzope which I define:

alias debugzope='sudo -u plone ./bin/runzope -X "debug-mode=on"'

The Safari broser seems to be very aggressive about caching. Thus changes in images and stylesheets may not immediately appear.

Conversely page template seem to be loaded straight from the disk, so you can alter the appearance of page elemnts by editing the pages without restarting or reinstalling products.