Plone and Related Items use for Collections and Folders

This post is about an old but hidden feature of Plone Collections, and how related items are used in some non-standard ways in Plone.

Have you ever used related items for a Plone Collection? Maybe you never used them neither for Folders, so you simply learn that Plone choose to hide related items for some types.

But while for Folders this is simply a choice to make related items as hidden, for Collections is different.

Using related items for Folders
Every AT content schema, after being defined, call a function that is finalizeATCTSchema.

    def finalizeATCTSchema(schema, folderish=False, moveDiscussion=True):
        """Finalizes an ATCT type schema to alter some fields
        """
        schema.moveField('relatedItems', pos='bottom')
        if folderish:
            schema['relatedItems'].widget.visible['edit'] = 'invisible'
        ... 

The function receive the argument folderish=True for folder content types. As you can see this hide the related items widget when editing (and in this way no simple user can fill the field, so you'll never see it also in view).

But if you fill the field through an external code, the field appear also in Folder's view.

To restore the field normally, simply make the widget visible again.

Using related items for Collections
For Collections the related items field is not hidden but has a special purpose.

You must use it to add additional items to the collection search result, ignoring whatever type of criteria you have set in the Collection.

For example: you can have a Collection that show all contents inside a folder (using a simple well-know path criterion) then you can add to related items of the collection one or more contents outside that folder. The resultset of the collection will include also this content.

Another example: you have a collection that display news items on the portal, then you need to include also an important event. The normal way for Plone is to create a new news item that talk about this event, but you can also use this trick: add the event to related items.

Drawbacks
I consider this a good feature. Not common, but two examples above are not so uncommon... but probably you never know of this feature.
However this behavior has some problems.

Plone 4.1 double related items. Seems that there is a bug in recent Plone. On Plone 3 if you were using related items in collections, the related items section was not shown in the Collection view template. Now is... probably a little bug that need to be fixed.

Documentation. No one know of this behavior because this isn't readable anywhere in the Plone UI. The related items field is the same of always. Some suggestion that can help:

• related items for Collections must be moved on the main fieldset, to highlight that there has some special meaning.
• related items widget help text for Collections could give some additional information on this behavior.

Related items aren't as normal criterion results. Related items are added to the resultset of the Collection, but:

• They are not sorted using the choosen sorting criteria
• They are not mixed with normal results
• They are always returned first

So related items are always used first, then other results are displayed. This can be good (because you can use this feature to put an high important news as first item of your Collection) but not simple to understand. However this is not a bug... mix related items and other results sorting them all can be complex and expensive for Plone.

How to sort those additional resultset? Recent Plone releases have finally add a way to sort related items (without using external add-ons like before) but using Plone 4.1 trunk the manual sorting is ignored for this feature. Maybe another little but to be fixed?

Can I use related items normally? Giving us this feature will steal us the possibility to use related items for Collections for the common purpose. I don't find this a big problem, however I get this request one time: the customer asked us to be able to use related items for collections in the classic way. Use the same field for a different task is someway strange.

Conclusion
Is this a good feature? I think it can be... however sometime I think that is too complex and simply needs to be removed. Some other times I find it smart.

What you think?