• documentation, best practices, sample base theme

  last modified August 22 by vedawms

Note that the overarching goal here is to provide top-of-the-line themes for Plone that follow all of the current best practices. PLEASE follow the conventions below and ask if you need help.

Relevant documentation

David Little has kindly been collecting a list of it here: http://del.icio.us/reynard71/plone3. If anyone has additional documentation they'd like to see flagged, please mention it to him. The Plone3 Theming Manual on plone.org is especially good, as are these two tutorials by David Convent:

http://plone.org/documentation/tutorial/customizing-main-template-viewlets

http://plone.org/documentation/how-to/override-the-portlets-in-plone-3.0

Where to store your themes (svn repository)

Unless anyone has objections, we should be storing our themes in the plone.org svn repository. To gain access to the repository, go here: http://plone.org/development/info/write-access-collective

Adding your product as an egg on PyPi

Please do this! It's the best way to get your theme found on plone.org.

When you create a product on plone.org you can define a remote URL, this is where you'd specify the remote URL on PyPi. For an example, have a
look at: collective.contentleadimage[1] as an example (just a random one I found on plone.org).

It can be uploaded to http://pypi.python.org/pypi by doing the following:
python setup.py egg_info -RDb "" sdist bdist_egg register upload

See also the instructions at http://pypi.python.org/pypi 

Adding your product to Plone.org

1. Go to http://plone.org/products, and make sure you are logged in
2. Click "Add new project"
3. Enter the details for your theme, and make sure you select "Visual
themes" as your category.
4. Save the form, and submit the project for approval. This is to
avoid people creating bogus projects, you can add your files once it
has been approved.

Example themes for best practices:

http://svn.plone.org/svn/collective/webcouturier.hosting.theme/trunk/
http://svn.plone.org/svn/collective/webcouturier.icompany.theme/trunk/

Check the readme to see all of the neat things you can do. These two have some neat bells and whistles.

Skeleton theme best practices:

  • Write a readme! We are assuming that most people downloading these themes are not Plone experts, and they should be able to figure out how to install and configure it based on your readme. Again, see the webcouturier theme readmes for an example. Feel free to document that your themes have been tested as part of the OOTB process, and you can reference this site if you want. Sample readme1 . Sample readme2 .
  • Make sure that the install.txt is up to date. If you are releasing your product as source and as an egg, you need to provide information on how to install the source product. Most of the autogenerated install.txt text for eggs is sufficient.
  • For those of you using tableless, this product has been endorsed by many. Please mention it in your readme if you use it:
    • http://plone.org/products/plone-tableless
  • We are going to be using the endorsed and approved way of generating themes with ZopeSkel. I.e:
    easy_install ZopeSkel
    paster create -t plone3_theme
    Answer all the questions (including naming your theme plonetheme.mythemename and ensuring the toplevel package is called plonetheme and your package is called mythemename)
We're not being literal about calling it "mythemename", by the way. Please follow the capitalization conventions noted above.
  • A number of people write their themes by building on top of public.css and base.css (and other .css files that the current paster theme overrides). To keep the greatest consistency, I'd like to ask that people consider not overwriting these stylesheets, though ultimately it comes down to personal preference. What we lose by overriding these is the contents tab view and a variety of deep styling that you don't normally see. Please be diligent and try not to lose some of the cleanliness that these stylesheets offer us.
  • Please clean up your site maps. This always gets forgotten.
  • All stylesheets should support dtml out of the box. Please reference the ploneCustom.css file to find the right syntax you need to make this happen, and make sure your stylesheets are named .dtml at the end.
  • If you choose to override the base Plone stylesheets, please do this by editing profiles/cssregistry.xml instead of by dropping empty files into the styles directory.
  • Avoid any changes to main_template. If you have a situation where you feel there is no way to adjust your skin except by using main_template, email the list and someone will assist. We want to rely on the usage of viewlets and browser views to achieve the desired results. Otherwise, just document what you've done.

Testing your themes

Please try to test them yourself first, and then I (or multiple people) will test them for you. Just announce it to the OOTB list and we'll get it in the pipeline.

General CSS guidelines:

  • For every skin, set generic styles for .portlet and similar items in case something gets rendered that doesn't have specific styles set for it -- ie a new portlet the client might add. If a skin has different-sized portlets for the left and right sides, and it has fixed width portlets, set styles for #portal-column-one .portlet and #portal-column-two .portlet, etc. Go from general to particular - make the general portlets' styles and then
    make special styles in case you want to do something special for a particular portlet.
  • We will not be providing support for 3rd party product styling.
  • If you're going to minimize use of dtml in the themes, be consistent. Optionally, you can document colors used at the beginning of the stylesheet:

    /* COLORS
    #025240 - dark green body background, h1 - rgb(2, 82, 64)
    #357565 - med green portal siteactions background - rgb(53, 117, 101)
    #417D6F - dark green breadcrumbs - rgb(65, 125, 111)
    #B8B8B8 - grey headline background - rgb(184, 184, 184)
    #00407A - dark blue (eg. logo blue) portlet header, h2 - rgb(0, 64, 122)
    */
  • If you're going to use color-definitions like #FFFFEE, do that consistently rather than occasionally use the abbreviation #FFE. Just be consistent.

    Browsers we will support and related issues

    • Skins must play well in all of the "A" list of supported browsers: http://developer.yahoo.com/yui/articles/gbs/index.html excluding Windows98, as it is not long for this world.
    • If you have additional browsers, IPhones, etc., please test your theme against that as well, but at the very minimum, we need to support the browsers listed above.
    • The site should play well on screen media like regular monitors.
    • The site should print properly. This means no unnecessary elements in printing - pure content. I don't think this is a good idea to put any background
      colors for printing (a lot of beginners try to do this) because most of the settings you have for printing by default in your OS'es and browsers disable background images and colors printing. At least this is not less than 50% setting I think. So the printing should be pure content without any attempts for fancy stuff I think. print.css.dtml is the place to manage this. So it's enough to remove unnecessary elements from printing just by customizing print.css.dtml in your theme and hiding elements you don't really need.
    • The site should play well with the presentation styles. This is the "presentation mode" you see when you first install Plone 3.0. It's rarely used, but we should still properly style this feature if we want to make professional themes.