Metadata-Version: 1.0
Name: collective.formcriteria
Version: 0.1
Summary: Add forms for user enterable search criteria to collections/topic/smart folders.
Home-page: http://pypi.python.org/pypi/collective.formcriteria
Author: Ross Patterson
Author-email: me@rpatterson.net
License: GPL
Description: =======================
        collective.formcriteria
        =======================
        
        This package provides new criterion types based on the
        ATContentTypes.criteria types that are used to create a form at the
        top of the topic view.  Users can use the form to submit criteria to
        supplement any search criteria in the topic.  Values entered on the
        criteria tab for the topic become the default values on the form.
        
        Also provided is an alternative display layout that uses the folder
        contents table and can still display the search form viewlet.
        
        Form Criteria
        =============
        
        Create a topic as a normal user.
        
        >>> from Products.PloneTestCase import ptc
        >>> from Products.CMFPlone import utils as plone_utils
        >>> self.login()
        >>> home = portal.portal_membership.getHomeFolder(ptc.default_user)
        >>> foo_topic = plone_utils._createObjectByType(
        ...     container=home, type_name='Topic',
        ...     id='foo-topic-title', title='Foo Topic Title')
        
        Create some documents so that we have some search results.
        
        >>> bar_document = plone_utils._createObjectByType(
        ...     container=home, type_name='Document',
        ...     id='bar-document-title', title='Bar Document Title')
        >>> baz_document = plone_utils._createObjectByType(
        ...     container=home, type_name='Document',
        ...     id='baz-document-title', title='Baz Document Title')
        
        Create the browser object we'll be using.
        
        >>> from Products.Five.testbrowser import Browser
        >>> browser = Browser()
        >>> browser.handleErrors = False
        
        Log in as a normal user.
        
        >>> browser.open(portal.absolute_url())
        >>> browser.getLink('Log in').click()
        >>> browser.getControl('Login Name').value = ptc.default_user
        >>> browser.getControl(
        ...     'Password').value = ptc.default_password
        >>> browser.getControl('Log in').click()
        
        Before the topic has any form criteria, the serach form is not
        present.
        
        >>> browser.open(foo_topic.absolute_url())
        >>> browser.getForm(name="formcriteria_search")
        Traceback (most recent call last):
        LookupError
        
        Add a simple string form criterion for searchable text on the criteria
        tab.
        
        >>> browser.getLink('Criteria').click()
        >>> browser.getControl('Search Text').selected = True
        >>> browser.getControl(name="criterion_type", index=0).getControl(
        ...     'Form Text').selected = True
        >>> browser.getControl('Add criteria').click()
        >>> print browser.contents
        <...
        ...Search Text...
        ...A simple string form criterion...
        
        Set a default search term.
        
        >>> browser.getControl(
        ...     name=
        ...     "crit__SearchableText_SimpleStringFormCriterion_value"
        ...     ).value = 'bar'
        >>> browser.getControl(name="form.button.Save").click()
        >>> print browser.contents
        <...
        ...Changes saved...
        
        If no form value have been submitted, such as on a fresh load of the
        topic view, the default term will be used in the query returning only
        one of the documents.
        
        >>> len(foo_topic.queryCatalog())
        1
        
        >>> browser.getLink('View').click()
        >>> browser.getLink('Bar Document Title')
        <Link text='Bar Document Title'
        url='http://nohost/plone/Members/test_user_1_/bar-document-title'>
        >>> browser.getLink('Baz Document Title')
        Traceback (most recent call last):
        LinkNotFoundError
        
        Now that a form criterion has been added, the topic view displays the
        search form.
        
        >>> form = browser.getForm(name="formcriteria_search")
        
        Enter a search term and submit the query.  The topic will now list the
        other document.
        
        >>> form.getControl(name='SearchableText').value = 'baz'
        >>> form.getControl(name='submit').click()
        >>> browser.getLink('Bar Document Title')
        Traceback (most recent call last):
        LinkNotFoundError
        >>> browser.getLink('Baz Document Title')
        <Link text='Baz Document Title'
        url='http://nohost/plone/Members/test_user_1_/baz-document-title'>
        
        The search form also reflects the search term submitted rather than
        the default value submitted on the criteria tab.
        
        >>> browser.getForm(name="formcriteria_search").getControl(
        ...     name='SearchableText').value
        'baz'
        
        Contents View
        =============
        
        Change the topic's display layout to the contents view.
        
        >>> browser.getLink('folder_contents_view').click()
        >>> print browser.contents
        <...
        ...View changed...
        
        The view renders the contents form.
        
        >>> browser.getForm(name="folderContentsForm")
        <zope.testbrowser.browser.Form object at ...>
        
        The topic contents are listed in the contents table form.
        
        >>> browser.getControl('Bar Document Title')
        <ItemControl name='paths:list' type='checkbox'
        optionValue='/plone/Members/test_user_1_/bar-document-title'
        selected=False>
        >>> browser.getControl('Baz Document Title')
        Traceback (most recent call last):
        LookupError: label 'Baz Document Title'
        
        The search form is also rendered if form criteria are present.
        
        >>> form = browser.getForm(name="formcriteria_search")
        
        The contents view also reflects user submitted criteria.
        
        >>> form.getControl(name='SearchableText').value = 'baz'
        >>> form.getControl(name='submit').click()
        >>> browser.getControl('Bar Document Title')
        Traceback (most recent call last):
        LookupError: label 'Bar Document Title'
        >>> browser.getControl('Baz Document Title')
        <ItemControl name='paths:list' type='checkbox'
        optionValue='/plone/Members/test_user_1_/baz-document-title'
        selected=False>
        
        Changelog
        =========
        
        0.1 - 2008-05-24
        ----------------
        
        * Initial release
        
        
        TODO
        ====
        
        * Additional Criteria
        
        Currently the only form criterion is the simple string criterion.  The
        intention is to add form criteria for the rest of the ATCT criteria as
        well.  I'm only likely to get to the ones that I need without any
        further input, so if you want one in particular let me know.
        
        There are some caveats about implementing form criteria.  The name of
        the criterion fields do not actually correspond to name of the index
        queried.  For most criterion, the field rendered to collect the index
        value is the "value" field of the criterion, regardless of what index
        it's used for.  For some of the more complex criteria, it may not be
        true that all that is needed is to render the "value" field with the
        name of the index to be queried.  Form criteria will still be
        possible, but more complex.  In summary, implementation will be simple
        for criteria that need only render the "value" field which can be
        given the criterion.Field() as its name attribute and still work with
        the catalog query.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
