http://plone.org/documentation/faq/plone-3-theming-errata

These will all be sent off to Packt to be incorporated in future versions of the book. (They are printed on demand, so hopefully the errors will be resolved quickly for those of you who are slower to place your orders.)

Please refer people to this list of errata, soon to be available prominently in the documentation section of plone.org, and if you've got errata of your own to submit, please send them on to veda@onenw.org.

Thanks!

$ paster create -t plone3_theme

It should read:

$ paster create -t plone3_theme plonetheme.mytheme.

Also, where it says:

Enter project name: My Theme

It should read:

Enter project name: plonetheme.mytheme

Package names shouldn't have spaces or hyphens in them, as buildout can't read them correctly. Fun with Plone!

http://tr.im/p3theming or http://www.packtpub.com/plone-3-theming-create-flexible-powerful-professional-templates/book.

It's worth noting that the webpage on Packt has some incorrect information, but will hopefully be updated soon. There are actually 15 chapters, not 11. The content of the book is mostly as stated on Packt's website, but what is not listed is the last chapter, which is the much-anticipated sneak peek into the world of rules-based theming, written by Alexander Limi.

I'd like specifically to thank Steve McMahon and Denys Mishunov for their efforts as my editors, and of course, Alexander, for contributing a chapter. I hope you all enjoy it, and if you have any errata to submit to me, please do! Happy reading!

Thanks,

- Veda

http://www.packtpub.com/plone-3-theming-create-flexible-powerful-professional-templates/book

I know that I've promised a chapter on Deliverance, and if Alexander Limi is able to get it to me in time, it will be included. If not, there will be information posted on plone.org soon. Thanks everybody for your patience and support!

Cheers,

- Veda

As many of you know the new theming for Plone book is coming out in May of this year. Packt is offering special discounts for ebooks and preorders, detailed here:

http://www.packtpub.com/plone-3-theming-create-flexible-powerful-professional-templates/book

This book summarizes three years of knowledge-gathering that will hopefully save new themers some pain. For those who are wondering, yes, Deliverance will be covered by Alexander Limi, in addition to all of the other bits and pieces new themers need to know. The table of contents is somewhat in flux at the moment, but that should be formalized shortly.

Enjoy, and thanks!

- Veda

http://www.packtpub.com/plone-3-theming-create-flexible-powerful-professional-templates/book

Be forewarned that Packt does not have the final list of chapters here, and there are some other minor errors that need to be corrected. It's available for pre-order now, due to ship in May 2009. Enjoy!

You can now pre-order your copy of the book here:

http://www.packtpub.com/building-plone-websites-through-the-graphical-interface/

Please note that although Packt has listed the book as Plone 3 TTW, it's final title is Practical Plone, a Beginner's Guide to Building Powerful Websites. The chapters featured in the book will include:

1. Introduction - Jon Stahl
What is a CMS? What is Plone, and where did it come from?

2. Installing Plone - Steve McMahon
Learn how to get Plone up and running on Windows, Mac OS X, and Linux.

3. A brief tour of Plone - Tom Conklin
Get an overview of Plone's user interface and key features.

Part 2 - I want to...

4. Create Web Pages - Sam Knox
Learn how to create and publish web pages with Plone's built-in visual editor.

5. Add News Items, Events and Other Content - Tom Conklin
Learn about the other standard content types, such as news items, events, and files.

6. Structure the Content in My Site - Tom Conklin
Learn how to use folders and Collections to structure your content.

7. Safely Manage Different Versions of Content - Darci Hanning
Understand Plone's built-in versioning features.

8. Delegate Content Management to Multiple Users - Tom Conklin
Learn how to create users and groups and give them permissions over various parts of your site.

9. Manage Approvals and Other Workflow for My Content - Matt Bowen
Customize your security model by creating workflow.

10. Show Additional Information to Users and Site Visitors - Jon Stahl
Learn about Plone's Portlet features.

