Metadata-Version: 1.0
Name: archetypes.referencebrowserwidget
Version: 2.0b2
Summary: A referencebrowser implementation for Archetypes
Home-page: http://pypi.python.org/pypi/archetypes.referencebrowserwidget
Author: Tom Gross
Author-email: itconsense@gmail.com
License: ZPL 2.1
Description: Introduction
        ************
        
        This 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.
        
        Versions
        ========
        
        Version 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.
        
        Change history
        **************
        
        Changelog
        =========
        
        2.0b2 - 23.04.2010
        ------------------
        
        * 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 - 08.04.2010
        ------------------
        
        * Updated package description
        [tom_gross]
        
        * Merged javascript files to one, which is included only with the widget
        [tom_gross]
        
        1.0rc1 - 02.04.2010
        -------------------
        
        * fixed widget for path-criterion in Plone 3.3
        [tom_gross]
        
        1.0b4 - 18.02.2010
        ------------------
        
        * again a broken tarball on pypi
        [tom_gross]
        
        1.0b3 - 17.02.2010
        ------------------
        
        * Fixed case where parent ul-element was missing for adding relations. This
        fixes
        http://dev.plone.org/plone/ticket/10172,
        http://dev.plone.org/plone/ticket/10215 and
        http://dev.plone.org/plone/ticket/10083
        [tom_gross]
        
        1.0b2 - 01.02.2010
        ------------------
        
        * Inserted conditional check in the widget, so it doesn't render an empty ul
        when there are no results. This is a backport of
        http://dev.plone.org/archetypes/changeset/12072 and refs
        http://dev.plone.org/plone/ticket/10083 and
        http://dev.plone.org/plone/ticket/9222
        [limi]
        
        
        1.0b1 - 21.12.2009
        ------------------
        
        * Add missing portal_path that prevented editing of content that contains if a
        multivalued reference has items set.
        [MatthewWilkes]
        
        1.0a6 - 01.12.2009
        ------------------
        
        * Fixed ``only_for_review_states`` of the widget to actually restrict.
        [hannosch]
        
        1.0a5 - 18.11.2009
        ------------------
        
        * Fix tests which were testing for the (incorrect) behaviour davisagli fixed.
        [optilude]
        
        * Make sure that a default value is passed in the request even for required
        multi-valued fields, so that the list of references only gets cleared if
        a value was actually passed for this field in the request form.
        [davisagli]
        
        1.0a4 - 14.11.2009
        ------------------
        
        * replaced cssQuery-call with jQuery one [esteele]
        * define portal which is used in the widget-template [santonelli]
        
        1.0a3 - 16.10.2009
        ------------------
        
        * egg 1.0a2 on pypi was broken [tom_gross]
        
        1.0a2 - 14.10.2009
        ------------------
        
        * simplified compatibility changes for ATCT 1.3 and 2.0 [hannosch]
        * provide fallbacks, if base_properties are not available [tom_gross]
        * be compatible with ATContentTypes 1.3 and 2.0 [tom_gross]
        
        1.0a1 - 21.08.2009
        ------------------
        
        * keep values in edit-mode, when edit form validates to false [tom_gross]
        * define an interface `IReferenceBrowserHelperView` for the helper view [tom_gross]
        * respect navigation root in breadcrumbs (Plone ticket #9379) [tom_gross]
        * added `getPortalPath`-method to helper-view, since global utool is no longer available in Plone 4 [tom_gross]
        
        0.11 - 03.06.2009
        -----------------
        
        * fixed Unauthorized error when referencing inaccessible targets [tomster]
        * added missing portal_path in refererencebrowser.pt (Thanks, Bert Vanderbauwhede)
        * fixed ambiguous method call in popup-view (Thanks, Bert Vanderbauwhede)
        * fixed javascript for order support in IE (Thanks, Rodrigo Ristow)
        
        0.10.1 - 05.05.2009
        -------------------
        
        * removed dependency for eggified zope
        * fixed tests for Plone 4 (tests pass on 3.2 and 4.0svn now)
        
        0.10 - 23.04.2009
        -----------------
        
        * Fixed unchecking of items when moving in IE [tom_gross]
        * Fixed handling of required multivalued fields to be standard. Throw a
        validation error instead of silently return to the previous value. [tom_gross]
        * Changed cssQuery-call with jquery-call in referencebrowser.js [tom_gross]
        * made base_properties optional
        * added egg dependencies
        
        0.9 - 13.11.2008
        ----------------
        
        * Fix usage of `aq_explicit` in favour of `aq_base`.
        [witsch]
        
        * Fix popup template to not required sessions.
        [witsch]
        
        * The startup directory method is now called with self aq wrapped. [regebro]
        
        0.8.1 - 06.11.2008
        ------------------
        
        * Fix 'Remove reference' when multiValued is a boolean instead of an int.
        [fschulze]
        
        * fixed popup for folderish objects [tom_gross]
        * show order arrows now for one entry only too [tom_gross]
        * popup now has a body-tag cssid: `atrefbrowserpopup`  (#8702) [tom_gross]
        * added tests for plone tickets #8347, #7608, #7965 [tom_gross]
        * fixed plone ticket #7557 [tom_gross]
        
        0.8 - 06.10.2008
        ----------------
        
        * Initial release
        * Forked Products.ATReferenceBrowserWidget
        * moved popup and scripts to z3-style views
        * use catalog-only implementation for displaying items in popup
        * added some tests
        * use namedtemplate-adapter for popup-template
        
        
        Detailed Documentation
        **********************
        
        Introduction
        ============
        
        The 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-implementation
        
        * resizeable popup via simple properties
        
        * a good unittest and integrationtest coverage
        
        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. 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 popup
        
        * allow_sorting: allows you change the order of referenced objects
        (requires multiValued=1)
        
        * allow_browse: shows the browse section in the popup
        
        * search_catalog: Catalog to use. Defaults to: portal_catalog
        
        * 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.
        
        * 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: 500
        
        * popup_height: height of popup-window in pixel. Defaults to: 550
        
        * popup_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:adapter
        for="Products.Five.BrowserView"
        factory=".view.default_popup_template"
        name="popup"
        provides="zope.formlib.namedtemplate.INamedTemplate"
        />
        
        See default implementation and unittests for examples.
        
        Design notes
        ============
        
        This 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.
        
        Contributors
        ************
        
        - Tom Gross, itconsense@gmail.com Author
        - Danny Bloemendaal, some portions of code taken from the
        ATReferenceBrowserWidget implementation
        - Alexander Limi, limi@plone.org for improved UI
        
        
        Download
        ********
        
Keywords: Relation Widget
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
