Using GenericSetup Efficiently

Once you have your GenericSetup profile set up you'll need to start adding import files into it. It is common for people to think that they have to write all the XML by hand. This should almost never be the case.

Change and export

The easiest way to to make changes with GenericSetup is to make the changes in your site and then export the corresponding step. Let's start with a very basic example, changing the MailHost settings so that we can send out mail.

Go to the ZMI (http://yourplonesite:8080/manage) and find the MailHost object in the Plone site root. Enter the configuration data for your mail provider. Now go to portal_setup and click on the Export tab. Click the checkbox next to the MailHost import step and then on the Export selected steps button.

A targz bundle with the XML declarations of this exported import step will be generated and downloaded. Note you can select as many import steps as necessary or even export all steps directly so you have a complete snapshot of the configuration of the your site.

Trimming down the export

When you export settings from from GenericSetup, you will get more than what you changed. It's a very good idea to trim down the export file to only have the specific items that you changed. If you don't trim down the file then you will inadvertently override a change that is made in another profile.

A common example is the propertiestool.xml export. This exports the properties in the portal_properties tool. Let's say you have modified the default_language property in portal_properties/site_properties and you want to save it for your policy product. If you go to portal_setup and export the Plone Properties, the generated propertiestool.xml will more than 100 lines long.

Since you have only modified a property and you're using a extension profile, you only have to keep the configuration data for this property.

<?xml version="1.0"?>
<object name="portal_properties" meta_type="Plone Properties Tool">
 <object name="site_properties" meta_type="Plone Property Sheet">
  <property name="default_language" type="string">en</property>
 </object>
</object>

Play well with others

When writing Plone add-ons you need to be aware of how your profile is going to interact with other add-ons and custom packages.

By default existing settings are purged before applying settings from base profiles. Extension profiles are applied in update mode.

However, you can use the purge="True" and purge="False" directives to override the default behavior. If True the existing settings of the current object are always purged, if False they are not purged.

For example, the declarations in the propertiestool.xml in an extension profile:

<?xml version="1.0"?>
<object name="portal_properties">
    <object name="navtree_properties">
        <property name="metaTypesNotToList" type="lines" purge="False">
           <element value="Promotion"/>
        </property>
    </object>
</object>

will append the Promotion type to the list of content types not to list in the navigation trees, leaving the rest of them intact, whereas, in the same extension profile

<?xml version="1.0"?>
<object name="portal_properties">
    <object name="navtree_properties">
        <property name="metaTypesNotToList" type="lines" purge="True">
           <element value="Promotion"/>
        </property>
    </object>
</object>

would remove all previous elements from the mentioned list and let Promotion alone.

User editable settings

Another thing to take into consideration is the fact that some of the properties or settings that you are importing can be changed by the end user. The most common of these properties would be the site title. The end user can easily change this setting by going to the Plone control panel.

Be careful not to place a setting like this in a profile that runs when your product is re-installed. This could lead to the end users' changes being wiped out each time. You can place these settings in another profile that can be run on the initial creation of the site.