11. React to Changes in the Site Automatically - Alex Clark
Build intelligence into your content management with Content Rules.

12. Control My Site's Configuration in Detail - Alex Clark
Detailed explanations of the various Plone control panels.

Part 3 - Now that I've got the basics, I'd like to learn how to...

13. Preliminary Steps: Setting Up an Environment - Clayton Parker
Set up a development environment with various debugging tools.

14. Find and Install Add-ons That Expand Plone's Functionality - Steve McMahon
Learn how to find and install add-on components that are freely available online.

15. Build Forms - Jon Stahl (with Steve McMahon)
Create web forms quickly and easily.

16. Create New Content Types - Matt Bowen
Create custom content types to capture and manage specific information.

17. Customize Aspects of Plone - Veda Williams
Learn how to customize Plone's various UI components.

18. Change the Look-and-Feel - David Convent and Veda Williams
Create a custom theme for your site.

Part 4 - My boss wants me to...

19. Put My Site Live - Steve McMahon
Learn how to configure a live Plone server.

20. Make It Go Faster - Ricardo Newbery
Configure a web cache to make Plone faster.

21. Connect to our LDAP/Active Directory Repository - John DeStefano
Let your users log in with their existing usernames and passwords by connecting to an existing LDAP/Active Directory server.

Huge thanks to everyone who has participated, including the authors above and our last-minute editors:

Jon Baldivieso
Andrew Burkhalter
John DeStefano
David Glick
Calvin Hendryx-Parker
Sam Knox
Erik Rose

and of course, many thanks to the fantastic Martin Aspeli, who started this project.

I'm personally thrilled to have been part of this process, and hope this book fills an important niche. Please show your support to the Plone Foundation (which will get the royalties associated with the book) by picking up a copy, and please help us promote it over the coming weeks and months.

Thanks!

- Veda

Let's look at this code for a second:

‹?xml version="1.0"?›
‹object›
‹order manager="plone.portaltop" skinname="Dogwood Theme" based-on="Plone Default"›
‹viewlet name="plone.path_bar"/›
‹/order›
‹hidden manager="plone.portaltop" skinname="Plone Default"›
‹viewlet name="plone.path_bar" /›
‹/hidden›
‹/object›

My goal is to hide the default Plone breadcrumbs and replace them with my own viewlet, which is customized to have >> instead of an arrow dividing the crumbs.

WHAT CODE GOES HERE?
--------------------
First, in your viewlets.xml, you only want to include the pieces of information that is changing. You don't want to grab the entire CMFPlone/Profiles/viewlets.xml file. That's because we are basing our skin off of Plone Default (or you should be), and it knows that the CMFPlone profile is the base profile. The next section explains how you correctly specify this.

FINER POINTS ABOUT SYNTAX:
--------------------------
Notice that the items I'm showing (order manager) says the name of my skinname, based on Plone Default. Unless you have a good reason not to, you should always specify the skinname and say that it's based on Plone Default.

When I'm hiding viewlets, I am generally hiding Plone default items, not anything from my skin, so the syntax is slightly different between order and hidden managers.

WHAT'S MY SKINNAME?
-------------------
The skinname in viewlets.xml needs to match the one in skins.xml, profiles.zcml, and the configure.zcml file where the IThemeSpecific layer is defined. Considering that there are a lot of pathnames running around, it's easy to get confused. I rely on the skinname that's specified in configure.zcml, where my IThemeSpecific interface is registered, because I know that it's generated automatically by my theme recipe and therefore probably correct.

HOW DO I GET MY CHANGES INTO MY SKIN?
-------------------------------------
Say you've got a highly customized theme. Your theme might even be tied into some additional products, such as a profile product. Things can get a little delicate here, and it becomes increasingly more dangerous to reinstall your theme product to see the changes you expect to see -- especially on a live site! In this case, what you want to do is go to portal_setup in the ZMI, click on the import tab, and select the Profile you wish to import from. THIS STEP IS VERY IMPORTANT. Choose the name of your theme, select the "viewlets" option to import, and import the selected step. Assuming all goes well, your GenericSetup will be re-read, and your viewlets will move accordingly.

