Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A reference browser widget (Maintainer Timon Tschanz)

Project Description


This Widget provides a Referencebrowser and a searchfield, which allows users to select references.

The basequery is all types which are not in the types_not_searched property all modification to the allowed types are relative to this query.

Traversal or Selectability can be changed for all widgets with the IReferenceSettings registry interface or per widget with the widget parameters.

The widget takes the following parameters:
  • allow_traversal: These Types are traversable
  • block_traversal: These Types are not traversable
  • selectable: These Types are selectable
  • nonselectable: These Types are not selectable
  • start: The path first opened. Can either be a callable or a path. Additionaly the strings “parent”, “navroot”, “ploneroot” can be used.
  • allow_nonsearched_types: If this is set to true all the types will be traversable and selectable.
  • override: drops all global config and the base query if a list is passed to the widget. All types need to be added to be selectable.
  • traversal_query: Updates the query used vor traversing by the given dict. The dict passed will be updated after everything is allready done. So make sure not to override sort_on/sort_order attributes.


With a RelationeChoice or RelationList of RelationChoice a source can be configured along with the field. The ContextSourceBinder makes sure that only valid content can be selected.

By default, the source binder only checks for a valid portal_type when selecting content.

The default_filter implementation therefore looks like this:

def default_filter(source, value):
    Return ``True`` when the object is selectable, ``False``
    when it is not selectable.

    return value.portal_type in get_selectable_types_by_source(source)

Feel free to add your own filter method as source parameter in your field. Example:

from ftw.referencewidget.filter import DefaultSelectable

class CustomClass(DefaultSelectable):
    def is_selectable(self):
        return bool(..)

realtionchoice_restricted_title = RelationChoice(
    title=_(u'Related Choice Restricted Title'),

The filter takes two parameter the actual source object and a value, which is the content object.

Only ReferenceObjSourceBinder are supported. The SourceBinder takes the following parameters:

  • selectable: These types are selectable
  • nonselectable: These Types are not selectable
  • allow_nonsearched_types: If this is set to true all the types will be traversable and selectable.
  • override: drops all global config and the base query if a list is passed to the widget. All types need to be added to be selectable.
  • selectable_class: Custom ISelectable Class to determine if a content is selectable or not.

The parameters are same as for the widget (Backwards compatibility with 1.x releases).

Fields combinations (Registered converter)

The following combinations are supported:

  • RelationList with value_type Relation –> Stores a List of RelationValues
  • RelationList with value_type RelationChoice –> Stores a List of RelationValues
  • Relation –> Stores a RelationValue
  • List of RelationChoice –> Stores a list of absolute paths, without the portal root part
  • TextLine –> Stores a absolute path as string, without the portal root part


1.4.2 (2017-08-29)

  • Bugfix for DataGridField support if Plone Site is inside a mount point. [mbaechtold]

1.4.1 (2017-08-08)

  • Add support for “collective.z3cform.datagridfield”. [mbaechtold]

1.4.0 (2017-07-07)

  • Implement display mode for the reference widget. [mathias.leimgruber]
  • Change name of sample content buildour registry entry to avoid conflicts. [mathias.leimgruber]
  • Implement path restriction option. [mathias.leimgruber]
  • Render hidden input elements for given references, instead of render them only by Javascript. This way the widget behaves more like all other plone widgets. [mathias.leimgruber]
  • Implement a additional traversal_query parameter for the widget. [mathias.leimgruber]
  • Implement ReferenceObjPathSource for IRelationChoice fields. [mathias.leimgruber]

1.3.0 (2016-11-09)

  • Implement some sort options. [mathias.leimgruber]
  • Use to follow renamed and moved content. Also do not fail if the content has been removed. [mathias.leimgruber]

1.2.3 (2016-10-18)

  • Fix edge case (mainly for tests) if the value passed to the IList/Widget converter is not a list, but a string. [raphael-s]

1.2.2 (2016-10-18)

  • Implement testbrowser widget. [raphael-s]

1.2.1 (2016-10-17)

  • Respect missing_value set by the field. [tschanzt]
  • Implement support for ITextLine only with ReferenceWidget. [mathias.leimgruber]

1.2.0 (2016-10-04)

  • Show absolute path starting at the plone root for the selected value. [mathias.leimgruber]
  • Remove the list style type and the obsolete spacing for the selected elements. [mathias.leimgruber]
  • Implement support for IList of IRelationChoice explicitly. Check Readme for more informations [mathias.leimgruber]

1.1.0 (2016-09-27)

  • Ignore empty value for multiple value field. [mathias.leimgruber]
  • Support chameleon by not rendering handlebar templates. [jone]

1.0.4 (2016-09-19)

  • Make it possible to remove an given internal reference (radio button). [mathias.leimgruber]
  • Ignore empty value for single value field. [mathias.leimgruber]
  • Fix search by pressing the “enter” button. [mathias.leimgruber]
  • Always unbind the click event before binding a new one on the ref button. [mathias.leimgruber]

1.0.3 (2016-09-14)

  • Same as 1.0.2 but uploaded to PyPI. [mbaechtold]

1.0.2 (2016-09-14)

  • Reload Items when overlay is reloaded. [tschanzt]
  • Respect Type constraints on search. [tschanzt]

1.0.1 (2016-09-09)

  • Ignore empty strings in converter. [tschanzt]
  • Improve overlay behavior (close on click outside the overlay + close on ESC). [mathias.leimgruber]
  • Get Widget name on overlay creation. [tschanzt]

1.0.0 (2016-09-07)

  • Initial release [tschanzt]
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
ftw.referencewidget-1.4.2.tar.gz (609.1 kB) Copy SHA256 Checksum SHA256 Source Aug 29, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting