TypedReferenceWidget

Warning

This product has not had a release in over 1 year and may no longer be maintained.

TypedReferenceWidget allows user to type referred object ids manually as a comma separated list.

Project Description

Version 1.0

Copyright

Copyright 2005 Mikko Ohtamaa.

Purpose

TypedReferenceWidget allows user to type referred object ids manually as a comma separated list.

When to use this widget

There can be so many objects that a standard way to enter references via check box lists and pull down menus becomes painful. An example situation could a bug tracker containing thousands of bugs. In a bug report item, related bugs field can be managed using Archetypes' reference field. But selecting referred items is difficult, because Archetypes standard ReferenceWidget was designed for small numbers of items. Typing in (or copy-pasting) related bud report ids would be easier.

Id magic

There are two kind of ids assigned with Plone objects

• Zope's folder level object ids, as a object name in path walkthrough. Think this as a kind of filename. Example: plone.org/products/myproductname. Object id is mutable: it can be changed after creation.
• Archetypes unique identifiers How to create easy to type UIDs. UID shouldn't be changed and once created, the object can be looked up using the same UID.

With TypedReferenceWidget, user types in the UIDs of referred object. For more information, see UID section in Archetypes Developer Guide.

How to create easy UIDs

Using TypedReferenceWidget is only meaningful, if UIDs are quite short and meaningful, unlike standard Archetypes object ids (UIDs), which are in format CustomerSQL.2003-07-23.4911. A meaningful unique identifier can be a running counter with a prefix letter. For example, Microsoft Development Networks uses Q + number for its articles (like Q567123). Plone and Archetypes how to documentation should have examples how to modify id generation

If your items have always the same Archetypes parent container, you can override parent's createObject method. Here is an example, where Issues are always placed under Application containers. This code goes to Applcation class:

    security.declareProtected(ADD_ISSUES_PERMISSION, 'createObject')
    def createObject(self, RESPONSE=None):
        """ Create a new issue whose local and site wide id is generated in non-standard way

        Give U###### format id for the created item.
        This id is used as Zope folder level object id (id, oid) and 
        Archetypes site wide unique id (uid).        

        Bad things happen, if generated ids are not site wide unique!
        """                

        usabilityTool = getToolByName(self, 'portal_usability')

        # create string UI + unique number (a running counter)
        id = "UI" + str(usabilityTool.nextIssueId())

        # Create a new object with an object id
        issue = Issue(id)

        # Force Archetypes UID for the object.
        # Otherwise it is generated through ReferenceEngine / make_uuid call.
        issue._at_uid = id

        # assing created object to this (self) container
        self._setObject(id, issue)
        issue = issue.__of__(self)

        # Initialize Archetypes stuff for the created object
        issue.initializeArchetype()

        # Go to the action which is responsible for editing a newly create item
        if RESPONSE != None:
            RESPONSE.redirect(issue.absolute_url() + '/base_edit')		

Input validation

Because the user can type in ids manually, error validation must be done. TypedReferenceWidget is accompanied with UIDListValidator class to perform this validation. Archetypes framework doesn't provide a hook for widget level validation. Therefore, a lways use UIDListValidator in your field.validators if your field uses TypedReferenceWidget, otherwise bad input creates an exception page. See UIDListValidator.py for more details.

Quality assurance

I toyed around with it. It works.

Tested with:

• Plone 2.1.1
• Windows XP
• Opera browser

Manual tests done:

• Entering empty string as a reference list
• Entering one correct reference
• Entering one correct reference w/changed case
• Entering one invalid reference
• Entering two correct references
• Entering two correct references and one invalid reference

References

TypedReferenceWidget is in live usage in www.opensourceusability.com.

Missing features in the current version

I am unlikely going to implement these features, due to my free of charge contribution for Plone project

• Internationalization
• Unit testing

Contact

If you wish to hire a professional Plone developer (freelancer), please don't hesitate to contact. I am willing to work abroad. Contant me to receive my CV.

Mikko Ohtamaa

Oulu, Finland

miohtama@mail.student.oulu.fi

Nick Moo (Moo- or Moo^) at #plone channel in irc.freenode.net