WHY IS IT STILL NOT WORKING?
----------------------------
I followed exactly this process, and yet my viewlets were not going where I expected to see them. I wanted my breadcrumbs to display in the portaltop area, but they refused to budge. Upon opening configure.zcml, where my breadcrumbs viewlet was defined, I realized the problem:

‹!-- The breadcrumbs --›
‹browser:viewlet
name="plone.path_bar"
manager="plone.app.layout.viewlets.interfaces.IAboveContentTitle"
layer=".interfaces.IThemeSpecific"
class=".viewlets.PathBarViewlet"
permission="zope2.View"
/›

Do you see it? I had specified the manager as IAboveContentTitle, when I should have made it IPortalTop. Viewlets.xml doesn't *really* control where your viewlet goes. The actual definition happens in configure.zcml (this is what tells Zope that your viewlet exists), but viewlets.xml needs to talk to that file for viewlet ordering / showing to work correctly.

If you changed your ZCML like I did, don't forget to restart your Zope or use plone.reload!

WAIT, IT'S *STILL* NOT WORKING!
-------------------------------
Assuming your viewlets.xml, configure.zcml, and viewlets.py are all correct, only one other thing could be wrong. Usually at this point you've tried to hide / show your viewlet a couple of times, and the GenericSetup is getting a little hairy under the covers.

Unfortunately, removing a viewlet from a manager doesn't unhide it. If you've been trying to hide / unhide a viewlet, it doesn't know how to remove that item from the "hidden" list. I've heard rumors that a "purge" command for GenericSetup would work, but I could never get it to work for me. The answer at this point is, use @@manage-viewlets and use the Show link TTW.

ERRORS TOO?
-----------
Every now and then, I also wind up with a typo in my viewlets.xml. Usually, it's something lame like forgetting to close the ‹/object› tag, and when I import my xml file, I get a rather obtuse error:

AttributeError: 'ViewletSettingsStorage' object has no attribute 'getPhysicalPath'

It's scary at first, but once you realize it's saying you have a typo, it becomes easy to resolve.

Whew!

It's dumb, and it happens to me constantly, but there are a few things I occasionally forget when trying to override a portlet:

1) If you get an error like this:

File "/opt/zope/buildouts/otis/src/plonetheme.mytheme/plonetheme/mytheme/browser/configure.zcml", line 51.1, unbound prefix

Add the xmlns:plone="http://namespaces.plone.org/plone" namespace to the top of your browser/configure.zcml file.

2) Before your portlet override code, make sure you add this snippet:

‹include package="plone.app.portlets" /›

3) Watch your path back to plone.app.portlets.portlets (note the double mention of portlets). You're walking through a folder structure, and portlets are nested a little deeper than viewlets. As for the "navigation" bit in the portlet= assignment below, that refers to navigation.py (a file, not a folder), and INavigationPortlet is an interface defined in that file.

‹plone:portletRenderer
portlet="plone.app.portlets.portlets.navigation.INavigationPortlet"
template="navigation.pt"
layer=".interfaces.IThemeSpecific"
/›

4) Note also that we're using the portletRenderer directive for overriding portlets, rather than the portlet directive that you find in existing (Plone default) portlets.

Today: beware of using the wrong version of Subversion. I recently got a new IMac, and in setting up my development environment, I grabbed Subversion 1.5. This isn't a bad thing in itself -- the problem is that our svn repository uses 1.4, and it took me several hours to back down to 1.4 before I could start making checkins again. A rather unfortunate experience, given that we had a high priority project that had to roll out. Lesson learned, 2 years added to my life.

Don't forget to check out the Weblion blog that explains how you can get around some Python ugliness involving Subversion 1.5 (in the event that you do indeed have the right version of svn on your own repo): http://weblion.psu.edu/news/subversion-1.5-has-landed

- Veda