How to use paster: This tutorial is housed here temporarily until an overview document can be written that explains to themers that in order to build a theme, they need to create a buildout and install the various dependencies. At that time, this document can be untagged for this section, and the overview document should flag this as a related resource.

What Controls What you See: This tutorial is an update from the original 2.5 doc. It is in pretty good shape, but I know the logo section needs to be reworked and that a lot of comments need to be integrated. Consider combining or referring to the canonical tutorial on how to change your logo. (Coincidentally, these need to be looked at more closely.) Review this document more closely to see if other areas need to be improved. This is an important low-hanging fruit.

DIYPloneStyle: Creating a Custom Style for Plone: This tutorial is an excellent example of what needs to happen in this tutorial: http://plone.org/documentation/tutorial/genericsetup-plone-theme. We need to pay special attention to things like resources, skin layers, etc.

­Creating a Custom Skin: This would need updating to get it to 2.1 status and possibly duplicates some of DIYPloneStyle. However it is a good example of structure - basics -> installation -> debug -> examples -> troubleshooting

Creating Plone Skin Products with PloneSkinDump: This is a third party product - there seems to be a Plone 3.0 in the svn trunk (last commit in July 08) - but the tutorial is only relevant for 2.*. Should this be in the documentation section of the product itself?

Using the Resource Registries to control CSS and Javascript: This tutorial is strong but should be reviewed to see if has changed in 2.5. We should make updates within this doc and call out caveats rather than overwriting old information. Yes, I would like to see more information on setting conditions - more examples for non-programmers and how to adjust settings with generic setup and profiles.

Working with CSS: Some aspects of this would be relevant to 2.5. This covers all the basics for customising TTW. It would be great to expand this with more information on using CSS within a theme product, also how to add CSS to the registry and set conditions for these (see note above). How to register via profiles. Generated CSS. What's the future of DTML?

How To Use sIFR To Do Font Substitution: This document is good, but needs to be updated for the newest version of sIFR and also needs to include any caveats learned from the Dogwood Project. Punting to Jon Stahl for updates, Veda to contribute.

Logo

Center the Logo: The How To itself is relevant only to 2.0, the comments bring it up-to-date - though need checking. Needs rewriting or incorporating into a bigger document (or is it an FAQ - how do I center the logo?).

Change the Logo: This is a really fundamental thing that has clearly caused problems - by the number of comments. Really important to bring up-to-date, incorporate the comments and include a troubleshooting section. (or is this documented elsewhere?).

Change the Logo on for the front page only: There's a typo in the title. There is some basic information in the comments for Plone 3, but needs expanding, since the logo is now a viewlet, not just a template.

Randomize the portal logo: Would it be better to incorporate this into a tutorial on randomisation techniques - with information too on how to cope with caching? Note also the tutorials on random portlets, the tutorial on embedding a random quote in and the random option in the collection portlet.

Split the portal logo: This is more a tutorial on techniques, how to use DOM Inspector to find out what you need, how to customize a template and how to customize css. A kind of "Hello World" example.

Switching Skins and Handling Themes

General Thoughts

Doesn't seem that anyone really knows how to do this. There are a number of different use-cases - needs thinking through. Eg just change a few colours (custom properties or custom stylesheets) or micro-site with different viewlets, editing versus visitor themes. Usjng CSS registry or marker interfaces or just dropping templates etc into the folder.

Priorities

1. At least get the Switching Skins tutorial annotated for Plone 3.
   

Comments on individual documents

Switching Skins - this seems to be the core documentation on this topic and possibly Selecting a Skin Based on a URL and Set Skin for folder could be absorbed into it (it references one of them, but not by the correct title). It isn't clear to me whether these methods would work for Plone 3, so it needs testing, plus we probably need to clarify the 'skin' / 'theme' terminology that's emerged in Plone 3. I'd like also to know what the implications are for caching and is it still possible for individual users to set their own skins?CMFUrlSkinSwitcher is mentioned, but seems to have superseded by http://pypi.python.org/pypi/collective.editskinswitcher/ - so I wonder if it would be worth mentioning this somewhere. Key tutorial for updating in this topic area.

Selecting a Skin Based on URL: The method here needs testing - I suspect works really only for 2.0. Perhaps the authors of CMFUrlSkinSwitcher could give advice. Absorb into Switching Skins tutorial or flag as 2.0 only.

Set skin for folder: This method has good feedback in the comments. But is it appropriate for Plone 3? Maybe flag as 2.0 only or absorb in Switching Skins tutorial.

