Introduction

Introduction

The Plone core is a beautiful thing.  It does a lot of things, and does a lot of things well.  But much of the power of Plone lies in its large and growing library of add-on products, which extend Plone in ways both large and small.    Many of Plone's core components started life as add-on products, and add-on products are the primary way to share and reuse code in the Plone community.

This guide is intended to help new product developers who wish develop high quality add-on products and contribute those products to the Plone community. It will also be useful to add-on product developers wanting to future-proof their products through the use of best coding practices.

Do you even need to write a product?

Sometimes the best product is one that never gets written because the developer just contributes to something that already exists.  Before you dive into writing a new product from scratch, it's worth taking a bit of time to check out the Products section of Plone.org as well as the Plone Collective (our shared SVN code repository), to see if someone else has already taken a run at solving your problem.  

It's in the long-term interest of the Plone community to have fewer, higher-quality, more generalized products than many products that all solve very similar problems in slightly different ways.   Most Plone add-on product developers are very open to new contributors, and would welcome your help in making an existing product better!

Add-on Product Developers 

A forum/list for developers of add-on products.

General Characteristics of High Quality Add-on Products

Add-on products from Plone range from the very simple to the extremely complex, which means that what makes a product "high quality" may vary quite a bit from one product to the next. That said, most high quality products will have the following general qualities.

Balancing Extensibility and Simplicity

A good add-on product is designed to be customizable / extensible / adaptable, where appropriate. It should be easy to define different content types which use any custom logic or machinery in your product. It should be easy to subclass any custom content types in your Product.

At the same time, simplicity is a virtue. Good products solve the problem they're trying to solve, without going overboard creating new frameworks or making every single point of the product customizable, using a minimal number of needed methods, etc. "Does one thing, and does it well."

Using Zope 3 Development Techniques

With the advent of Zope 3 technology, the Plone community now places a very high value on good componentization. Complex products should broken into multiple products, libraries, methods and classes, consisting of Zope 3 compoments (interfaces, views, annotations, etc.) that can be re-used by other products.

Good starting points for learning how to apply Zope 3 development techniques in add-on Products include:

• b-org: an in-depth tutorial from Martin Aspeli. The video of Martin's b-org presentation from Plone Conference 2006 covers similar material.
• Rocky Burt's tutorial "Developing Plone Products Using Zope 3 Technologies" from Plone Conference 2006 is also worth a look. You can read the material and also watch a video of his talk.
  

Using Good Archetypes Development Practices

Archetypes is the framework Plone uses for building its core content objects, and thus many add-on products involve creating new content types with Archetypes.  Using Archetypes correctly will go a long way towards making your add-on products robust, reliable and easy to use. 

A good starting point for learning more about Archetypes is:

• The Archetypes Developer Manual
• Upfront System's brief guide to developing a custom content type

However, a custom Archetypes content type might not always be needed. If you only need to extend the schema of an existing Plone content type, you should look into archetypes.schemaextender. This allows you to take advantage of the strengths of ATContentTypes (or other existing Archetypes-based content types) non-invasively without sub-classing. Learn more about Schema Extender:

• "Customize the fields of the content types" how-to
• "SchemaExtender Extends Your Mind" presentation
• archetypes.schemaextender on pypi
  

Well Designed User Interface

Plone prides itself on being the most highly usable and accessible content management system around.  Add-on product developers should pay attention to the user interface for their products.  For example,

• Beginning with Plone 3.0, add-on Products can take advantage of the KSS javascript framework.  Effective use of javascript can help you build a much more responsive and rich user interface.  However, user interfaces should degrade gracefully (with functionality intact) in browsers that lack javascript.
• Products should use appropriate Archetypes or formlib widgets for editing interfaces.  See:
• The Archetypes Widgets Reference
• More fields and widgets from the Archtypes SVN repository
• Push end-user configuration options into Plone control panels.  Avoid making users go into the ZMI or the filesystem to configure your add-on products.
  

Security

Thanks to Zope, Plone is a highly secure system, and is generally pretty resistant to the most common types of security problems that plague, say, PHP/MySQL content management systems.  But every add-on product is a potential source of security problems, and thus you should pay clear attention to security as you design your product. 

Useful starting points on security in Plone include:

• Andy McKay's security talk
• J Cameron Cooper on security
  
• Mikko Ohaatma on security
• Martin Aspeli on permissions and workflows
  

Internationalization (i18n)

Plone has users all over the world, and Plone's internationalization framework is one of its strongest features.  But it's not worth much unless add-on Product authors make sure their products are i18n-ready.  (Don't worry, you regrettably monolingual folks, it's really quite easy, and no foreign language skills are needed!).

Good starting points:

• The "i18n for Developers" how-to 

• Upfront Systems' guide to internationalization in Plone

Naming your product

Choosing a good name really helps people understand what your product is and what it does. Unfortunately, the Plone and Zope communities have a history of coining awkward product names. Renaming a product is painful because of migration hassles for later releases, so getting the project name right the first time around will save you work later. Here are some recommendations for choosing a great product name:

• Choose a name that is unique, memorable, and not too similar to other existing products.
  
• A good name describes or suggests what your product does.
• As the Plone community transitions to eggs for product distribution, it's important to remember that the namespace is not the product
• Avoid having the word "Plone" in your product name — it's usually obvious from the context that it is a Plone product. If you really feel the need to have Plone in the product name, it's better to call it something like "XYZ for Plone". Plone® is a worldwide registered trademark of the Plone Foundation, and people very often think products that contain the word is the responsibility of the Foundation, which is confusing and unnecessary.
• Avoid jargony acronyms like "AT" "CMF" "NG" etc. and names based on the underlying technologies of your product.
• Avoiding prefixing your products with your company name, or the company you are developing it for.
• Don't lowercase your human-readable product names just because Zope 3 convention is for lowercase names in code.

At the risk of courting controversy, here are some "good" product names and some "less good" ones.  (Remember: we love all add-on product developers, even if we don't love all the product names! :)