Collections are an extremely powerful tool in Plone. A Collection works much like a report or query does in a database. The idea is that you use a Collection to search your website based on a set of Criteria. There is a wide array of Criteria available to you in a Collection as well as a number of ways to control the way the results display on the Collection page.

This tutorial will seek to help you discover some of the more in depth features of Collections to allow you to get more out of your Plone website.

Features covered include:

• Adjusting the Display Settings
• Explanation of Criteria Fields
• Adjusting the Sort Order
• Understanding Date Fields
  

We will start by covering how to Adjust the Display Settings and what effect the different settings can have on your Collection.

While the main power of Collections lies in Criteria, the display settings can make a big difference in the way your Collection will appear.

All three of the settings we will cover in this section can be found by clicking the Edit tab of a Collection.

 Inherit Criteria

By selecting the Inherit Criteria option, the Collection will inherit the Criteria from a parent Collection. This is only useful when using Sub Collections. If this is checked, you can create another Collection that is more specific than the Parent while still retaining the basic criteria of the Parent. A simple example might be a Parent Collection for displaying all Events in a site, and a Sub Collection that also displays Events (by inheriting Criteria) but only those Events with a particular keyword.

Limit Search Results

We can use Limit Search Results to limit the number of results that are Collection will display per page. This way if we have a Collection that is displaying News Items, we can limit the results to five or ten, instead of having it show all News Items on a single, large list.

Display as a Table

Display as a Table is simply another way to display the results of a Collection. Instead of having the Collection spit out the results in a list form, we can have it generate a table with the results, and set exactly what information about the results we want displayed. We customize the table by selecting the Table Columns from the left and clicking the button to move it over to the right. In the example above we chose to include the Title of the object, its Creator, and the Effective date. You can use any number of the columns, or all of them if you so choose.

Rendered table using the selected columns in above example.

When considering what to select, keep in mind that not all objects will have the information for every column available. For example, the Start Date and End Date only apply to Events. Therefore if you added these columns and your table included Pages as well as Events then the rows for the Pages would not have the Start and End Dates filled in. The other thing to consider is that the more columns you have showing the more crowded the table will become. The best rule of thumb is to only display what you absolutely need to display.

A few more notes on selecting columns: You can select more than one at a time by holding down the control key (Ctrl) while you click. If you want to remove a column, select it on the right and click on the button. Also you can add and remove columns by double clicking on their name.

The power of Collections most certainly lies with the Criteria fields. Mastering how to use the different Criteria will allow you to use Collections in several useful ways. In this section, we will use examples to illustrate the many ways of using Criteria.

Categories

The Category criterion allows you to search the Category field of objects. For this to work you must specify Categories for the content objects ahead of time (this is done through the Categorization tab on content objects). An example where you could use this is you want to create a Collection that would display all objects relating to the Category Organization. As you can see in the image below, we are able to select the value Organization for our criterion. Then, by saving this criterion and viewing our Collection, the results would be all content objects we had designated with the Category Organization.

Once again the values available to you are completely dependent on what you have specified on your objects in the Categorization tab.

When using the Creator criterion, we are filtering objects based on who created them. This might be useful if you want to do a featured author section, where you would only want to display content on your site that has been created by a certain author.

As you can see we have several options for our criterion type. They allow us to restrict the creator to the person currently logged in, enter the name of another user as text, or to select users from a list.

If you want to display results from multiple users, you would need to use the List of Values option. Otherwise you would normally use the Text option unless the creator you wanted to select was yourself in which case you would use Restrict to Current User.

Description

The Description field is essentially a search box type criterion. However, instead of searching the title and body of a page, it will only search for the text in the Description field of a content object.  This criterion is only really useful if you fill out the Description field consistently for all your content objects.

Location

Using the Location criterionis much like specifying a location when you search for a document on your hard drive. By specifying a Location criterion, the results that are displayed in your Collection will only come from that location, most commonly a Folder. This can be useful if you only want to display content that is in the About Us section of your site, for example. This is also useful for narrowing Collection results when combined with other criteria.

To specify a Location, simply click the Add button, which will pop up a new window showing you a directory of your site. If we follow our example and want to search the About Us section of our site, we would click the Insert  button next to the About Us folder.

