Metadata-Version: 1.0
Name: plone.app.z3cform
Version: 0.5.0
Summary: A collection of widgets, templates and other components for use with z3c.form and 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
        =================
        
        A collection of widgets and templates, and other components for use
        with `z3c.form`_ in Plone_.  This extends `plone.z3cform`_, the library that
        enables Zope 2 applications to use z3c.form, with Plone-specific markup and
        functionality.
        
        Please read the documentation for `z3c.form`_, which contains important
        information about using z3c.form in Zope 2 in general. For the most part,
        that package contains the "active" parts that you need to know about, and
        this package provides "passive" overrides that make the forms integrate with
        Plone.
        
        Installation
        ============
        
        To use z3c.form forms in Plone, you should install this package. First,
        depend on it in your own package's ``setup.py``, using the
        ``install_requires`` list. Then load its configuration form your own package's
        ``configure.zcml``, with::
        
        <include package="plone.app.z3cform" />
        
        Before you can use the forms, you also need to install the
        ``plone.app.z3cform:default`` GenericSetup extension profile. The best way
        to do that is to install it as a dependency of your own product's installation
        profile. In your ``metadata.xml``, add a dependency like::
        
        <metadata>
        ...
        <dependencies>
        ...
        <dependency>profile-plone.app.z3cform:default</dependency>
        </dependencies>
        </metadata>
        
        Note that if you don't install the product, and you are using standalone
        z3c.form forms (in Zope 2.12 or later), you will find that z3c.form complains
        about missing widgets. This is because the ``IFormLayer`` marker interface
        has not been applied to the request.
        
        In fact, the browser layer installed with this product's extension profile is
        ``plone.app.z3cform.interfaces.IPloneFormLayer``, which in turn derives from
        ``z3c.form.interfaces.IFormLayer``.
        
        Default macros
        ==============
        
        This package overrides the ``@@ploneform-macros`` view from `plone.z3cform`_,
        using standard Plone markup for form fields, fieldsets, etc.
        
        All the macros described in `plone.z3cform`_ are still available. In addition,
        you can use the ``widget_rendering`` macro to render all the default widgets,
        but none of the fieldsets (groups) or the fieldset headers (which would be
        rendered with the ``fields`` macro).
        
        Each widget is rendered using the ``@@ploneform-render-widget`` view, which by
        default includes the widget's label, required indicator, description, errors,
        and the result of ``widget.render()``.  This view may be overridden for
        particular widget types in order to customize this widget chrome.
        
        Inline form validation
        ======================
        
        This package installs AJAX handlers to perform inline field validation. On any
        form, the field will be validated when the user blurs a field.
        
        This relies on the KSS framework, and is only installed if ``plone.app.kss``
        is available. If you are using a custom form, note that you must define the
        following "kassattr" variables:
        
        * ``formname``, the name of the form view, defined on the ``<form />``
        element.
        * ``fieldname``, the name of the current field (same as the widget name),
        defined on an element wrapping the field.
        * ``fieldset``, defined for non-default fieldsets on the ``<fieldset />``
        element.
        
        This also assumes the standard Plone form markup is used. See
        ``templaes/macros.pt`` for details.
        
        .. _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 ``plone.app.z3cform.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 ``plone.app.z3cform.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.
        
        Changelog
        =========
        
        0.5.0 - 2010-04-20
        ------------------
        
        * Render errors from group form widget manager validators.  Fixes
        http://code.google.com/p/dexterity/issues/detail?id=96
        [davisagli]
        
        * Default to showing the default fieldset, rather than the first non-default
        fieldset.
        [davisagli]
        
        * Replace the required field indicator image with a unicode box, refs
        http://dev.plone.org/plone/ticket/10352
        [davisagli, limi]
        
        * Replaced the existing radiobutton-based boolean widget with the standard
        single checkbox Plone version.
        [limi]
        
        * Add @@ploneform-render-widget view, so that the widget chrome can be
        customized for particular widget types.
        [davisagli]
        
        * Added slots to the ``titlelessform`` macro. See ``README.txt`` in
        ``plone.z3cform`` for details.
        [optilude, davisagli]
        
        * Cleaned up templates to match Plone 4 conventions.
        [optilude]
        
        * Made templates and inline validation work with standalone forms as supported
        by plone.z3cform 0.6 and later.
        [optilude]
        
        * Installed a browser layer IPloneFormLayer with this package's extension
        profile. This inherits from z3c.form's IFormLayer, allowing the default
        widgets to work. You should always install this package in
        portal_quickinstaller before using z3c.form forms in Plone.
        [optilude]
        
        * Made the textlines widget the default for sequence types with text/ascii
        line value types. The default widget from z3c.form is too confusing.
        [optilude]
        
        * Use form method defined in form class. This allows HTTP GET forms.
        Before method was hardcoded to "post" in the template. [miohtama]
        
        0.4.9 - 2010-01-08
        ------------------
        
        * Remove unused (and broken on Plone 4) lookup of the current user's WYSIWYG
        editor preference.  The wysiwyg_support template does this for us.
        [davisagli]
        
        
        0.4.8 - 2009-10-23
        ------------------
        
        * Made the KSS validator use publish traversal instead of OFS traversal to find
        the form. This makes it usable with forms reached by custom IPublishTraverse
        adapters.
        [davisagli]
        
        * Added enable_form_tabbing option to not transform fieldsets into tabs.
        [vincentfretin]
        
        * Added an id to the generated form.
        [vincentfretin]
        
        * Fixed issue in macros.pt: fieldset.current hidden input was never generated.
        [vincentfretin]
        
        
        0.4.7 - 2009-09-25
        ------------------
        
        * Set plone i18n domain for "Info" and "Error" messages in macros.pt so they are translated.
        [vincentfretin]
        
        
        0.4.6 - 2009-07-26
        ------------------
        
        * Include plone.z3cform's overrides.zcml from our own overrides.zcml.
        [optilude]
        
        * Updated to collective.z3cform.datetimewidget>=0.1a2 to fix a ZCML conflict
        with z3c.form.
        [davisagli]
        
        
        0.4.5 - 2009-05-25
        ------------------
        
        * Made the KSS form support conditional on both kss.core and Archetypes being
        installed.
        [hannosch]
        
        * Use the date/time widgets from collective.z3cform.datetimewidget as the default
        widget for Date and Datetime fields.
        [davisagli]
        
        
        0.4.4 - 2009-05-03
        ------------------
        
        * Made the KSS validator use traversal instead of getMultiAdapter() to find
        the form. This makes it work on add forms.
        See http://code.google.com/p/dexterity/issues/detail?id=27
        [optilude]
        
        
        0.4.3 - 2009-04-17
        ------------------
        
        * Added a display template for the WYSIWYG widget.
        [optilude]
        
        * Make the ?fieldset.current query string variable work. Set it to the id
        of a fieldset other than default to pre-select a different fieldset, e.g.
        .../@@formview?fieldset.current=3
        [optilude]
        
        * Hide the 'default' fieldset if there's nothing to show there.
        [optilude]
        
        * Provide 'portal' variable in wysiwyg template, as its used by some editors.
        [davisagli]
        
        
        0.4.2 - 2008-09-04
        ------------------
        
        * Make the WYSIWYG widget work also for non-Acquisition wrapped
        content.
        
        
        0.4.1 - 2008-08-21
        ------------------
        
        * Removed maximum version dependency on zope.component. This should be left
        to indexes, known good sets or explicit version requirements in buildouts.
        If you work with zope.component >= 3.5 you will also need five.lsm >= 0.4.
        [hannosch]
        
        * Make use of new plone.z3cform support for looking up the layout template by
        adapter. This means that forms now no longer need to depend on
        plone.app.z3cform unless they want to use Plone-specific widgets.
        
        
        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
