Review formmodifier.py documentation.

docs/api/generated/formmodifier/plugin_dbui.formmodifier.FormModifier.configure.rst

+plugin_dbui.formmodifier.FormModifier.configure
+===============================================
+
+.. currentmodule:: plugin_dbui.formmodifier
+
+.. automethod:: FormModifier.configure
\ No newline at end of file

docs/api/generated/formmodifier/plugin_dbui.formmodifier.FormModifier.hide_fields.rst

+plugin_dbui.formmodifier.FormModifier.hide_fields
+=================================================
+
+.. currentmodule:: plugin_dbui.formmodifier
+
+.. automethod:: FormModifier.hide_fields
\ No newline at end of file

docs/api/generated/formmodifier/plugin_dbui.formmodifier.FormModifier.link_comboboxes.rst

+plugin_dbui.formmodifier.FormModifier.link_comboboxes
+=====================================================
+
+.. currentmodule:: plugin_dbui.formmodifier
+
+.. automethod:: FormModifier.link_comboboxes
\ No newline at end of file

docs/api/generated/formmodifier/plugin_dbui.formmodifier.FormModifier.merge_fields.rst

+plugin_dbui.formmodifier.FormModifier.merge_fields
+==================================================
+
+.. currentmodule:: plugin_dbui.formmodifier
+
+.. automethod:: FormModifier.merge_fields
\ No newline at end of file

docs/api/generated/formmodifier/plugin_dbui.formmodifier.FormModifier.set_mapper.rst

+plugin_dbui.formmodifier.FormModifier.set_mapper
+================================================
+
+.. currentmodule:: plugin_dbui.formmodifier
+
+.. automethod:: FormModifier.set_mapper
\ No newline at end of file

docs/api/generated/plugin_dbui.formmodifier.FormModifier.rst

+plugin_dbui.formmodifier.FormModifier
+=====================================
+
+.. currentmodule:: plugin_dbui.formmodifier
+
+.. autoclass:: FormModifier
+   :show-inheritance:
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: formmodifier/
+
+      ~FormModifier.configure
+      ~FormModifier.hide_fields
+      ~FormModifier.link_comboboxes
+      ~FormModifier.merge_fields
+      ~FormModifier.set_mapper
+
+
+
+
+

docs/api/generated/plugin_dbui.formmodifier.configure_forms.rst

+plugin_dbui.formmodifier.configure_forms
+========================================
+
+.. currentmodule:: plugin_dbui.formmodifier
+
+.. autofunction:: configure_forms
\ No newline at end of file

modules/plugin_dbui/fieldsmodifier.py

@@ -22,18 +22,19 @@ class FieldsModifier(Modifier):
             two keys/attributes:
 
             * extjs_fields (dict):
-                Ext JS configuration options for each field.
-                Keys are the database field names.
+              Ext JS configuration options for each field.
+              Keys are the database field names.
 
             * composite_fields (gluon.storage.Storage):
-                describe the fields embedded in the :class:`.FieldContainer`.
-                It has two attributes:
+              describe the fields embedded in the :class:`.FieldContainer`.
+              It has two attributes:
+
                     * main (list): the first field of the container
                     * fields.others (list): the others field.
 
-                Fields are identified by their database field names
-                and should belong to the database table defined
-                in the constructor.
+              Fields are identified by their database field names
+              and should belong to the database table defined
+              in the constructor.
 
     """
 

modules/plugin_dbui/formmodifier.py

@@ -18,17 +18,15 @@ MODIFIER_FORMS = 'modifier_forms'
 
 
 def configure_forms(db, **extjs):
-    """Apply to all form widgets the same configuration options.
-    Useful to set plugins in one go, for example.
+    """Apply a set of configuration parameters to all form widgets.
 
     Args:
         db (gluon.dal.DAL or list):
             list of forms to be modified. They are identified by their
-            associated table name.
+            associated database table name.
 
-    Note:
-        The keyword arguments define values for the Ext JS configuration
-        options of he ``Ext.form.Panel`` class.
+    Keyword Args:
+        **extjs: any configuration parameter of the ``Ext.form.Panel`` widget.
 
     """
     if isinstance(db, DAL):