You can open folders to view content contained within them either by clicking the Browse button or directly on the title of the folder you want to open. You may also use the Search box to search for the Title of an object.

Search Text

The Search Text is a very useful criterion. It is similar to the search box on your site or an Internet search engine. It takes the text you specify and searches the Title, Description, and Body of all objects and returns any that have the word or phrase you specify. This is useful when you want to find objects that have to deal with a certain thing, especially if the word or phrase appears across many content types. Using LearnPlone.Org as an example, if I want to create a Collection that displays all objects that reference the word Collections, I would use the Search Text criterion and specify collections. All Tutorials, Videos, Glossary items, etc with collections in the Title, Description, or Body would then appear in the Collection results.

Related To

The Related To field is another field, like Category, that must be specified on a content object prior to being used for a Collection. The Related To field on an object lets you specify which other objects in your site are similar or are relevant to the object you created. By specifying this field, when you create an object you can create a web of related content that will reference each other (think of a "see also" kind of function). When you have done this, you can use the Related To criterion in a Collection to display anything related to a specific object.

In this case we have specified that there are pages related to Our Staff, History, and the About Us Homepage. By selecting one or multiple values from this list, our Collection will display the pages that related to that Value.

If we selected History as the value we wanted, our Collection would show us everything that is related to the History page.

Keep in mind that the Related To Values list does not work based on which objects are related to content but on which objects have another object related to it. The Collection will display the results that are related to that value.

State

Using the State criterion is very simple. It allows us to sort by published or private state. It is a very good idea to restrict publicly viewable Collections to filter on published, so that no private content appears in the Collection results. Filtering on the Private state can be useful as well. For example, a site administrator might want to quickly see private content, so that they could determine what work needs to be done and what could deleted.

Dates

You may have noticed that there are several different dates available to use as Criteria. Since there are such a large number of dates, they will be covered on their own page later on in this tutorial.

The Sort Order determines the order the results of the Collection will be displayed in.  Sort Order allows you to sort by three main categories: text, object properties, and dates.  When you sort by text, objects will be sorted in alphabetical order. When sorting by one of the object properties, we effectively are grouping objects together by the specified properties.  When we sort by a date the results will be displayed with the most recent first (although there are many 'dates' in Plone). All Sort Orders are in Ascending Order unless the Reverse Order check box is selected. By checking this we can display in reverse order, or newest dates first, etc.

Dates

Object Properties

Item Type

When sorting by Item Type, we end up with a Collection that has results that are grouped by Item Type. We would want to use this if we have a Collection that will return many different Item Types. This way we can make the Collection very easy to browse for the site visitor.

State

Sorting by State will display results grouped by the publishing state. Since there are only two States in the default configuration of Plone, there will only be Published and Private items. We can use this to separate all pages on our site and easily see what we have that is public (Published) and what we are hiding from the public eye (Private).

Category

Category Sort Order is useful when we want to display the objects on our site in a manner where they are grouped by the Category we placed them in. Keep in mind, for sorting by Category to even be remotely useful, you must have specified the Category on several objects. If you have not specified any Categories, then sorting by Categories will do nothing.

Related To

The Related To Sort Order will actually apply a criterion to your Collection. It limits to the results to only those that have Related To information Specified on their properties.

Text

Short Name

Sorting by the Short Name is the same as putting the result objects in alphabetical order. By default Plone sets the Short Name of an object to be the same as the Title. The difference between the two is that the Short Name is all lower case and hyphenated between all words. For example the Short Name for the page titled About Us would be about-us. The Short Name is what Plone also uses in the URL for the page (www.myplonesite.org/about-us). You can specify a different Short Name for an object by using the Rename button on the Contents tab.

Creator

Sorting by the Creator will group all results in alphabetical order by their author. For example, let's say we had several documents published by Bob Baker and several of other documents published by Jane Smith. Sorting by the creator would result in all the documents created by Bob Baker listed first followed by those of Jane Smith.

Title

Sorting by Title will display the results in alphabetical order, by the object Titles.

Next we will cover the Dates that we skipped over in this section as well as the Criteria Field Section.

