Why have I written this?

When I wrote this there seemed to be almost no detailed information about Plone's topics, so I've written what I've managed to find out about them. I am a relative novice when it comes to Plone, so please feel free to make any corrections or additions you see necessary. This is stuff I've gleaned from "The Plone Book", "The Definitive Guide to Plone", the Plone mailing list and some trial and error.

I got the feeling that because 2.0's topics were so tricky, even the experts avoided them and helped other users avoid them by not writing about them. Hopefully this will change now that 2.1's Smart Folders have arrived. If you find some documentation please make a reference to it here.

Smart Folders vs topics This was originally written for Plone 2.0.3. Topics are a little different in Plone 2.1. I haven't used them much yet, but I've added some initial observations to this text.

In some places where I've referred to topics, I mean the topic objects avaliable to Plone 2.0, but in others I mean either 2.0's topics or 2.1's Smart Folders, so I hope it still makes sense.

For a start, in Plone 2.1 they are called Smart Folders, are more flexible and appear easier to use and have less bugs. But they basically achieve the same thing. You could probably work out how to use Smart Folders by trial and error, but topics are trickier so they have been less popular than they could have been.

Note that Apple's Mac OS X can create what they also call Smart Folders. I assume the concept is similar, but they have nothing to do with Plone's Smart Folders.

What are topics?

Topics are a metatype based on folders, so they act a little like folders in that they will appear in your navigation menu. Rather than displaying their contents when viewed, they display the results of a search of your site. They can have criteria which limit this search. If they have no criteria, then they find everything. They can also have a sort order defined, and that alone can be useful. Only managers can create them (not sure if this is true of Smart Folders).

What good are they?

Topics are handy when, for example, you want to show a list of all news items or events within the whole site or a particular folder (and its subfolders). Or you might need a list of all unsubmitted documents, sorted from newest to oldest. They allow you to be freed from having to keep items in the folders they will appear in in your site's menu structure, and to avoid having to duplicate items that need to appear in several places. You can keep everything in a single folder if you like, and have them appear in several/various places in your menu according to their contents.

Subtopics

They can contain subtopics (they're called subfolders when you're using Smart Folders), which behave like any other topic, except that they can optionally inherit they parents' criteria, allowing then to display a subset of the objects their parents display. A subtopic will appear in your navigation menu like a subfolder would (but only when you're viewing it).

How do they work?

They work by querying the portal catalog, which is quicker than searching each object one by one for matches. I'm under the impression that the list of matching objects for each topic is stored and maintained somewhere in the catalog, so that viewing a topic involves no search time at all. (Could someone confirm if that's true? I have feeling it's not.) Thus, if you manage to get an item into your site without it being cataloged (i.e. adding or modifiying an object via the ZMI instead of Plone), then it won't appear in any topics.

Creating them

To create a topic, add one to your main folder or a subfolder like you would any other object, by choosing Topic from the pullown list of object types in "Add new item". Give it an id (shortname, which becomes part of the URL) and a title (which is what will be displayed in the menu and folder listings), and click Save. The topic will be saved and you'll be taken to the criteria tab.

If you leave the topic with no criteria, then it'll find everything in your site.

Criteria

Smart Folders have an additional "criterion", accessed from the Edit tab. You can specify whether to limit the number of results returned, and how many to return. Very useful if you want to use the results in a small portlet, for example.

