Products.ATReferenceBrowserWidget 2.0.5

ATReferenceBrowserWidget is reference widget for Archetypes.

Introduction

ATReferenceBrowserWidget is an add-on to Archtetypes. It adds a new reference widget that allows you to search or browse the portal when creating references. This new widget inherits from the standard reference widget so you can use all it’s properties.

When you use this widget, there are two buttons presented for each widget. One that opens a popup-window that let’s you do the search/browsing and one that let’s you clear the reference or selected references (will be in effect after the form’s Save).

The popop window basically consists of two parts. The top half is a search form and the bottom half is the browser/search results part. Both parts can be turned off or on using the widget’s properties.

The search part has additional configuration in the widget (see properties below).

Properties

The popup window can be configured using the following widget properties:

• default_search_index: when a user searches in the popup, this index is used by default

• show_indexes: in the popup, when set to True, a drop-down list is shown with the index to be used for searching. If set to False, default_search_index will be used.

• size: in case of single-select widget, the default is set to 30. In case of multi-select, default is 8.

• available_indexes: optional dictionary that lists all the indexes that can be used for searching. Format: {‘<catalog index>’:’<friendly name’>, … } The friendly name is what the end-users sees to make the indexes more sensible for him. If you do not use this property then all the indexes will be shown (I think nobody should allow this to happen!).

• allow_search: shows the search section in the popup

• allow_sorting: allows you change the order of referenced objects (requires multiValued=1)

• allow_browse: shows the browse section in the popup

• startup_directory: directory where the popup opens. Optional. When omitted, the current folder is used or in the case where a property refwidget_startupdirectories under site_properties is found it is searched for a startup_directory.

  Property is a lines field having the following format:

  path1:path2

  path1 is the path where all widgets being under it set startup_directory to path2 if no startup_directory is set.

• startup_directory_method: the name of a method or variable that, if available at the instance, will be used to obtain the path of the startup directory. If present, ‘startup_directory’ will be ignored.

• restrict_browsing_to_startup_directory: allows you to restrict the breadcrumbs (‘allow_browse’ property) to contents inside the ‘startup_directory’ only. So you are not able to walk up in the hierarchy. (default: 0 = disabled)

• image_portal_types: specify a list of image portal_types. Instances of these portal types are being previewed within the popup widget

• image_method: specifies the name of a method that is added to the image URL to preview the image in a particular resolution (e.g. ‘mini’ for thumbnails)

• show_review_state: allows you to display the workflow state for objects (off by default)

• show_path: display the relative path (relative to the portal object) of referenced objects

• only_for_review_states: items are only referencable if their workflow state matches the ones a specified (default: None = no filtering by workflow state)

• history_length: enable a history feature that show the paths of the last N visited folders (default : 0 = no history)

• force_close_on_insert: closes the popup when the user choses insert. This overrides the behavior in multiselect mode.

• base_query: defines query terms that will apply to all searches, mainly useful to create specific restrictions when allow_browse=0. Can be either a dictonary with query parameters, or the name of a method or callable available in cotext that will return such a dictionary.

This add-on comes with an example content type that uses this widget. You can enable the installation of the type by uncommenting the appropriate line in Install.py under Extension. See ATReferenceBrowserDemo.py.

Design notes

Both the templates (widget and popup) are prototypes. There are still some inline styles, especially in the popup because I didn’t want to tweak with plone’s css stuff and I didn’t want to do hacking and tricking to incorporate a stylesheet myself.So, that’s still a point of interest.

Furthermore I made some design decisions. Right now, in the popup window, all objects are shown (when browsing) and objects that may be referenced to are bold and the other objects are greyed out. I chose to show the non-referenceable objects too because they may be an important part of the context that help the user search for the desired objects to browse to. Another thing that I chose for is that in case of a multi-value widget, the popup remains open so that you can continue to add references without having to reopen the popup over and over again. Problem is that you have to close the window yourself. This may change if it turns out to be an annoyance.

A thing that is more related to forms in general is that the items in the multiselect listbox need to be selected before Save is clicked otherwise only the selected items are submitted. That kinda sucks usability-wise because now the user basically has to make two selections: first by choosing the items in the popup and secondly by selecting them again in the listbox. Right now I made it so that the items are selected by default but if the user starts clicking in the list, then there might be an issue. Btw, the inandout widget has the same problem. Best would be to select all the items in a script just before the form is submitted so that the complete list is submitted. But that requires changes in the base_edit form I think. But it’s something to think about since there are now already two widgets that needs to be prepared like this (inandout and this one, haven’t looked at picklist though, could have the same problem).

