Metadata-Version: 1.0
Name: infrae.plone.relations.form
Version: 1.0
Summary: Formlib widget to manage plone.app.relations relations in a plone site.
Home-page: http://svn.infrae.com/PloneComponent/infrae.plone.relations.form/trunk
Author: Sylvain Viollon
Author-email: sylvain@infrae.com
License: GPL
Description: *************************************
        Formlib widget for plone.app.relation
        *************************************
        
        .. contents::
        
        
        The purpose of this extension is to provide formlib widget to edit
        plone.app.relation relations. This have been tested with Plone 2.5 and
        Plone 3.
        
        Interface definition
        ====================
        
        Simple interface for our contents, using the custom Zope 3 field for
        relation::
        
        >>> from infrae.plone.relations.schema import PloneRelation
        >>> from zope.interface import implements, Interface
        >>> class ISimpleContent(Interface):
        ...    """Simple interface with relation."""
        ...    relation = PloneRelation(title=u"A relation",
        ...                             relation="relation1")
        
        
        In the user interface, Zope IntID are used to keep track of
        object. You can also use Archetype UID (check the ``configure.zcml``
        file), in this case all content must comes from the Referenceable
        class of Archetype (``Products.Archetypes.Referenceable``).
        
        
        Widget definition
        =================
        
        The plone relation widget is customisable, you can select different
        sub-widgets to select new items to add to relation. These sub-widgets
        can takes arguments. For instance here, you can put a restriction on
        ``content_type``.
        
        The widget is built using ``CustomWidgetFactory``::
        
        >>> from infrae.plone.relations.form import PloneRelationEditWidget
        >>> from infrae.plone.relations.form import PloneRelationSearchAddWidget
        >>> from zope.app.form import CustomWidgetFactory
        >>> widget_factory = CustomWidgetFactory(PloneRelationEditWidget,
        ...                                      add_widget=PloneRelationSearchAddWidget,
        ...                                      add_widget_args=dict(content_type='MySimpleContent'))
        
        Currently, there is three different widgets to add relations: one which
        does a catalog search with user input and let select result as object
        for relation, one which list objects (from the catalog always), one
        which use a Zope 3 vocabulary as input.
        
        The ``infrae.plone.relations.form.utility`` provides simples methods to
        build these widgets.
        
        Form definition
        ===============
        
        Now, we will do a simple edit form for a content using this interface::
        
        >>> from Products.Five.formlib import formbase
        >>> from zope.formlib import form
        >>> class EditSimpleContentForm(formbase.EditForm):
        ...    label = 'Edit form'
        ...    description = 'Form to edit relation'
        ...    form_fields = form.Fields(ISimpleContent)
        ...    form_fields['relation'].custom_widget = widget_factory
        
        
        It's easy ?
        
        Real test
        =========
        
        We added this code in the ``example.py`` file, and the form would be
        bind to Document. We load it now::
        
        >>> from Products.Five.zcml import load_string
        >>> load_string("""<configure xmlns="http://namespaces.zope.org/browser">
        ... <page name="relation.html"
        ...       for="infrae.plone.relations.form.example.IPloneRelationExample"
        ...       class="infrae.plone.relations.form.example.PloneRelationEditForm"
        ...       permission="cmf.ModifyPortalContent" />
        ... </configure>""")
        
        And now get an authenticated browser::
        
        >>> browser = self.getAuthenticatedBrowser()
        
        The front-page is a document, so we should get our form::
        
        >>> browser.open('http://nohost/plone/front-page/relation.html')
        >>> 'Plone relation edit form' in browser.contents
        True
        
        So we can search for Plone in this add widget, and should get one
        response, since by default there is only one document with the word
        *Plone*, the front page itself::
        
        >>> browser.getControl(name='form.relation.search_value').value='Plone'
        >>> browser.getControl(name='form.relation.search_button').click()
        
        And we got some results::
        
        >>> add_value = browser.getControl(name='form.relation.add_value:list')
        >>> add_value.getControl('Welcome to Plone').selected = True
        >>> browser.getControl(name='form.relation.add_button').click()
        >>> browser.getControl('Apply').click()
        >>> 'Updated on' in browser.contents
        True
        
        You can look up the ``README.EXT.txt`` and ``example.py`` file for
        more tests and examples.
        
        
        Changes
        =======
        
        1.0
        ~~~~~
        
        - Add more tests,
        
        - Remove translation marker: they triggers errors under Plone 3. Now
        this work with Plone 3 as well.
        
        0.9
        ~~~
        
        - First release, we need more functional or unit test to release 1.0.
        
        
        Credits
        =======
        
        The first version of this widget have been released with the help of
        the Flemish government of Belgium, for the application
        <http://www.zonderisgezonder.be>.
        
        You can help us as well to contribute to this product, by sending your
        remarks or patchs at the author email address (or ask for an SVN
        access).
        
Keywords: relationships plone widget formlib
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Framework :: Zope2
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