To create a criterion you must choose a field name and criteria type, from the pulldowns on the form, then click Add. (It should probably be a "criterion type", but that's what the form says.) The field names you can choose from are those listed in /portal_catalog/indexes. Most of them should be familiar and self explanatory, but a few are not:

• "Date" is the effective date if present, otherwise it's the modified date.
• "SearchableText" is the description, title and body text as one piece of text.
• "getId" is the same as id.

The "criteria type" can be String, Integer, List, Friendly Date, or Sort. Smart Folders only allow you to choose criteria types that apply to the field you've chosen, but topics show them all.

• Use a String type for anything requiring a single string to compare to, like a keyword or path.
• I assume you use an Integer type where you're wanting to match a number. I've never used it myself.
• Use a List type where you need to match all or any of several values. You enter them one per line in a list box.
• Use a Friendly Date type to match items with dates in a particular range. Be warned that this type doesn't always work properly, so check your results before trusting them. They have been described as "Unfriendly Dates" and "broken". See the Tips section below for more information. The bugs seem to have been fixed in 2.1's Smart Folders, and you can now choose from a Relative Date or a Date Range criteria.
• The Sort type allows you to sort the results ascending or descending according to the contents of a field. You can only have one Sort criteria. You can't sort by title with topics, but you can with Smart Folders. Trying to sort byu title with a topic will make your topic crash and it may be hard to fix it. Look at the indexes tab of /portal_catalog and note the type of the indexes available. You can't sort with TextIndexes, which is what the Title index is, only with FieldIndexes(I think). I believe you could create a second index of type FieldIndex for it, and sort on that instead, but naturally it will have to have a different name and you'll have to remember to use it instead.

Once you've added criteria you can enter a value for it.

If you have multiple criteria, their results are "anded" together, i.e. the more you add the less results you get.

Note that you can only use a field as a topic criterion once per topic. It won't be available for selection again. This is especially a nuisance for sorting (not true for Smart Folders), because often you want to sort by the very field you've selected by. One way around it is to apply the sort criterion to a subtopic with inherited criteria, although it's messy to navigate through. Another suggestion has been to duplicate that index in the portal_catalog with a different name. Then you could sort with one index and limit the results with another.

Subtopics

To add a subtopic, click on the Subtopic tab of a topic (or the subfolders tab of a Smart Folder). You can enter the id of a subtopic and add it, and it'll appear in the list. Click on it to view it. The first thing you'll probably want to do is click on the Edit tab to enter a title for it and decide whether to enable "Inherit Criteria".

When you've done that you'll be taken to its criteria form. This is similar to its parent topic's criteria form. Remember that if you've enabled "Inherit Criteria" you're already starting off with a reduced set of results, even though you don't see those criteria listed. Inherited criteria are useful if you want to present your users with an increasingly refined set of results, e.g. all news, then all news created by particular people, etc.

Tips

There are a few traps for the unwary topic user:

• Don't change any properties you might want to search for via the ZMI. If you do, the catalog doesn't get updated. Topics search the catalog, not the objects themselves.
• Paths can be tricky in the old topics because you have to specify the full path from the root. E.g. /mysite/articles/old. If your site is hosted it's not obvious what the name of the root of the site is because it just shows up as /. Look at the items in the Catalog tab in portal_catalog to find its name. I don't think putting in a URL works. With Smart Folders you use a Location criteria, which allows you to browse and insert the location to search. You even get to choose whether it searches subfolders!
• Weird toggling friendly date (Not a problem with Smart Folders). I've seen weird things happen with friendly date criteria. When I say "less than" it remains as "more than", or when I change the age it will swap from one to the other, etc. The less than more than option appears to toggle, you set one, you get the other, but we do observe the expected behaviour based on the setting displayed. See :http://plone.org/collector/3383 for more information and a solution (I haven't tried it myself). Or just keep saving till it toggles the way you want it!
• Sometimes a topic goes crazy because you've made a mistake with the criteria, and all you get is an error message so you can't get to the criteria tab to fix it. Just add /topic_criteria_form to the end of its URL to get in to fix it. I've had even this not work, and had to delete the topic and start again.
• There are some fields you can't sort with, e.g. title and Description. Trying will result in a topic that crashes and can't be fixed. Experiment with a test topic first. I think it's safe to choose anything in the list with Smart Folders.

FAQ

• Can I join the results of two topics together? Not that I know of. Check if a list criteria type could help.
• How do I change how the results are listed? With topics, customise /portal_skins/plone_3rdParty/CMFTopic/topic_view. With Smart Folders, first have a play with the Smart Folder Settings (click preferences, then look in the Site Setup menu on the left). There you can choose which fields to display in the results (metadata tab), and which criteria are available (indexes tab). I'd be cautious about fiddling with the latter too much. I assume the Smart Folder Settings apply to the whole site. Not sure which template Smart Folders use, but I'd be guessing /portal_skins/ATContentTypes/atct_topic_view.

EXAMPLES

1. Create a new topic to list all objects of a certain type (e.g. news items, or events)
   • From your own folder select add new item > topic. Give it a short name, title and description
   • From the criteria tab choose Type as the field name and String Criterion as the criteria type. Click Add.

   (notice that the available fields list no longer includes Type)

   Your new topic now redraws its criteria tab listing the criteria details.

   • Enter News Item in the edit box, click Save and select the view tab to see the results of the topic search.
   1. b. for Type criteria the filter (topic) matches against the available Content Types in your Plone portal, have a look via the ZMI at /portal_types for a listing of valid Types in your portal.