Anyway, have fun with it and if you have suggestions please let me know. If you see problems, please fix them when you can.

Changelog

2.0.5 - October 5,2009

• Declare package dependencies. [hannosch]

• Let breadcrumbs respect navigation root This fixes http://dev.plone.org/plone/ticket/9373. [tom_gross]

2.0.4 - December 29, 2008

• The new property ‘startup_directory_method’ was used without guard. Since old instances in a migrated db wouldn’t have this property, this would effectively block editing of nearly all ATContentTypes objects in an upgraded db. Fixes reopened http://dev.plone.org/plone/ticket/8347. [smcmahon]

• Fixed catalog search call, it should get the query as keywords, not a dict. This makes ATRBW work with collective.solr. [fschulze]

2.0.3 - August 18, 2008

• Fixed missing project name from registerType method. This closes http://dev.plone.org/plone/ticket/8369. [garbas, hannosch]

• Fixed undefined name in startup_directory_method. This closes http://dev.plone.org/plone/ticket/8347. [hannosch]

2.0.2 - July 4, 2008

• Re-enabling ‘Remove reference’ button so that in multiValue=False mode there’s a way to actually unset a singly chosen reference. This was a feature regression introduced in Plone 3.0.x and until some other UI paradigm emerges, this should be there. This isn’t a problem in multiValue mode, as the checkbox UI allows the disabling of any individual referenced objects. This fixes http://dev.plone.org/plone/ticket/6950. [andrewb]

• Remove bogus leading whitespace. [wichert]

• Added new property ‘startup_directory_method’. It defines a method that, if available at the instance, will be used to obtain the path of the startup directory. [rsantos]

• Inserted references were not checked by default on Internet Explorer 7. This closes http://dev.plone.org/plone/ticket/7936. [hannosch]

• Added new property ‘hide_inaccessible’. When set, it changes the widget behaviour in view mode so that it hides all the items from the list of references for which a user do not have the View permission (instead of presenting the user with the login screen). In case of any problems please contact me via [e-mail]. [triquetra]

2.0.1 - September 10, 2007

• Added a reference_edit macro to the referencebrowser.pt template and call it from the edit macro. This makes it reusable by other widgets. [deo]

2.0 - August 9, 2007

• No changes. [hannosch]

2.0rc1 - July 9, 2007

• Changed an invalid div tag inside a ul to a li tag in referencebrowser.pt. [hannosch]

• Small i18n markup correction. [hannosch]

2.0b4 - May 5, 2007

• Removed five:registerPackage as it is causing problems in ZEO environments. [hannosch]

2.0b3 - May 1, 2007

• Death to tabindexes! [limi]

• Use getToolByName to get the portal_properties tool [wichert]

• ATReferenceBrowserWidget now uses checkboxes for displaying the selection (instead of a selection field). [jvloothuis]

• Removed unused and wrong types_param definition throwing errors in some configurations. (There is no mandatory “allowed_types” attribute on field definitions you can rely on.) If this line was good for anything, please re-add it in a failsafe version. [deichi]

2.0b2 - March 23, 2007

• Replaced all getToolByName calls with getUtility. [hannosch]

2.0b1 - March 5, 2007

• Converted to a regular Python package in the Products namespace. [hannosch]

• Removed lots of BBB code. We require Archetypes 1.5 now. [hannosch]

• Replaced renderAllTheStylesheets with new content provider for inclusion of the CSS files. [fschulze]

• Add an option to show all results immediately. [alecm]

• Added .metadata files for the two javascripts to tie them to the HTTPCACHE. [reinout]

1.7.1 - January 16, 2006

• No longer show all search results by default when allow_browse is off because it can be very very slow. [alecm]

• Undid the fix for #5996, because it broke basic functionality. [ajung]

1.7 - December 13, 2006

• Now the popup also works for multiselect archetypes fields with the id content (see comments in referencebrowser_setReference). http://dev.plone.org/plone/ticket/5996 [fRiSi]

• The widget now tries to sort references on their order attribute which only exists for orderablereferencefield references. (therefore the tal:on-error). This solves http://dev.plone.org/plone/ticket/5995 but could be relaced by a condition such as widget/isOrderable as proposed in #5995. [fRiSi]

• Fixed simple TAL markup bug which prevented show_review_state from working. This closes http://dev.plone.org/plone/ticket/5924. [hannosch]

