Metadata-Version: 1.0
Name: plone.app.z3cform
Version: 0.4.0
Summary: A collection of widgets and templates, and other components for with z3c.form in Plone
Home-page: http://pypi.python.org/pypi/plone.app.z3cform
Author: Plone Foundation
Author-email: plone-developers@lists.sourceforge.net
License: GPL
Description: =================
        plone.app.z3cform
        =================
        
        Abstract
        ========
        
        A collection of widgets and templates, and other components for use
        with `z3c.form`_ in Plone_.  This is much related to `plone.z3cform`_,
        the library that enables Zope 2 applications to use z3c.form.
        
        .. _z3c.form: http://pypi.python.org/pypi/z3c.form
        .. _Plone: http://plone.org
        .. _plone.z3cform: http://pypi.python.org/pypi/plone.z3cform
        
        WYSIWYG widget
        ==============
        
        The ``wysiwyg`` package provides an implementation of the Plone
        WYSIWYG widget compatible with ``z3c.form``.  This will allow you to
        use Kupu, FCKeditor and other editors compatible with the Plone
        WYSIWYG interface in your ``z3c.form`` forms.
        
        To use, simply set the widget factory for the widget you'd like to be
        displayed with the WYSIWYG widget:
        
        >>> from zope import interface, schema
        >>> from z3c.form import form, field
        >>> from z3c.form.interfaces import INPUT_MODE
        >>> from plone.app.z3cform.wysiwyg.widget import WysiwygFieldWidget
        
        >>> class IProfile(interface.Interface):
        ...     name = schema.TextLine(title=u"Name")
        ...     age = schema.Int(title=u"Age")
        ...     bio = schema.Text(title=u"Bio")
        
        >>> class MyForm(form.Form):
        ...     fields = field.Fields(IProfile)
        ...     fields['bio'].widgetFactory[INPUT_MODE] = WysiwygFieldWidget
        
        
        Query select widget
        ===================
        
        The ``queryselect`` module provides a query source compatible with
        ``z3c.formwidget.query`` which combines to a selection field that can
        be queried.
        
        The native value type for the widget is Archetypes UID collections.
        The default implementation will simply search using the
        ``SearchableText`` index in the portal catalog.
        
        This is how your form schema could look like:
        
        >>> from zope import interface, schema
        >>> from plone.app.z3cform.queryselect import ArchetypesContentSourceBinder
        
        >>> class ISelection(interface.Interface):
        ...     items = schema.Set(
        ...         title=u"Selection",
        ...         description=u"Search for content",
        ...         value_type=schema.Choice(
        ...             source=ArchetypesContentSourceBinder()))
        
        Optionally, instead of storing Archetypes UIDs, you can choose to use
        ``persistent.wref``, i.e. weak references, instead of UIDs:
        
        >>> from plone.app.z3cform.queryselect import uid2wref
        >>> factory = uid2wref(ISelection['items'])
        
        To store weak references instead of UIDs you would register such a
        factory as a component adapting the context.  The factory
        automatically provides the interface which defines the field.
        (XXX: Please rewrite this paragraph.)
        
        
        =====================
        KSS inline validation
        =====================
        
        First, let's set up KSS debug mode:
        
        >>> from zope.interface import alsoProvides
        >>> from kss.core.tests.base import IDebugRequest
        >>> from zope.publisher.browser import TestRequest
        >>> from zope.annotation.interfaces import IAttributeAnnotatable
        
        >>> def make_request(form={}):
        ...     request = TestRequest()
        ...     request.form.update(form)
        ...     alsoProvides(request, IDebugRequest)
        ...     alsoProvides(request, IAttributeAnnotatable)
        ...     return request
        
        Then we create a simple z3c form
        
        >>> from zope import interface, schema
        >>> from z3c.form import form, field, button
        >>> from plone.app.z3cform.layout import FormWrapper
        
        >>> class MySchema(interface.Interface):
        ...     age = schema.Int(title=u"Age")
        
        >>> class MyForm(form.Form):
        ...     fields = field.Fields(MySchema)
        ...     ignoreContext = True # don't use context to get widget data
        ...
        ...     @button.buttonAndHandler(u'Apply')
        ...     def handleApply(self, action):
        ...         data, errors = self.extractData()
        ...         print data['age'] # ... or do stuff
        
        >>> class MyFormWrapper(FormWrapper):
        ...     form = MyForm
        ...     label = u"Please enter your age"
        
        >>> from zope.component import provideAdapter
        >>> from zope.publisher.interfaces.browser import IBrowserRequest
        >>> from zope.interface import Interface
        
        >>> provideAdapter(adapts=(Interface, IBrowserRequest),
        ...                provides=Interface,
        ...                factory=MyFormWrapper,
        ...                name=u"test-form")
        
        Let's verify that worked:
        
        >>> from zope.component import getMultiAdapter
        >>> context = object()
        >>> request = make_request()
        >>> formWrapper = getMultiAdapter((context, request), name=u"test-form")
        >>> formWrapper
        <Products.Five.metaclass.MyFormWrapper object ...>
        >>> formWrapper.form
        <class 'plone.app.z3cform.tests.example.MyForm'>
        
        >>> del context, request
        
        Inline validation
        -----------------
        
        Inline validation is invoked via the @@kss_z3cform_inline_validation view.
        
        >>> from zope.interface import Interface, implements
        >>> class Bar(object):
        ...     implements(Interface)
        >>> context = Bar()
        >>> request = make_request(form={'form.widgets.age': 'Title'})
        >>> view = getMultiAdapter((context, request), name=u"kss_z3cform_inline_validation")
        
        This is wired up with KSS. When the user leaves a form control with inline
        validation enabled, it will be called with the following parameters:
        
        >>> view.validate_input(formname=u'test-form', fieldname=u'form.widgets.age', value='Title')
        [{'selectorType': 'css', 'params': {'html': u'<![CDATA[The entered value is not a valid integer literal.]]>', 'withKssSetup': u'True'},
        'name': 'replaceInnerHTML',
        'selector': u'#formfield-form-widgets-age div.fieldErrorBox'},
        {'selectorType': 'htmlid',
        'params': {'value': u'error'},
        'name': 'addClass',
        'selector': u'formfield-form-widgets-age'}]
        
        >>> request = make_request(form={'form.widgets.age': '20'})
        >>> view = getMultiAdapter((context, request), name=u"kss_z3cform_inline_validation")
        >>> view.validate_input(formname=u'test-form', fieldname=u'form.widgets.age', value='20')
        [{'selectorType': 'css', 'params': {}, 'name': 'clearChildNodes', 'selector': u'#formfield-form-widgets-age div.fieldErrorBox'},
        {'selectorType': 'htmlid', 'params': {'value': u'error'}, 'name': 'removeClass', 'selector': u'formfield-form-widgets-age'},
        {'selectorType': 'css', 'params': {'name': u'display', 'value': u'none'}, 'name': 'setStyle', 'selector': '.portalMessage'},
        {'selectorType': 'htmlid', 'params': {'html': u'<![CDATA[<dt>info</dt><dd></dd>]]>', 'withKssSetup': u'True'},
        'name': 'replaceInnerHTML', 'selector': 'kssPortalMessage'},
        {'selectorType': 'htmlid', 'params': {'name': u'class', 'value': u'portalMessage info'},
        'name': 'setAttribute', 'selector': 'kssPortalMessage'},
        {'selectorType': 'htmlid', 'params': {'name': u'display', 'value': u'none'}, 'name': 'setStyle', 'selector': 'kssPortalMessage'}]
        
        
        Changelog
        =========
        
        0.4.0 - 2008-07-31
        ------------------
        
        * Add inline validation support with KSS
        
        * Require zope.component <= 3.4.0 to prevent compatibility issues with
        five.localsitemanager, of which a buggy version (0.3) is pinned by
        plone.recipe.plone 3.1.4.  Upgrade to this version if you're seeing::
        ...
        Module five.localsitemanager.registry, line 176, in registeredUtilities
        ValueError: too many values to unpack
        
        0.3.2 - 2008-07-25
        ------------------
        
        * Fixed a bug in macros.pt where 'has_groups' and 'show_default_label'
        for fieldsets were set in the 'form' macro, rendering the 'field'
        macro unusable by itself.
        
        0.3.1 - 2008-07-24
        ------------------
        
        * Fixed a bug where we would use the form macros defined in
        plone.z3cform instead of our own.
        
        0.3 - 2008-07-24
        ----------------
        
        * Create this package from Plone-specific bits that have been factored
        out of plone.z3cform.
        
        
Keywords: zope plone form widget template
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Framework :: Zope2
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
