You'll find detailed information and a tutorial on how to move viewlets here:

• http://plone.org/documentation/tutorial/customizing-main-template-viewlets/reordering-and-hiding-viewlets

Quick Cheat Sheet of the Basics

Through the Web

• Add @@manage-viewlets to your site URL.
• If you want to move viewlets that only appear on a page, be sure to append @@manage-viewlets to the URL of the page.
• You will find that you can move, hide or remove viewlets with this method, but that you cannot move them from one viewlet manager to another.

In your own product

Moving or removing viewlets is part of your site configuration:

• Add or edit [your theme package]/profiles/default/viewlets.xml

You'll find general information about the site configuration in the Configuration section of this manual. It's worth reading this through before you launch in here, as configuring viewlets and viewlet managers can be a bit tricky. It will tell you

• how you can get the Generic Setup tool to write out the configuration for you
• why things might not be working as you expect

GloWorm is a useful tool here too. It will help you move the viewlets around through the Plone user interface and inspect the resulting configuration.

Removing a viewlet from a viewlet manager

You can't do anything more than hide your viewlet in the viewlet manager

<object>
    <hidden manager="[Viewlet Manager Name]" skinname="[your skin name]">
        <viewlet name="[Viewlet Name]" />
    </hidden>
</object>

Note that you can do this process through the web and then get the Generic Setup tool to write out the configuration for you to transfer into your own theme package.

Moving a viewlet within a viewlet manager

<object>
    <order manager="[Viewlet Manager Name]" skinname="[your skin name]">
Specify all the viewlets you want to see in this viewlet 
in the order you want them with this directive:
        <viewlet name="[Viewlet Name]">
    </order>
</object>

Note that you can do this process through the web and then get the Generic Setup tool to write out the configuration for you to transfer into your own theme package.

Moving a viewlet from one viewlet manager to another

If you are basing your theme on the Plone Default theme, then you'll find that reassigning a Plone Default viewlet is a two step process

• hide it in its current viewlet manager
• add it and give it a position in a different viewlet manager

<object>
Hide it from the current viewlet manager
    <hidden manager="[current Viewlet Manager Name]" skinname="[your skin name]">
        <viewlet name="[Viewlet Name]" />
    </hidden>
Add it to a different viewlet manager
    <order manager="[a different Viewlet Manager]" skinname="[your skin name]"
           based-on="Plone Default">
        <viewlet name="[Viewlet Name]"
                 insert-before="[Name of Viewlet Below]" />
    </order>
OR Add it to your own viewlet manager
    <order manager="[Your Viewlet Manager]" skinname="[your skin name]">
        <viewlet name="[Viewlet Name]"/>
    </order>
</object>

• you can also use 'insert-after="[Name of Viewlet Above]"' or use an asterisk to place the viewlet at the top or bottom of the manager (e.g 'insert-after'=*).
• based-on="Plone Default" means that it will take the Plone Default ordering and then apply the insert-after and insert-before adjustments you've specified.

Registering a viewlet / non-std. theme

If youare basing your theme on the Plone Default theme, then you'll
find that reassigning a Plone Default viewlet is a two step process

* hide it in its current viewlet manager
* add it and give it a position in a different viewlet manager

If your theme is not based on Plone Default you need to register the
viewlet in your theme.

You can customize a viewlet template through the web, but you can't alter the underlying Python class.

On the file system, rather than customize, the process is to wire up a new viewlet, or re-wire an existing viewlet.

You'll find a detailed tutorial on creating a viewlet in this article.

Quick Cheat Sheet

Through the Web

• Use Site Setup > Zope Management Interfaces > portal_view_customizations to customize the template of an existing Plone Default viewlet.
• You cannot create a new viewlet through the web.

In your own product

You will need to know the name of:

1. The viewlet manager interface

Look this up in the Elements section of this manual

2. Your theme specific interface

This is optional, but ensures that your viewlet is only available for your theme. If you used the plone3_theme paster template, then the name will probably be IThemeSpecific.

You will need to create the following (you should be able to locate the originals to copy by looking at the Elements section or by using GloWorm):

3. browser viewlet directive

This will go in [your theme package]/browser/configure.zcml

4. configuration file

[your theme package]/profiles/default/viewlets.xml

5. page template

[your theme package]/browser/[your template name].pt 

6. Python class

This is optional (but see the note below for Plone version 3.1.2 or lower)
put this in [your theme package]/browser/[your module].py

Sample configuration.zcml directives

Re-wiring a Plone Default viewlet to use your own template (note the layer attribute is really important here)

<browser:viewlet
 name="plone.[viewlet name]"
 manager="[viewlet manager interface]"
 class="plone.app.layout.viewlets.common.[viewlet class name]"
 template="templates/[your template name]"
 layer="[your theme specific interface]"
 permission="zope2.View"
 /> 

Wiring up a new viewlet but borrowing a Plone Default viewlet class

<browser:viewlet
 name=[your namespace].[your viewlet name]"
 manager="[viewlet manager interface]"
 class="plone.app.layout.viewlets.common.[viewlet class name]"
 template="templates/[your template name]"
 layer="[your theme specific interface]"
 permission="zope2.View"
 />

Wiring up with a brand new viewlet with your own class or your own template

<browser:viewlet
 name=[your namespace].[your viewlet name]"
 manager="[viewlet manager interface]"
 class=".[your module].[your class name]"
 (or: template="templates/[your template name]")
 layer="[your theme specific interface]"
 permission="zope2.View"
 />

Notes for Plone version 3.1.2 or lower:

Sample Python class

In Plone version 3.1.2 or lower, you will need to use this to override a Plone Default viewlet, even if you only want to change the page template.

from [element namespace] import [element class name]
from Products.Five.browser.pagetemplatefile import ViewPageTemplateFileclass 

[your class name]([element class name]):
    render = ViewPageTemplateFile("[your template name]")