Metadata-Version: 1.0
Name: collective.z3cform.datagridfield
Version: 0.3
Summary: Version of DataGridField for use with Dexterity / z3c.form
Home-page: http://svn.plone.org/svn/collective/
Author: Kevin Gill
Author-email: kevin@movieextras.ie
License: GPL
Description: Introduction
        ============
        
        Licence: GNU General Public License
        
        This module provides a z3c.form version of the Products.DataGridField. This product
        was developed for use with Plone4 and Dexterity.
        
        Requirements
        ------------
        
            * Plone 4
            * z3c.forms
            * A browser with javascript support
            * jquery 1.4.3 or later
        
        Installation
        ------------
        
        Add collective.z3cforms.datagridfield to your buildout eggs.::
        
            eggs=\
                ...
                collective.z3cforms.datagridfield
        
        Example usage
        -------------
        
        This piece of code demonstrates a schema which has a table within it.
        The layout of the table is defined by a second schema.::
        
            from zope import schema
            from zope import interface
            from plone.directives import form
            
            form collective.z3cforms.datagridfield import DataGridFieldFactory
            
            class ITableRowSchema(interface.Interface):
                one = schema.TextLine(title=u"One")
                two = schema.TextLine(title=u"Two")
                three = schema.TextLine(title=u"Three")
            
            class IFormSchema(interface.Interface):
                four = schema.TextLine(title=u"Four")
                table = schema.List(title=u"Table"
                    value_type=schema.Object(title=u"tablerow", schema=ITableRowSchema))
            
            class EditForm(form.EditForm):
                extends(form.EditForm)
            
                grok.context(IFormSchema)
                grok.require('zope2.View')
                fields = field.Fields(IFormSchema)
                label=u"Demo Usage of DataGridField"
                        
                fields['table'].widgetFactory = DataGridFieldFactory
        
        Configuration
        -------------
        
        Unfortunately, due to the way in which the widgets and sub-widgets are setup, it
        is difficult to configure the widget after it is created. Instead, you create
        a customised factory with the configuration that you need.::
        
        
            def CustomisedDataGridFieldFactory(field, request):
                widget = DataGridField(request)
                rv = FieldWidget(field, widget)
                widget.allow_insert = False   # Enable/Disable the insert button on the right
                widget.allow_delete = False   # Enable/Disable the delete button on the right
                widget.auto_append = False    # Enable/Disable the auto-append feature
                return rv
        
            ...
                fields['table'].widgetFactory = CustomDataGridFieldFactory
        
        Manipulating the Sub-form
        -------------------------
        
        The DataGridField makes use of a subform to build each line. The main DataGridField
        contains a DataGridFieldObject for each line in the table. The DataGridFieldObject
        in turn creates the DataGridFieldObjectSubForm to store the fields.
        
        There are two callbacks to your main form:
        
            datagridInitialise(subform, widget)
            
            *   This is called when the subform fields have been initialised, but before
                the widgets have been created. Field based configuration could occur here.
        
            *   Note: omiting fields causes an error. If you want to omit fields, create
                a separate schema instead.
        
            datagridUpdateWidgets(subform, widgets, widget)
        
            *   This is called when the subform widgets have been created. At this point,
                you can configure the widgets, e.g. specify the size of a widget.
        
        Notes
        -----
        
        I have attempted to keep the markup close to Products.DataGridField, so that the
        styling approach is the same.
        
        If you are passing through a list of objects (as opposed to a list of dicts), you
        need to implement the dictionary interface on the object.
        
            def get(self, name, default=None):
                return getattr(self, name, default)
            
            def set(self, name, value):
                return setattr(self, name, value)
        
        
        TODO
        ----
        
            * I convert the return value to a list of dictionaries. It should be a list of objects
              of the correct type. The data transformations need to be looked at again.
        
            * Testing
        
            * The mechanism to hide columns is cumbersome. This needs to be revisited.
        
            * Better styling of table in read-only mode.
        
            * Move rows up / down
        
        Demo
        ----
        
        Examples of configurations are in the demo folder.
        Once you install this package, the demo views will be visible on your site. ::
        
            * http://localhost:8080/Plone/@@demo-simple-edit-form
        
        References
        ----------
         
            * http://pypi.python.org/pypi/Products.DataGridField
        
        
        
        Changelog
        =========
        
        0.3 (2011-02-04)
        ----------------
        
            * The auto-append functionality did not bind correctly for popup forms.
              I switched to using jQuery.live() instead of binding at document load time.
        
            * Added a menu to the demo pages
        
            * Added a display only form option.
        
            * Fixed the restructured text of the main README.txt so that it will show
              more friendly in PyPI.
        
Keywords: Plone,Dexterity,z3c.form
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Programming Language :: Python