1.6 - November 4, 2006

• listFolderContents requires ‘List folder contents’ which isn’t always available, avoid unauthorized errors in these cases by returning []. This makes the popup marginally less efficient for some combinations of widget parameters. [alecm]

• added ‘restrict_browsing_to_startup_directory’ property [ajung]

1.5 - September 8, 2006

• Fixed incorrect i18n markup. [hannosch]

• Fixed unclickable back and close links in the popup view in IE. This closes http://dev.plone.org/plone/ticket/5491. [hannosch]

• Corrected two little XHTML conformance issues. [hannosch]

• Fixed some import locations for AT 1.5 compatibility. [hannosch]

• added ‘history_length’ property [ajung]

1.4 - June 1, 2006

• Added ‘only_for_review_states’ property. [ajung]

• Added support for (optional) ‘additionalReferenceInfo’ method that can be used to add additional information for referencable items. [ajung]

1.3 - May 15, 2006

• Removed empty and unused i18n folder. [hannosch]

• Allow empty queries if there are some other constrains provided and allow_browse is false. This closes http://dev.plone.org/plone/ticket/5181. [hannosch]

• Changed call to here.folderlistingFolderContents() back to here.listFolderContents() because this method is not available on the Plone Site object. (so Home did no longer work) [fRiSi]

• Refactored the breadcrumb area to not use REQUEST[‘PARENTS’] anymore and added i18n support (RTL and translation for ‘Home’). REQUEST[‘PARENTS’] was evil because if did not work out for sites that that switch the skin by url and manipulate SiteRoot [fRiSi]

• Added ‘image_portal_types’ and ‘image_method’ properties. This allows you to specify a list of image portal types that are display inside the popup widget as images using the ‘image_method’ (e.g. to show images to be referenced as thumbnails) [ajung]

• Added ‘show_review_state’ property [ajung]

• Extended functionality of startup_directory property [spamsch]

• Added ‘allow_sorting’ property to order to allow reordering of multiValued ReferenceFields. [ajung]

• Added ‘show_path’ property [ajung]

1.2

• Added a slot for overriding the ‘at_url’ path to the object, so that the widget can be used in scenarios where the path to the relevant object isn’t so obvious (in Fate for example). [alecm]

• skins/…/referencebrowser_popup.pt: Changed call to ‘here.listFolderContents()’ to ‘here.folderlistingFolderContents()’ in order to avoid requiring the ‘List folder contents’ permission on the folder to be browsed. [raphael]

• Made compatible with CMF 2.0 (CMF <= 1.4) isn’t supported anymore [hannosch]

1.1

• Added handler for the popup.

• Removed duplicate color definition in popup window.

1.0.1

• Converted templates to own i18n domain [hannosch]

• Fixed an allowed_types_method handling bug [alecm]

• fieldName may not be the same as field.getName() due to the way BaseObject.widget() works. This strangeness is used to make Topics/Criteria work, but makes ATRBW unusable in criteria. Now it works. [alecm]

• Fixed allowed_types handling so that it respects allowed_types_method, and fixed the method handling. [alecm]

• Fixed some base_query brokenness when allow_browse is enabled. [alecm]

• Added i18n infrastructure. [hannosch, naro]

• Added support for CSSRegistry.

1.0

• Added property (search_catalog) to allow querying of alternate catalogs (e.g. CMFMember’s member_catalog). [alecm]

• Added message in the popup when adding items in multi-select mode. [limi]

• Fixed a bug that occured when setting references on objects located in the portal root. [alecm]

• Added base_query property which takes a dictionary or method that returns a dictionary containing a catalog query to use as a filter (most useful with allow_browse disabled). All portal_type restrictions use this mechanism now which allows for proper use of the field property allowed_types_method to make the types restrictions dynamic. [alecm]

0.2.1

• Fixed problem with portal_factory.

• Fixed problem with startup_directory.

• Removed automatic install of the demo type.

• Added startup_directory patch. [optilude]

0.2 - September 9, 2004

• Added batched view.

• Fixed a problem with multiValued.

• Added view link that opens the object in a new browser window so you can check if that’s the object you are looking for.

• Added ‘back’ link that does a javascript:history.back() so you can return to the browser mode after you’ve done a search.

• Removed possibility to link to the object itself.

• Made the popup window a bit wider and higher.

• Modified the ‘close window’ link. Now sits next to the ‘back’ link.

• Added startup_directory property for the widget to force another startup folder in the portal for the popup window.