Metadata-Version: 1.0
Name: collective.z3cform.datagridfield
Version: 0.7
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.z3cform.datagridfield to your buildout eggs.::
        
            eggs=\
                ...
                collective.z3cform.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
            
            from collective.z3cform.datagridfield import DataGridFieldFactory, DictRow
            
            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=DictRow(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
        
        Storage
        -------
        
        The data can be stored as either a list of dicts or a list of objects.
        If the data is a list of dicts, the value_type is DictRow.
        Otherwise, the value_type is 'schema.Object'. 
        
        If you are providing an Object content type (as opposed to dicts) you
        must provide your own conversion class. The default conversion class
        returns a list of dicts, not of your object class. See the demos.
        
        Configuration
        -------------
        
        The widget can be customised via the updateWidgets method.
        
            def updateWidgets(self):
                super(EditForm, self).updateWidgets()
                self.widgets['table'].allow_insert = False # Enable/Disable the insert button on the right
                self.widgets['table'].allow_delete = False # Enable/Disable the delete button on the right
                self.widgets['table'].auto_append = False  # Enable/Disable the auto-append feature
                self.widgets['table'].allow_reorder = False  # Enable/Disable the re-order rows feature
        
        The widget contains an attribute 'columns' which is manipulated to hide column
        titles.
        
        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.
        
            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.
        
        TODO
        ----
        
            * Testing
        
            * The mechanism to hide/omit columns is cumbersome. This needs to be revisited.
        
            * Better styling of table in read-only mode.
              Merge the display and input versions of the layout.
        
            * kss validation - highlight the incorrect row, rather than the entire widget.
              Possibly show the error message in the field cell.
        
            * hidden mode
        
        Demo
        ----
        
        Examples are in the package collective.z3cform.datagridfield_demo.
        
        References
        ----------
         
            * http://pypi.python.org/pypi/Products.DataGridField
            * http://pypi.python.org/pypi/collective.z3cform.datagridfield_demo
        
        
        
        Changelog
        =========
        
        0.7 (2011-07-01)
        ----------------
        
        * Changed markup/javascript to prevent duplicate HTML id attributes. Changed
          Javascript to allow for datagrid page templates that don't use tables.
          [dextermilo]
        
        * Improve spacing in CSS.
          [davisagli]
        
        * Revert my fix to ensure that blank rows are added, because it duplicated
          a fix in z3c.form resulting in extra rows.
          [davisagli]
        
        0.6 (2011-05-17)
        ----------------
        
        * Search for datagridInitialise and datagridUpdateWidgets on the
          parent form, also when in a fieldset.
          [maurits]
        
        * Register templates on plone.app.z3cform.interfaces.IPloneFormLayer to
          take precedence over that packages list widget templates.
          [elro]
        
        * Make sure that updateWidgets is called to add blank rows even if the
          widget has no value.
          [davisagli]
        
        * When extracting a row value fails due to a validation error, convert
          widget values to field values so the value can be successfully applied
          to the grid widget.
          [davisagli]
        
        * Register a plone.supermodel handler for the DictRow so it can be used
          in supermodel models.
          [davisagli]
        
        * Depend on collective.z3cform.datagridfield_demo as a test extra;
          use the browser view from this package in the tests.
          [maurits]
        
        * _validate still used when import/exporting, fix up code so it works
          [lentinj]
        
        * Add a DictRow serializer for transmogrify.dexterity
          [lentinj]
        
        * Only use width:100% on input cells that are the only element in the cell
          [lentinj]
        
        * Reorder row indices backwards when adding rows. This means that adjacent
          rows don't share the same index temporarily, for example:-
          - Row 1 and 2 contain input:radio based widgets
          - Row 0 added, row renumbering starts
          - Row 1 widgets renamed 2
          - Both sets of input:radio share the same name, one deselected
          - Row 2 widgets renamed 3
          - . . . 
          [lentinj]
        
        * Use jQuery to clone rows, and clone the jQuery events on the rows.
          [lentinj]
        
        * Implemented reorder functionality
        
        0.5 (2011-02-08)
        ----------------
        
        * Put in the DictRow class (tks Martin Aspeli)
        
        * Moved the demo code out to a separate package collective.z3cform.datagridfield_demo
          (tks Laurence Rowe).
        
        * Removed superfluous lines from setup.py (tks Laurence Rowe).
        
        * Removed unnessary dependency on dexterity (tks Laurence Rowe).
        
        * Removed unnessary dependency on grok (tks Laurence Rowe).
        
        0.4 (2011-02-06)
        ----------------
        
        * Renamed the demo pages. The starting point is now @@demo-collective.z3cform.datagrid .
        
        * The widget can now be configured via the updateWidgets method. It
          is no longer necessary to create a custom factory.
        
        * The columns can now be omitted.
        
        * Provide a set of demo views for Object access.
        
        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