Create a different look and feel: This tutorial needs a formatting tidy up as well as a review. There are a number of cries for help about how to get this to work for Plone 3, so an update is required. This is a use case which overlaps with CSS registry techniques (and possibly viewlet configuration - can this be placeful - I don't know ? - but there may be scope for a section in the theme reference manual indicating how to hide a viewlet under particular circumstances). Has Penn State done any development in this direction?

Change the look and feel of a folder and its subfolders using a customized version of main_template - is this still recommended?

Portlets

General Thoughts

There's so much information about portlets that I wonder whether it is worth separating out the sections to 1. Viewlets 2. Portlets and Slots 3. Navigation. Would there be a way to indicate the version number on the listings themselves (and possibly sort by version number) rather than having to click through to the document itself to establish whether it is relevant?

I also think that portlets might need an introductory overview, explaining the difference between Plone 2 and Plone 3 portlets and guiding the user through the range of documentation available. -> TTW configuration in 2 -> TTW configuration in 3 -> generic portlet types -> Plone 3 portlet customisation -> Instances of Plone/2 Classic Portlets. Clearly this ranges from user / integrator documentation to themeing documentation to development documentation. (possibly in the theme reference manual)

For the theme reference manual, I'm thinking about a portlet decision tree - when do you need to subclass, when just replace the renderer, when simply use the configuration options. ... needs thought and working out on paper.

Possible Priorities

1. Current documentation groups both portlets and viewlets together. Worth thinking about whether they should be separated.
2. Need some basic information on the new portlet infrastructure in Plone 3 and fact that most of the 2.1 portlets described in the how tos (e.g the weather portlet) can be redeployed as classic portlets. (maybe each howto/tutorial needs comment at the top to that effect).
3. Adding Slots - cross reference to Adding Portlet Managers, so that Plone 3 users can see the difference
4. Gardening for comments across portlets (also see comments on individual documents below)
5. Formatting portlets - perhaps amalgamate the rounded corners tutorial and how to

Comments on individual documents

Override the portlets in Plone 3.0: This is a great doc, just needs to be checked, gardened for comments and minor evolutions. Veda to do.

Subclassing new portlets: I used this not so long ago and found it very helpful.

Adding Portlet Managers: I recently used this and found it extremely helpful. It would be good to incorporate some of the suggestions in the comments especially 'i think it could be very useful to expand this howto to the case where someone is making a plone3_theme with paster and to the an other one to add portletmanagers to the main_template' (there are cases where you don't want to position your portlet manager inside a viewlet manager but actually directly in a template) and also the reference to using the IColumn interface.

Adding Slots: This will work for 2.1. The suggestions in the comments to edit plone.py seems to me like a bad idea (what's the recommended process now for adding global variables). It won' t work at all for 3; but it would help to refer to Adding Portlet Managers and perhaps extend that tutorial to deal with a portlet manager directly in a template.

Formatting Portlets: This is a key How To - just needs checking for accuracy in Plone 3. See also the Rounded Corners Portlets - I can't comment on these as not a CSS expert.

Rounded Corners on Portlets: This is outdated but there's some useful information about CSS generally. See above

Controlling Portlets: This just needs a bit of gardening - a pointer to Plone 3 documentation and an investigation of the single comment at the bottom of the page.

How to remove portlets from Python code: title is a bit misleading - should be 'with Python code' or 'in Python code'. Could we skew this How To - so that it incorporates both the generic setup and the python code version. It might need a different title - 'Specifying Portlets'

Add PostIt Note Portlet for Notes: Just a bit of gardening to make it clearer that this can be used as a Classic Portlet

Create a Portlet to Switch between...: bit of gardening to make it clearer that this can be used as a Classic Portlet in 3.

Creating a Static Text Portlet: This needs cleaning up with a pointer to how to do this in Plone 3 to the tutorial Creating Static Text Portlets in Plone 3

Creating Static Text Portlets in Plone 3.0: This tutorial needs some gardening, there are quite a few comments and some doubts at the end about whether the product can be installed in Plone 3.0 using buildout. I think it would also be worth mentioning somewhere that the static portlet comes as standard in Plone 3.1.

Creating Portlets with editable static content: maybe some gardening. It has been flagged as out-dated - what happens to it now?

Multiple Months in Calendar Portlet: Marked as outdated - not sure how this works in Plone 3.

Navigation

General Thoughts

Should navigation be a separate section? Its a portlet ---- but......

Priorities

1. Get the customize the Plone 3 navigation done
   
2. Put a pointer to Plone 3 documentation in Creating a Flat Navigation Portlet (there's also a Penn State Product that offers a Classic portlet implementation of this)

Comments on Individual Documents

How to Customize the Plone 3 navigation (I don't have rights to see it). It would be good to get this finished - an easy target.

Creating a Flat Navigation Portlet: Needs a pointer to Plone 3 to show how this is done (possibly in How to Customize)

Viewlets

General Thoughts

Joel has suggested a tutorial to demonstrate the power of viewlets (eg ones that appear depending on permissions or interfaces; potential of dropping viewlets into the content div of the page (using above-content viewlet managers for example). How best to do this? Difficult to demonstrate without a viewlet on the file-system, or to rewire a plone viewlet without a configure.zcml. Would an overview of lesser known viewlets (like the presentation viewlet) help?

Priorities

1. Gardening

Comments on Individual Documents

Customizing the viewlets in main_template: This is a great doc but should be checked and gardened for comments and any minor evolutions (not needing to change the version # to update your site. Veda to do.

Displaying a Random Quote: This would be a good candidate for a Plone 3 viewlet.

Templates

General Thoughts

There are various subject areas covered here. The first two are fairly fundamental. Syntax etc is thoroughly covered, but supplying and manipulating content involves a number of edge cases. The third probably needs checking out - is the "theory" of alternative displays and templates explained anywhere? Are the examples given in these docs still relevant to Plone3. Is the templating of archetypes covered in the archetypes manual.

1. ZPT Syntax, macros etc,
   
2. supplying and manipulating content within templates
3. ways to apply different templates in different contexts
4. archetypes view and edit templates
   

Priorities

1. Amalgamate the two macro tutorials if required?
2. Alternative templates, perhaps add a page to the theme reference manual (some of this is end user stuff or archetypes stuff - so check whether it is there and link to it)

Comments on Individual Documents

ZPT Syntax, macros etc

Using Macros and Metal in Plone Page Templates This goes over the same ground as Marco's tutorial on ZPT (though the title of that doesn't explicetly mention macros, should it?). It has a few good illustrations, but the references are to Plone 2 not Plone 3 (do we need both docs).

CMF Expressions Are these actually relevant to templates. Possibly the TRM needs more information on TALES expressions

Supplying content to templates

Edit Zope Page Template Content through Plone Is this title a bit misleading? Is it really usable with Plone 3 - will the example given work in Plone 3

Content Type specific templates

Customising AT View Templates This is a key tutorial. It needs a bit of gardening and updating for Plone 3 (e.g. inclusion of KSS for in-place editing); CSS registry; viewlets

Making the view page of a content type use your schemata declarations Does this work in Plone 3 - KSS?

How to customise view or edit on archetypes content items Needs gardening. Actually is this two how tos in one - one about overriding the content_edit action for a custom content type, the other giving useful information about the templates ( I usually use it for the latter)

Alternative Templates

Do we have documentation on setting the display drop down (e.g. through the web as well as programmatically - e.g. using generic setup)

Do we have documentation on how to set a one-off custom template or a content type for a landing page or front page.

Add supplementary views to custom content types Still relevant but see comments above.

Using custom templates as frontpage Martin's tutorial has options for Plone 2. but see comments above

General Comments:

­

I'm thinking that where we know we have documents that need to be updated that are not large-scale tutorials like David Convent's work, we should update the tutorial within the existing (older) tutorial. However, rather than overwriting the older information, we should preserve that information or include caveats where things are different from version to version. This will have to be addressed on a document-by-document basis.

Documentation We Know We Need:

• Start Here page for theming that tells people what they need to do to get rolling; Trey Beck has started working on this and should be tapped to see if he can complete it or pass it off to someone else for completion.

• Realistic examples of how to use page templates to create new homepage view (find a few common use cases here)
• How-to on how to insert images into your TAL code (and find portal_url)
• Extra information on some of the pitfalls of reordering / hiding viewlets (http://www.404-notfound.com/blog/2008/09/reordering_hiding_viewlets_arg.html)
• Extra information on some of the common stumbling blocks around overriding portlets (http://www.404-notfound.com/blog/2008/08/overriding_portlets_common_stu.html)
• How to use base properties, reference CSS manager product (I can put some of this into the theme reference manual - anneb).
  
• How to on how to get rid of scrollbars around your searchbox (esp. in IE7). Answer is overflow:visible, and we need to get this fix into the core Plone stylesheets.

Overall List of Priorities:

1. Theming tutorial [Veda]
   
2. Change the logo tutorial [anneb]
3. Introduction to Portlets
4. Gardening portlet how tos
   
5. Finish how to customize the navigation
6. Gardening viewlets
   
7. Garden templates
8. Investigate the relevance of some template documentation to Plone 3

Theme Reference Overview