There are several different types of dates we can choose from, many of them sounding similar. Because of this it is very easy to get confused about which date to use. Below, each date option is defined.

Dates Defined

Creation Date
The Creation Date is the date the document was made. You can think of this as its birthday, the day it was born. You cannot change the Creation Date of an object.

Effective Date
The Effective Date is the date when an object becomes published. This date is customizable through the Edit tab on objects under the Date tab. However, there it is referred to as the Publishing Date (a minor discrepancy in Plone's nomenclature).

Creation Date and Effective Date are very similar. They both are representative of the beginning point of an object. A very important point to keep in mind when choosing which one you want to use, is that an object can be created long before it ever becomes public. You could have a page that is worked on for several weeks before it is actually published. Thus you would get different results in a Collection depending on which date you used.

We recommend using the Effective Date, instead of Creation Date for date-oriented Collections. This way your Collection shows results based on when they became viewable to the public, which is more relevant to the audience of your Collection. Also, you can go in and manually adjust the Effective Date to control the sort order which is not something you can do with the Creation Date.

 Image of Page Edit Tab showing the Date section

Expiration Date
The Expiration Date refers to the day that the item will no longer become publicly available. This date is also customizable through the Edit tab (shown above) like the Effective Date. By default, objects have no Expiration Date.

Modification Date
The Modification Date is the date the object was last edited. Note that this date is first set the day the object is created and will automatically change every time the object is edited. There is no way to customize this date. You could use this as a Sort Order along with an Item Type criterion set to Page, to display all recently modified pages within the last week, for example. The What's New listing on the homepage of LearnPlone.Org uses Modification Date as its date criterion. That way both newly created documents and ones that have been updated appear in the listing. 

Event Specific Dates

The two following dates only apply to objects that are Events. These two dates are very effective for creating Recent Events and Upcoming Events Collections that will let your audience know what your organization is doing and will be doing in the future.

Start Date
The Start Date is simply the date that an Event starts.

End Date
The End Date is simply the date that the Event ends.

Setting up a Date

A confusing thing about dates can be how its Criteria are set up. They have a setup that is not like any of the other Criteria. First off, you have to choose whether you want a Relative Date or a Date Range.

The Relative Date allows you to construct a conditional statement. Such as: Items modified less than 5 days in the past. A Date Range will allow you to specify an exact range of dates, such as 01/02/08 to 02/02/08. The Date Range is useful when you want to create a Collection with a static date that won't change. The Relative Date can be very useful as it will allow you to create Collections that are automatically updating themselves, such as a Recent News Collections or an Upcoming Event Section.

Relative Date

Looking first at the Relative Date option, you can see we have three options to fill out.

The first option is Which Day. This allows us to select the number of days our criterion will include. One of the options is called Now. Using this will set the date range to the current day. The other two options do not matter and can be ignored when using Now.

The second option is In the Past or Future. This enables us to choose whether we are looking forward or backward into time.

The last option is More or Less. Here we can choose from three options. Less than allows us to include everything from now to a period of time equal to or less than the Which Day setting, either in the past or future. More than will include everything from beyond our specified number of days equal to or more than Which Day. Finally On the Day will only include things that are on the day we specified in the Which Day. Using the example in the image above if we had selected On the Day instead of Less than our Collection would display only objects that were modified (we are using the Modification Date criterion) 5 days ago.

If this is confusing to you, try reading it as a statement substituting in the field options you chose. "I want the results to include objects More or Less than Which Day, In the Past or Future". Our example in the image above would become "I want the results to include objects Less than 5 days in the past".

Date Range

The Date Range is much easier to understand. Both a Start Date and End Date are required (do not confuse these terms with the Event Specific dates!). The Date Range allows us to enter a beginning and an end date and the display everything within that time frame. Notice also that it allows us to specify a specific time of day as well.

Through this tutorial we have covered the different options available to you with Collections. You should now have some background and insight to how each of the different settings and criteria work. With this the next step is to figure out what you want to display with your Collection and pick the criteria that will create that. Keep in mind that you can mix and match as many of the criteria as you want.

The more you work with collections, experiment, and explore, the more efficient and effective you will become at using them. The possibilities of Collections are great and are not just limited to a few examples. So go forth and explore.