@@ -44,48 +42,43 @@ def configure_forms(db, **extjs):
 
 
 class FormModifier(Modifier):
-    """Modifier to customise the form widget associated to a database table.
+    """Customise the form widget associated to the database
+    table *tablename*.
 
-    Attributes:
-        data.field_sets (list)
-        data.hidden_fields (list)
-        data.mapper (function)
-
-    """
-
-    def __init__(self, tablename):
-        """Initialize the form modifier associated to the database
-        table ``tablename``.
-
-        The data structure of the form modifier can be access
-        outside the class::
+    Args:
+        tablename (str): name of the database table
 
-            p = PluginManager('dbui')
-            modifier = p.dbui['modifier_forms'][tablename]
+    Attributes:
+        data (gluon.storage.Storage): storage containing the
+            instructions to tune the form widgets. It has
+            two keys/attributes:
 
-        or internally via the attribute ``data``.
+            * extjs (dict): Ext JS configuration options
+              for ``Ext.form.Panel`` widget.
 
-        The keys of the ``data`` structure are:
+            * field_sets (list): list of ``gluon.storage.Storage`` defining
+              the :class:`.FieldSet` configurations. It has two
+              keys/attributes:
 
-            * ``extjs`` (dict) Ext JS configuration options for the form widget.
+                    * fields (list): database fields embedded in the ``FieldSet``.
+                      They are identified by their database field name
+                      and should belong to the table specified in the
+                      constructor.
 
-            * ``field_sets`` (list of Storage) each ``Storage`` defined a
-              ``FieldSets``. It has two keys ``fields`` and ``extjs``.
-              The former is a list of field names belonging to the table
-              defined in the constructor. The latter is a dictionary with
-              the configuration options of the ``Ext.form.FieldSet`` widget.
+                    * extjs (dict): the configuration options of
+                      the ``FieldSet`` widget.
 
-            * ``hidden_fields`` (list)  list of field names to be hidden in
-              the form. The fields have to belong to the table defined in
-              the constructor.
+            * hidden_fields (list):  list of field hidden in the form.
+              They are identified by their database field name and
+              have to belong to the table specified in the constructor.
 
-            * ``mapper`` (None or function) reference to the function used
+            * mapper (function): reference to the function used
               to organize the ``FieldSet`` in ``Tabs``, for example.
 
-        Args:
-            tablename (str): name of the database table
+    """
+
+    def __init__(self, tablename):
 
-        """
         Modifier.__init__(self, MODIFIER_FORMS, tablename)
 
         if 'field_sets' not in self.data:
@@ -94,14 +87,29 @@ class FormModifier(Modifier):
             self.data.mapper = None
 
 
+    def hide_fields(self, *fields):
+        """Hide the list of fields in the form.
+        Each field is identified by its database field name.
+
+        Args:
+            *fields: variable list of database field identified
+                by their name.
+
+        """
+        for el in fields:
+            if el not in self.data.hidden_fields:
+                self.data.hidden_fields.append(el)
+
+
     def link_comboboxes(self, **kwargs):
-        """Link two fields in such a way that the values available for the
-        second one depend on the value selected for the first one.
+        """Link two fields rendered as ComboBox. The values available for the
+        second one depends on the value selected for the first one.
 
-            * This first field is the master while the second one is the slave.
+        Notes:
+            * This first field is the *master* while the second one is the *slave*.
             * Often the master and slave fields are reference fields.
-            * An external table contains the data defining the relation between the
-              master and the slave.
+            * An external table must contains the data defining the relation
+              between the master and the slave.
             * The external table must have the master and slave fields
             * Several slaves can be attached to the same master::
 
@@ -114,33 +122,26 @@ class FormModifier(Modifier):
                                                  masterHasSlaveData='anotherTable')
 
             * This method modify deeply the field configuration transforming
-              the Ext.form.comboBox into App.form.LinkedComboBox.
+              the ``Ext.form.comboBox`` into ``App.form.LinkedComboBox``.
 
         Keyword Args:
-            master (gluon.dal.Field):
-                the field used as master.
+            master (gluon.dal.Field): the database field used as master.
                 It has to be defined in the table referenced in the constructor
                 and in the ``masterHasSlaveData`` table.
 
-            slave (gluon.dal.Field):
-                the field used as salve.
+            slave (gluon.dal.Field): the database field used as salve.
                 It has to be defined in the table referenced in the constructor
                 and in the ``masterHasSlaveData`` table.
 
-            masterHasSlaveData (str):
-                name of the external database table.
-                Its contains the data defining the relation between master and slave.
-                It should contains fields with the name of the master and slave ones.
+            masterHasSlaveData (str): name of the table containing the relation
+                between master and slave. It should contains fields with the name
+                of the master and slave ones.
 
-            masterExtJS (dict):
-                configuration options dictionary for the
-                Ext.form.Combobox associated to the master reference field.
-                Might be useful to set the master in readOnly mode for example.
+            masterExtJS (dict): configuration options dictionary for the
+                ``Ext.form.field.Combobox`` associated to the master reference field.
 
-            slaveExtJS (dict):
-                configuration option dictionary for the
-                Ext.form.Combobox associated to the slave reference field.
-                Might be useful to set the salve in readOnly mode for example.
+            slaveExtJS (dict): configuration option dictionary for the
+                ``Ext.form.field.Combobox`` associated to the slave reference field.
 
         """
         # short cuts
@@ -205,14 +206,14 @@ class FormModifier(Modifier):
 
 
     def merge_fields(self, *fields, **kwargs):
-        """Merge fields in a :class:`.FieldSet`
-        corresponding to the ``Ext.form.FieldSet`` widget.
+        """Merge fields in the :class:`.FieldSet` widget.
 
-        Each ``field`` is either a string identifying the database field by its name
-        or an instance of the Ext JS configurator like the ``Spacer``.
+        Args:
+            *fields: variable list of database field identified by their name.
 
-        The keyword argument define values for the configuration options of
-        the ``Ext.form.FieldSet`` widget.
+        Keyword Args:
+            **kwargs: any configuration options of the ``Ext.form.FieldSet``
+                widget.
 
         """
         # by default the field occupies all the field set space
@@ -223,32 +224,25 @@ class FormModifier(Modifier):
         self.data.field_sets.append(di)
 
 
-    def hide_fields(self, *fields):
-        """Hide the list of fields in the form.
-        Each field is identified by its database field name.
-
-        """
-        for el in fields:
-            if el not in self.data.hidden_fields:
-                self.data.hidden_fields.append(el)
-
-
     def set_mapper(self, func):
-        """Link the mapper tool to the function func.
+        """Link the mapper tool to the function *func*.
 
-        A mapper tool is related to the organization of the field/fieldest
-        in the form. By default the form layout is a column where fields are
+        A mapper tool organise the field/fieldsets in the form.
+        By default the form layout is a column where fields are
         pushed from the top to the bottom. By using the layout configuration
-        option it is possible to organize the field/fieldset in horizontal
-        box, vertical box, columns or in table.
+        option, it is possible to layout the field/fieldset horizontally,
+        vertically, by columns or table.
 
         This approach does not allow to map field/fieldset in panels
-        contains in the form, like an Ext.TabPanel. The mapper tool allows to
-        handle this case. It is a function with one arguments, the list of
+        contains in the form, like an ``Ext.tab.Panel``. The mapper tool
+        handles this case. It is a function with one arguments, the list of
         field/fieldset. The function return a dictionary with the structure of
         panels embedded in the form an the fields they contained.
 
-        Example of mapper can be found in the :mod:`plugin_dbui.mapper` module.
+        Example of mapper can be found in the module :mod:`.mapper`.
+
+        Args:
+            func (function): reference to a function.
 
         """
         self.data.mapper = func