2. Topics can have subtopics attached to them allowing you to chain successive criteria as filters on the content of your site. This allows for the results of a topic to be refined. This is like an and for a boolean search
   • Select the subtopics tab of your active topic and provide an ID or short name for this new topic (the subtopic).
   • The new topic form is displayed, provide the information required (note that you'll need ensure this topic has the Inherit Criteria option selected if you want the results of the supertopic to be further refined by the criteria of this new subtopic.
   • Select the view tab of the subtopic to see the results of the topics.
   1. b. the subtopics only exist in the namespace of the original topic, you won't see them in the folder.
3. To use a Topic like an or for a boolean search, for example to find all events or news items (adapted from a post by Ralf Ritz)
   • From your own folder select add new item > topic. Give it a short name, title and description
   • From the criteria tab choose Type as the field name and List Criterion as the criteria type. Click Add.

   Your new topic now redraws its criteria tab listing the criteria details.

   • Enter News Item and Event on different lines in the edit box under matches one of the following, click Save and select the view tab to see the results of the topic search.
4. Recently modified items. This topic searches for all objects in the site which have changed over the last week (adapted from www.engineering.ucl.ac.uk)
   • From your own folder select add new item > topic. Give it a short name, title and description
   • From the criteria tab choose modified as the field name and Friendly Date Criterion as the criteria type. Click Add.

   (notice that the available fields list no longer includes modified)

   Your new topic now redraws its criteria tab listing the criteria details.

   • Under the Criteria Details for this topic select less than 1 week old from the configurable friendly date option. Click Save and select the view tab to see the results of the topic search.
5. Recently modified items plus sort by modified time. Building on the previous topic, add a subtopic to list recently changed (or added) stuff sorted correctly by modified time. This topic plus sub-topic lists all recently created objects and sorts them newest first. Warning, you will probably notice the Weird toggling friendly date behaviour noted above, just toggle until you've got it working the way you expect.
   • Select the subtopics tab of your Recently modified items topic and provide an ID or short name for the subtopic.
   • From the criteria tab choose modified as the field name and Sort Criterion as the criteria type. Click Add. The criteria tab allows you to select between ascending or descending order (as you'd expect).
   • Select the view tab of the subtopic to see the results of the topics.
6. Topic lists objects with certain keywords in their properties tab. This topic lists all objects with a certain keyword selected in their properties metadata tab. Note, it is not obvious from Add New Topic Criteria that the field name Subject is equivalent to the keywords selected in an object's metadata, however this is the case. So if you want to make use of these keywords to group objects together via topic results then do the following.
   • From your own folder select add new item > topic. Give it a short name, title and description
   • From the criteria tab choose Subject as the field name and List Criterion or String Criterion as the criteria type. Click Add.

   Your new topic now redraws its criteria tab listing the criteria details.

   • Assuming you have previously selected a number of keywords in some selected objects metadata tab (in this case I have some documents with "!BSc" and "B.Comm" as keywords) Enter !BSc and B.Comm on different lines in the edit box under matches one of the following, click Save and select the view tab to see the results of the topic search.
7. An example using paths. The trick to paths is to realize that they are relative to the Zope root when you have VirtualHostMonster turned and rewrite rules in place. Remember, a Plone site lives inside Zope. So if your Plone site is http://yoursite:8080/plone_site, and the rewrite rules allow you to access it at http://yoursite/, you still need to include /plone_site in your path.

   Object: To add a topic which displays only those News Items which are stored in folder /plone_site/sitenews

   • On the "Add new item" drop down list, choose "Topic"
   • Enter a short name, title, and description for the topic
   • Click the "Criteria" tab
   • In the section labelled "Add New Topic Criteria" select "portal_type" from the "Field name" drop down list
   • In the same section, select "String Criterion" from the "Criteria type"
   • Click the "Add" Button

   The first criterion should appear in the section labelled "Criteria Details" with a blank text field below a label "portal_type is".

   • Fill in the "portal_type is" field with the value "News Item"
   • Click Save

   Now add a criterion based on path

   • In the section labelled "Add New Topic Criteria" select "path" from the "Field name" drop down list
   • In the same section, select "String Criterion" from the "Criteria type"
   • Click "Add"

   The second criterion should appear in the section labelled "Criteria Details" with a blank text field below a label "path is".

   • Fill in the "path is" field with the value "/plone_site/sitenews"
   • Click Save
8. An example of a site using topics. This site www.nuw.org.au generates its News, Events, Press Releases and Public Documents pages using a slightly modified topic template. Each branch of the Union can securely store their documents in their own areas but still have them all displayed together. Subtopics are used to further filter the results by branch using path criteria.

The news, etc shown on the front page uses the results of those same topics in some custom CMFContentPanels viewlets, and a similar arrangement is used to display the staff photos at www.nuw.org.au/branches/vic, http://www.nuw.org.au/ohs and www.nuw.org.au/training.