Package: archetypes.referencebrowserwidget
IntroductionThis is an implementation of  referencebrowser widget. It
provides a widget used for Archetypes reference-fields. The widget can
be used on its own or as a dropin replacement of the ATReferenceBrowserWidget
in Plone 3 and is included in Plone >= 4.
Unlike the ATReferenceBrowserWidget, archetypes.refencebrowserwidget uses
an overlay instead of a popup to display the referencebrowser.VersionsVersion 1 of the product is a classical popup and works with Plone 3 and 4.
Version 2 of the product displays the browser as a jQuery overlay. Currently
it is only tested with Plone 4 and Plone 5.Change historyChangelog2.5.11 (2020-03-21)Bug fixes:Minor packaging updates. [various] (#1)2.5.10 (2017-12-11)Bug fixes:Drop dependency on plone.app.form
[MatthewWilkes]2.5.9 (2017-03-09)Bug fixes:Fix import location for Products.ATContentTypes.interfaces.
[thet]2.5.8 (2016-08-10)Fixes:Use zope.interface decorator.
[gforcada]2.5.7 (2016-02-12)Fixes:Fixed to work with Plone 5.  [vangheem]Updated to work with new plone.batchingpaginationselector as
well as with old one.  [thet]2.5.6 (2015-11-27)Fixes:Do not fail if a level of the path we are adding the object using
the ReferenceBrowser widget is not accessible by the current user.
[gbastien]2.5.5 (2015-10-27)Fixes:Show elements that the reader has no access to as “Undisclosed” instead of
throwing Unauthorized.
[pbauer]2.5.4 (2015-09-27)Follow README/CHANGES best practice.
[tisto]saner check for isNotSelf(), which was throwing KeyError
[alecpm, tkimnguyen]2.5.3 (2015-04-15)#23 added parameter ‘use_wildcard_search’ to widget, True by default
[gbastien]Replacedjqusage with$[keul]Fixing reference sorting issue due to global function refactoring done
on recent versions
[keul]Add labels for images in the popup widget.
[mitakas]#16 fix browsing for widgets in case field has setallowed_types(Warning: changed return value of view/getResult from[`brain1, brain2,..]`to[dict(item=brain1,browsable=True,referenceable=False),...]in case you customized popup.pt)
[fRiSi]2.5.2 (2014-09-11)Fix the “Clear Reference” button, which was not working due to the
refbrowser_removeReference function hidden in a anonymous function.
[thet]fixed allowed_types
[agitator]2.5.1 (2014-07-10)Fix JavaScript for compatibility with jQuery 1.9 by using jQuery’son,
attached to document, instead oflive.
[thet]Use foward compatable test for checked items with jQuery >=1.7
fixeshttps://dev.plone.org/ticket/13853[arterrey]Fix non-multi reference selection when the referenced object
no longer exists.
[mattss]2.5.0 (2014-02-23)Do not use portal_interface tool but @@plone_interface_info (PLIP #13770).
[ale-rt]Filter out references that are None.  This may happen when the
reference_catalog has links from a source to a no longer existing
target.
[maurits]2.4.19 (2013-08-13)Modified pagination links selector to use only “.listingBar” instead of
“div.listingBar”. The batchnavigation.pt template can be customized in a
theme and use a different structure, “ul.listingBar” for example.
[vincentfretin]If we have a sort_on parameter in base_query,
use it instead of getObjPositionInParent to display folder content.
[thomasdesvenain]2.4.18 (2013-05-23)Added two widget properties that allow to add help messages on popup,
in two slots (top and bottom).
[thomasdesvenain]Added css ids in popup.
[thomasdesvenain]Wrap jQuery functions for better compatibility.
[esteele]2.4.17 (2013-03-05)2.4.15 broke non-multi reference selection. Added code to discriminate
between multi and single widget id. Fixeshttp://dev.plone.org/ticket/13402[smcmahon]2.4.16 (2013-01-13)Add an option of searching for related items by path.
[plamut]2.4.15 (2012-12-14)Make new added references sortable with already existing ones
while editing a content.  Fixeshttp://dev.plone.org/plone/ticket/13271[gbastien]Use HTML5 placeholder attribute on search box. Replaces deprecated
inputLabel class.
[danjacka]2.4.14.1 (2012-11-07)Fixed typo
[tomgross]2.4.14 (2012-10-18)Use normalizeString to create class names for an item’s portal type
and review state. Fixeshttp://dev.plone.org/plone/ticket/11400.
[danjacka]don’t let search fail on broken catalog
[tomgross]2.4.13 (2012-10-11)Restored a “view” link on linkable items (as with Plone 3):
It will open a preview of the element in a popup window.
[keul]Fixed referenced elements sort order on widget view.
[gbastien]Take search_index into account while used in popup search form.
[gbastien]2.4.12 (2012-08-11)Show item icons in popup.
[thomasdesvenain]Limit the width of checkboxes column in popup.
[thomasdesvenain]2.4.11 (2012-04-09)Fixed breadcrumbs internationalization in popup.
[thomasdesvenain]2.4.10 (2012-02-09)We can restrict browsable types, with browsable_types parameter on widget.
[thomasdesvenain]2.4.9 (2011-12-08)updated query to take allowed_types into account
[hpeteragitator]fixed form submission issue in ie #11984
[tom_gross]2.4.8 (2011-11-23)Completed MANIFEST.in
[tom_gross]2.4.7 (2011-11-23)Added MANIFEST.in
[tom_gross]2.4.6 (2011-11-23)Fixed release
[tom_gross]2.4.5 (2011-11-23)Fixed tests for plone.uuid >= 1.0.2
[tom_gross]2.4.4 (2011-08-19)Fix: text searches should search outside navigation root
[gotcha]2.4.3 (2011-07-04)Use label tags for selectable items.
[esteele]Fix: text search searches from navigation root.
[thomasdesvenain]moved checkPermission from widget template to helper
[tom_gross]Fix referencebrowser.js error when using allow_sorting = 1
[toutpt]2.4.2 (2011-06-02)Fix: overlay is not closed at item selection when field is multivalued.
[thomasdesvenain]Fix undefined variable checkPermission
[kiorky]Fix error in refbrowser_moveReferenceDown and refbrowser_moveReferenceUp
which caused page reloads when a referenced item was moved twice.
Refshttp://dev.plone.org/plone/ticket/11859[cewing]Fix errors in sorting scripts which caused failure to detect items at head
or tail of list of referenced items. Refshttp://dev.plone.org/plone/ticket/11859[cewing]2.4.1 (2011-05-12)Add js hack to move overlay div to be a direct child of body to avoid
IE7 z-index bug. Fixeshttp://dev.plone.org/plone/ticket/11465.
[smcmahon]2.4 (2011-04-11)Fix regression in UID lookup in cases where plone.uuid is present, but not
used for Archetypes content (such as with plone.app.discussion 1.0 on Plone
4.0)
[davisagli]2.3 (2011-04-01)Fixed: widget did not work when search was disallowed.
[thomasdesvenain]2.2 (2011-02-25)FixedgetStartupDirectorymethod if astartup_directory_methodwas
defined, which cannot be traversed to.
[hannosch]check the references in the overlay that are checked in the widget
when the overlay is constructed or refreshed.
[csenger]Don’t disable checkboxes in overlay when an item is selected.
Remove the item from the value list when it is unchecked in
the value list. fixeshttp://dev.plone.org/plone/ticket/10786[csenger]2.1 (2011-01-03)Don’t issue deprecation-warnings on Zope 2.13
[tom_gross]Fixed title display for images with previewhttp://dev.plone.org/plone/ticket/11290[tom_gross]Fixed: do not return results that are outside of startup directory
if browse is restricted to it.
[thomasdesvenain]Qualify input tag id to avoid name-clashing. Fixeshttp://dev.plone.org/plone/ticket/11325.
[malthe]Made sure to always quoteat_urlwhen forwarding it in the templates.
[deo]Use URL quoting ofat_urleverywhere and quote in Python code not in
templates. Fixeshttp://dev.plone.org/plone/ticket/11297[tom_gross]Cleaned breadcrumb code Fixeshttp://dev.plone.org/plone/ticket/11289[tom_gross]2.0 (2010-09-06)Fixed i18n of “You are here:”.
[vincentfretin]Set a minimum version for jquerytools, to avoid this problem #10939
[do3cc]Encode search-URL. Fixeshttp://dev.plone.org/plone/ticket/10942[tom_gross]2.0rc2 (2010-07-29)Make sure the popup can be closed by the same ways as other popups in Plone
4. Fixeshttp://dev.plone.org/plone/ticket/10773[davisagli]Fixed bug: pop-up didn’t render id of file with empty title because of
improper use of TALES Path expression. Now uses browser method instead.
[kleist]2.0rc1 (2010-07-12)Fixed link rebinding of pagination links (thanks Mustapha Benali!)
[tom_gross]2.0b4 (2010-06-02)Fixed display of title (introduced in 2.0b3)2.0b3 (2010-06-02)Use getOverlay() instead of the deprecated getContent()
Closeshttp://dev.plone.org/plone/ticket/10548[esteele]Use content icons from sprite
Closeshttp://dev.plone.org/plone/ticket/10543[tom_gross]2.0b2 (2010-04-23)Adding missing return falses to prevent page reloads on reordering
[cah190,esteele]Mark already related objects visually in referencebrowser
[tom_gross]Only show sorting arrows on adding, if field is really sortable
[tom_gross]use Python doctest instead of zope.testing.doctest
[tom_gross]2.0b1 (2010-04-08)Updated package description
[tom_gross]Merged javascript files to one, which is included only with the widget
[tom_gross]Detailed DocumentationIntroductionThe archetypes.referencebrowserwidget is a Plone/Archetype-widget for relation-
fields. It adds a new reference widget that allows you to search or browse the
portal when creating references.  It can be used as a dropin-replacement for
the default ATReferenceBrowserWidget or as a standalone widget.To install it as a replacement just install the product via the quickinstaller.
For using it as a standalone widget see the demotype in demo.py.
The widget tries to be ui-compatible with its predecessor
ATReferenceBrowserWidget. You can use the same properties as for the standard
ReferenceField and for the ATReferenceBrowserWidget.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).The widget supports:catalog-only query of popup-contents. This is massive! permformance
win compared with ATReferenceBrowserWidget. Try accessing a folder
with 10k+ objects with both widgets.generic referencefield implementation via adapter. OOTB it supports
Archetypes.ReferenceField and plonerelations.ATField.overwrite the popup-template via namedtemplate-implementationresizeable popup via simple propertiesa good unittest and integrationtest coveragePropertiesThe 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. It points to “SearchableText” 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 popupallow_sorting: allows you change the order of referenced objects
(requires multiValued=1)allow_browse: shows the browse section in the popupsearch_catalog: Catalog to use. Defaults to: portal_catalogstartup_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:path2path1 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 widgetimage_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 objectsonly_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.hide_inaccessible: don’t show inaccessible objects (no permission) in view
mode.show_results_without_query: Don’t ignore empty queries, but display results.popup_width: Width of popup-window in pixel. Defaults to: 500popup_height: height of popup-window in pixel. Defaults to: 550popup_name: Name of template to be used for popup. To use another template
you have to register a named adapter for this template. Like:<zope:adapterfor=”Products.Five.BrowserView”
factory=”.view.default_popup_template”
name=”popup”
provides=”zope.formlib.namedtemplate.INamedTemplate”
/>See default implementation and unittests for examples.Design notesThis notes were taken from the original ATReferenceBrowserWidget. Since I
didn’t changed the ui, they are still valid (I think!?).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.ContributorsTom Gross,itconsense@gmail.comAuthorDanny Bloemendaal, some portions of code taken from the
ATReferenceBrowserWidget implementationAlexander Limi,limi@plone.orgfor improved UICarsten Senger,senger@rehfisch.de, improve usabilityMathieu Le Marec - Pasquet, template fixThomas Desvenan,thomasdesvenain@gmail.com- fixes and minor featuresPeter Holzer,hpeter@agitator.com- query update/fixGauthier Bastien,gauthier@imio.be- bug fixesHarald Friessnegger,harald@webmeisterei.com- bug fixesDownload