Review converter.py documentation.

docs/api/generated/plugin_dbui.converter.to_field.rst

+plugin_dbui.converter.to_field
+==============================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_field
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_fields.rst

+plugin_dbui.converter.to_fields
+===============================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_fields
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_formPanel.rst

+plugin_dbui.converter.to_formPanel
+==================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_formPanel
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_gridColumn.rst

+plugin_dbui.converter.to_gridColumn
+===================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_gridColumn
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_gridColumnModel.rst

+plugin_dbui.converter.to_gridColumnModel
+========================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_gridColumnModel
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_gridFilter.rst

+plugin_dbui.converter.to_gridFilter
+===================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_gridFilter
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_gridPanel.rst

+plugin_dbui.converter.to_gridPanel
+==================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_gridPanel
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_jsonstore.rst

+plugin_dbui.converter.to_jsonstore
+==================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_jsonstore
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_model.rst

+plugin_dbui.converter.to_model
+==============================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_model
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_panelWithUrlSelector.rst

+plugin_dbui.converter.to_panelWithUrlSelector
+=============================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_panelWithUrlSelector
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_treeNodes.rst

+plugin_dbui.converter.to_treeNodes
+==================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_treeNodes
\ No newline at end of file

docs/api/generated/plugin_dbui.converter.to_viewport.rst

+plugin_dbui.converter.to_viewport
+=================================
+
+.. currentmodule:: plugin_dbui.converter
+
+.. autofunction:: to_viewport
\ No newline at end of file

modules/plugin_dbui/converter.py

@@ -173,45 +173,40 @@ def _to_field(field, linkedcombo=True, **kwargs):
 
 
 def to_field(field, composite=True, linkedcombo=True, **kwargs):
-    """Build the :class:`.Field` configuration for
-    the database field. The conversion handles
-    :class:`.FieldContainer` and takes into account
-    the :class:`.FieldsModifier` instructions.
+    """Build the widget configuration for the database *field*.
 
-    Note:
-        The return configurator is a :class:`.Field`.
-        However it can be a :class:`.ComboBox`,
-        a :class:`.FieldDate`,
-        :class:`.FieldTextArea`, ...
-        depending on the ``type`` of the database field.
-        The association is defined in the dictionary
-        :const:`FTYPE_TO_XTYPE`.
+    The return configuration depends on the *type* of the database field.
+    It can be  a :class:`.Field`, a :class:`.ComboBox`, a :class:`.FieldDate`,
+    a :class:`.FieldTextArea`, ...
+
+    The conversion takes into account the :class:`.FieldsModifier`
+    instructions and handles :class:`.FieldContainer` widget.
 
     Note:
-        The database fields can be organized in
-        :class:`.FieldContainer` in the application
-        model using the modifiers
-        :class:`.FieldsModifier`.
+        Several database fields can be merged in a single
+        :class:`.FieldContainer` widget using
+        the method :meth:`.FieldsModifier.merge_fields`.
 
     Args:
-        field (gluon.dal.Field);
+        field (gluon.dal.Field):
+            database field.
 
-        composite (bool): ``FieldContainer`` is ignored when ``False``.
-            Useful to build grid filter.
+        composite (bool):
+            ``FieldContainer`` is ignored when ``False``.
 
-        linkedcombo (bool): ``LinkedComboBox`` are ignored when ``False``.
-            Useful to build grid filter.
+        linkedcombo (bool):
+            ``LinkedComboBox`` are ignored when ``False``.
 
     Keyword Args:
-        kwargs (dict):
-            any Ext JS configuration parameter of the ``Ext.form.Field``
-            class. They are applied in the following order:
-            constructor, modifiers and keyword arguments.
+        **kwargs (dict): any Ext JS configuration parameter of the
+            ``Ext.form.Field`` widget or derived classes. They are applied
+            in the following order: constructor, modifiers and
+            keyword arguments.
 
     Returns:
         * Field
         * ``None`` when the argument composite is ``True`` and when
-            the field is consumed by a ``FieldContainer``.
+          the field is consumed by a ``FieldContainer``.
 
     """
     table = field.table
@@ -252,27 +247,30 @@ def to_field(field, composite=True, linkedcombo=True, **kwargs):
 
 
 def to_fields(table):
-    """Build the list :class:`.Field` configuration
-    for each field of the database ``table``.
+    """Build the list of widget configurations
+    for each field of the database *table*.
+
+    The widget associated to each database field depends on its *type*.
+    It can be a :class:`.Field`, a :class:`.ComboBox`, a :class:`.FieldDate`,
+    a :class:`.FieldTextArea`, ...,
 
-    The function handles :class:`.FieldSet` and
-    :class:`.FieldContainer` as well as the
-    :class:`.FieldsModifier` instructions.
-    The ``FieldSet`` and ``FieldContainer`` can be defined in the
-    application model using the modifier
-    :class:`.FormModifier` and the
-    :class:`.FieldsModifier` respectively.
+    The configuration of the widget takes into
+    account :class:`.FieldsModifier` instructions.
+    It also handles :class:`.FieldSet` as well as :class:`.FieldContainer`
+    widgets.
+
+    Note:
+        Several database fields can be merged in a
+        single :class:`.FieldContainer` widget using
+        the method :meth:`.FieldsModifier.merge_fields`.
+        Similarly, they can be grouped in a :class:`.FieldSet` widget via
+        the method :meth:`.FormModifier.merge_fields`.
 
     Args:
         table (gluon.dal.Table): database table
 
     Returns:
-        list:
-            The list elements are :class:`.Field`, but
-            it can be a :class:`.ComboBox`,
-            a :class:`.FieldDate`,
-            a :class:`.FieldTextArea`, ...,
-            depending on the ``type`` of the database field.
+        list of Field elements.
 
     """
     li = []
@@ -338,22 +336,22 @@ def to_fields(table):
 
 
 def to_formPanel(table, **kwargs):
-    """Build the :class:`.FormPanel` configuration
-    for the database ``table``. The conversion takes into account the
-    :class:`.FormModifier` instructions.
+    """Build the configuration of the :class:`.FormPanel` widget
+    for the database ``table``.
+
+    The conversion takes into account the :class:`.FormModifier`
+    instructions.
 
     Args:
         table (gluon.dal.Table): database table
 
     Keyword Args:
-        kwargs (dict):
-            any Ext JS configuration parameter of the
-            ``Ext.form.Panel`` class. They are
-            applied in the following order: constructor, modifiers
-            and keyword arguments.
+        **kwargs (dict): any Ext JS configuration parameter of the
+            ``Ext.form.Panel`` class. They are applied in the following
+            order: constructor, modifiers and keyword arguments.
 
     Returns:
-        FormPanel:
+        FormPanel
 
     """
     tablename = table._tablename
@@ -377,22 +375,22 @@ def to_formPanel(table, **kwargs):
 
 
 def to_gridColumn(field, **kwargs):
-    """Build the :class:`.GridColumn` configuration
-    for the database ``field``. The conversion takes into account the
-    :class:`.GridModifier` instructions.
+    """Build the configuration of the :class:`.GridColumn`
+    for the database ``field``.
+
+    The conversion takes into account the :class:`.GridModifier`
+    instructions.
 
     Args:
         field (gluon.dal.Field): database field
 
     Keyword Args:
-        kwargs (dict):
-            any Ext JS configuration parameter of the
-            ``Ext.grid.Column`` class.
-            They are applied in the following order: constructor, modifiers
-            and keyword arguments.
+        **kwargs (dict): any Ext JS configuration parameter of the
+            ``Ext.grid.Column`` class. They are applied in the following
+            order: constructor, modifiers and keyword arguments.
 
     Returns:
-        GridColumn:
+        GridColumn
 
     """
     T = current.T
@@ -444,15 +442,17 @@ def to_gridColumn(field, **kwargs):
 
 
 def to_gridColumnModel(table):
-    """Build the :class:`.GridColumnModel` configuration
-    for the database ``table``. The conversion takes into account the
-    :class:`.GridModifier` instructions.
+    """Build the configuration of the :class:`.GridColumnModel`
+    for the database ``table``.
+
+    The conversion takes into account the :class:`.GridModifier`
+    instructions.
 
     Args:
         table (gluon.dal.Table): database table
 
     Returns:
-        GridColumnModel:
+        GridColumnModel
 
     """
     delete_columns = []
@@ -488,36 +488,24 @@ def to_gridColumnModel(table):
 
 
 def to_gridFilter(table, **kwargs):
-    """Build the :class:`.GridFilter` configuration for
-    the database ``table``. The ``GridFilter`` is parametrized using the
-    :class:`.GridModifier`.
+    """Build the configuration of the :class:`.GridFilter` widget for
+    the database ``table``.
+
+    The ``GridFilter`` is defined by the
+    method :meth:`.GridModifier.append_filter`
+    and :meth:`.GridModifier.configure_filters`
 
     Args:
         table (gluon.dal.Table): database table
 
     Keyword Args:
-        kwargs (dict):
-            any of the Ext JS configuration parameters of the
+        **kwargs (dict): any of the Ext JS configuration parameters of the
             ``App.grid.Filter`` class. They are applied in the following order:
             constructor, modifiers, keyword arguments.
 
-    A filter rule is defined in the model via the
-    :class:`.GridModifier`.
-    The rule is a ``tuple`` containing 3 strings
-    ``("field1", "operator", "comment")``
-    where ``field1`` is the name of a field belonging to the ``table``.
-    A more elaborate filter rule allows to filter on any foreign field using
-    the syntax is ``("table2.field1", "operator", "comments")``.
-    Valid operators are defined in the method
-    :meth:`.DbSvc._encode_query`.
-
-    Rules are store in the modifier section ``grid_filters``.
-
     Returns:
-        GridFilter:
-            Return an empty dictionary if the GridFilter is
-            not defined in the application model.
-
+        * GridFilter
+        * Empty dictionary when filters are not defined
 
     """
     T = current.T
@@ -609,21 +597,22 @@ def to_gridFilter(table, **kwargs):
 
 
 def to_gridPanel(table, **kwargs):
-    """Build the :class:`.GridPanel` configuration for
-    the database ``table``. The conversion takes into account the
-    :class:`.GridModifier` instructions.
+    """Build the configuration of the :class:`.GridPanel` widget for
+    the database *table*.
+
+    The conversion takes into account the :class:`.GridModifier`
+    instructions.
 
     Args:
         table (gluon.dal.Table): database table
 
     Keyword Args:
-        kwargs (dict):
-            any of the Ext JS configuration parameters of the
+        **kwargs (dict): any of the Ext JS configuration parameters of the
             ``App.grid.Panel`` class. They are applied in the following order:
             constructor, modifiers, keyword arguments.
 
     Returns:
-        GridPanel:
+        GridPanel
 
     """
     tablename = table._tablename
@@ -657,21 +646,22 @@ def to_gridPanel(table, **kwargs):
 
 
 def to_jsonstore(table, **kwargs):
-    """Build the :class:`.DirectStore` configuration for
-    the database ``table``. The conversion takes into account the
-    :class:`.StoreModifier` instructions.
+    """Build the configuration of the :class:`.DirectStore` associated
+    to the database *table*.
+
+    The conversion takes into account the :class:`.StoreModifier`
+    instructions.
 
     Args:
         table (gluon.dal.Table): database table
 
     Keyword Args:
-        kwargs (dict):
-            any of the Ext JS configuration parameters of the
-            ``App.data.DirectStore`` class. They are applied in the following order:
-            constructor, modifiers, keyword arguments.
+        **kwargs (dict): any of the Ext JS configuration parameters of the
+            ``App.data.DirectStore`` class. They are applied in the
+            following order: constructor, modifiers, keyword arguments.
 
     Returns:
-        DirectStore:
+        DirectStore
 
     """
     db = table._db
@@ -749,14 +739,14 @@ def to_jsonstore(table, **kwargs):
 
 
 def to_model(table):
-    """Build the :class:`.Model` configuration for
+    """Build the configuration of the :class:`.Model` associated to
     the database ``table``.
 
     Args:
         table (gluon.dal.Table): database table
 
     Returns:
-        dict:
+        dict
 
     """
     db = table._db
@@ -798,31 +788,30 @@ def to_model(table):
 
 
 def to_panelWithUrlSelector(table, selectorTitle='Select', **kwargs):
-    """Build the :class:`.PanelWithUrlSelector` configuration
-    where the selector is a form derived from the database ``table``.
+    """Build the configuration of the :class:`.PanelWithUrlSelector` widget.
 
     Args:
-        table (gluon.dal.Table): database table
+        table (gluon.dal.Table): database table. It is used to build the form
+            to select values. The form has one entry per table field.
 
         selectorTitle (str):
             the title of the FieldSet encapsulating
             the selector fields.
 
         baseUrl (str): the selected values are send to a controller
-            defined by the baseUrl.Values are processed and results
+            defined by the baseUrl. Values are processed and results
             will be published in the panel.
             It is mandatory to specified the baseUrl.
 
     Keyword Args:
-        kwargs (dict):
-            any of the Ext JS configuration parameters of the
+        **kwargs (dict): any of the Ext JS configuration parameters of the
             ``App.panel.WithUrlSelector`` class.
 
     Returns:
-        PanelWithUrlSelector:
+        PanelWithUrlSelector
 
     Raises:
-         BaseException: when the argument``baseUrl`` is not defined.
+         BaseException: when the argument ``baseUrl`` is not defined.
 
     """
     if 'baseUrl' not in kwargs:
@@ -845,11 +834,12 @@ def to_panelWithUrlSelector(table, selectorTitle='Select', **kwargs):
 
 def to_treeNodes():
     """Build the list of :class:`.Node`.
-    The Node structure is defined in the application model using
-    :class:`.ViewportModifier`.
+
+    The nodes are displayed by the viewport widget.
+    The list is built via the method :meth:`.ViewportModifier.add_node`.
 
     Returns:
-        list:
+        list
 
     """
     cfg = []
@@ -865,17 +855,17 @@ def to_treeNodes():
 
 
 def to_viewport(**kwargs):
-    """Build the :class:`.Viewport` configuration.
-    The conversion takes into account the
-    :class:`.ViewportModifier` instructions.
+    """Build the configuration of the :class:`.Viewport` widget.
+
+    The conversion takes into account the :class:`.ViewportModifier`
+    instructions.
 
     Keyword Args:
-        kwargs (dict):
-            any of the Ext JS configuration parameters of the
+        **kwargs (dict): any of the Ext JS configuration parameters of the
             ``App.viewport.Viewport`` class.
 
     Returns:
-        dict:
+        dict
 
     """
     cfg = {}