Plugin Dbui API Guide Release 1.0.1

plugin_dbui API Guide Release 1.0.1

R. Le Gac

Dec 09, 2019

CONTENTS

1 Constants 1

2 Database model 3 2.1 Initialisation...... 3 2.2 Callbacks...... 6 2.3 Filters...... 6

3 User interface 9 3.1 Field...... 9 3.2 Form...... 10 3.3 Grid...... 13 3.4 Node...... 16 3.5 Store...... 18 3.6 Viewport...... 19 3.7 Convert database ﬁelds to widgets...... 20 3.8 Ext JS widget mappings...... 24

4 Controller 43 4.1 Selector...... 43 4.2 Helper functions...... 45

5 Services, exception and base classes 53 5.1 Services...... 53 5.2 Exceptions...... 58 5.3 Base classes...... 58

6 Indices and tables 63

i ii CHAPTER ONE

CONSTANTS

CALLBACK_ERRORS str _callback_errors DBUI str Dbui INLINE_ALERT str UNDEF str undefined UNDEF_ID int 1 UNKNOWN str ???

1 plugin_dbui API Guide, Release 1.0.1

2 Chapter 1. Constants CHAPTER TWO

DATABASE MODEL

2.1 Initialisation

Dbui Set of tools to initialise the plugin Dbui.

2.1.1 plugin_dbui.Dbui class plugin_dbui.Dbui Bases: object Set of tools to initialise the plugin Dbui.

Methods

define_paths(**kwargs) deﬁne paths for the plugin dbui. initialise_ui() Initialise persistent storage for the plugin dbui. start_directSvc() Start services to interact with the database from the User Interface using the Ext JS Direct protocol.

plugin_dbui.Dbui.deﬁne_paths

static Dbui.define_paths(**kwargs) deﬁne paths for the plugin dbui. Paths are relative to the main directory of the application. They can target a ﬁle (static/myapp.css) or a directory (static/css).

Note: The conﬁguration of the plugin is persistent across the application. It can be accessed at any time using the syntax:

from gluon.tools import PluginManager PluginManager("dbui").dbui

Parameters • app_about (str) – relative path to the ABOUT ﬁle, e.g. static/ABOUT.html.

3 plugin_dbui API Guide, Release 1.0.1

• app_css (str or list) – relative path to CSS files for the application, e.g. static/myapp/ressources/css. Default is None • app_changelog (str) – relative path to the CHANGELOG, e.g. static/ CHANGELOG. • app_db_schema (str) – relative path to the database schema, e.g. static/docs/ database.png. • app_debug (str or list) – relative path to the debug version for the application library, e.g. static/myapp/src or static/myapp/myapp-debug.js. Default is None • app_git (str) – the URL of the git repository for the application, e.g. https:// gitlab.in2p3.fr/w2pext/plugin_dbui.git Default is None. • app_lg (str or list) – relative path to languages files for the application, e.g. static/myapp/locale/myapp-lang-fr.js. Default is None. • app_html_api (str) – relative path to the documentation for the python api, e.g. static/docs/api/index.html. The format is HTML. • app_html_jsduck (str) – relative path to the documentation for the javascript api, e.g. static/docs/jsduck/index.html. The format is HTML. • app_html_reference (str) – relative path to the documentation for developers, e.g. static/docs/reference/index.html. The format is HTML. • app_html_user (str) – relative path to the documentation for users, e.g. static/ docs/user/index.html. The format is HTML. • app_libmin (str or list) – relative path to the minified version for the application library, e.g. static/myapp-min.js. • app_license (str) – relative path to the license for the application. • app_pdf_api (str) – relative path to the documentation for the python api, e.g. static/docs/pdf/myapp_api.pdf. The format is PDF. • app_pdf_reference (str) – relative path to the documentation for developers, e.g. static/docs/pdf/myapp_reference.pdf. The format is PDF. • app_pdf_user (str) – relative path to the documentation for user, e.g. static/ docs/pdf/myapp_user.pdf. The format is PDF. • app_script (str) – relative path to the main script to run the application, e.g. static/myapp.js. • app_script_dir (str) – relative path to a directory containing a collection of JavaScript, e.g static/scripts. The script named foo can be run via the URL: https://myverver/myapp?script=foo. The default is None. • dbui_conf (str) – the ULR returning the configuration for the User Interface. The default is /myapp/plugin_dbui/dbui_conf, • dbui_conf_debug (str) – the URL returning the debug version of the configuration for the User Interface. The default is /myapp/plugin_dbui/dbui_conf?debug. • dbui_html_api (str) – relative path to the documentation for the python api. e.g. static/plugin_dbui/docs/api/index.html. The format is HTML. • dbui_html_jsduck (str) – relative path to the documentation for the javascript api, e.g. static/plugin_dbui/docs/jsduck/index.html. The format is HTML.

4 Chapter 2. Database model plugin_dbui API Guide, Release 1.0.1

• dbui_html_reference (str) – relative path to the documentation for developers, e.g. static/plugin_dbui/docs/reference/index.html. The format is HTML. • dbui_license (str) – relative path to the license for the plugin dbui, e.g static/ plugin_dbui/LICENCE_UK.html. • dbui_pdf_api (str) – relative path to the documentation for the python api, e.g. static/plugin_dbui/docs/pdf/dbui_api.pdf. The format is PDF. • dbui_pdf_reference (str) – relative path to the documentation for developers, e.g. static/plugin_dbui/docs/pdf/dbui_reference.pdf. The format is PDF. • dbui_script (str) – default script to run the application: static/ plugin_dbui/main.js. It is used when the option app_script is not deﬁned. • plugins_paths (dict) – contains paths deﬁning javascript libraries for plugins. The key is the name of the plugin while the value is a dictionary with 4 keys (str or list or None):

css relative path to CSS files: static/plugin_key/resources/css de- relative path to the debug version: static/plugin_key/dbui-debug. bug js lg relative path to languages files: static/plugin_key/locale/ key-lang-fr.js lib- relative path to minified version: static/plugin_key/locale/ min key-lang-fr.js

By default, plugins ace, dbui, extjs and mathjax are conﬁgure.

Note: It is possible to register others plugins by adding them to the plugins_paths dictionary. There libraries will be laod properly by the controller plugin_dbui/index.

plugin_dbui.Dbui.initialise_ui

static Dbui.initialise_ui() Initialise persistent storage for the plugin dbui.

Note: The conﬁguration of the plugin is persistent across the application. It can be accessed at any time using the syntax:

from gluon.tools import PluginManager PluginManager("dbui").dbui

modifier_fields Type dict plugin_dbui.modifier_forms Type dict plugin_dbui.modifier_grids Type dict plugin_dbui.modifier_stores

2.1. Initialisation 5 plugin_dbui API Guide, Release 1.0.1

Type dict plugin_dbui.modifier_viewports Type gluon.storage.Storage plugin_dbui.static_stores Type dict

plugin_dbui.Dbui.start_directSvc

static Dbui.start_directSvc() Start services to interact with the database from the User Interface using the Ext JS Direct protocol. Returns Return type directSvc

2.2 Callbacks

INHIBIT_DELETE_UNDEF(setrows) Inhibit the delete of the record containing the undeﬁned value. INHIBIT_UPDATE_UNDEF(setrows, values) Inhibit the update the row containing the undeﬁned value.

2.2.1 plugin_dbui.callback.INHIBIT_DELETE_UNDEF plugin_dbui.callback.INHIBIT_DELETE_UNDEF(setrows) Inhibit the delete of the record containing the undeﬁned value. Parameters setrows (gluon.dal.Set) – set of records used for deleted Returns true when the record contains the undeﬁned value.

2.2.2 plugin_dbui.callback.INHIBIT_UPDATE_UNDEF plugin_dbui.callback.INHIBIT_UPDATE_UNDEF(setrows, values) Inhibit the update the row containing the undefined value. Parameters • setrows (gluon.dal.Set) – set of records for update • values (dict) – dictionary of database field used in the update. Returns true when the record contains the undefined value.

2.3 Filters

CLEAN_COMMA(value) Remove trailing comma(s). CLEAN_SPACES(value) Remove leading as well as trailing spaces and keep a single space between words.

6 Chapter 2. Database model plugin_dbui API Guide, Release 1.0.1

2.3.1 plugin_dbui.ﬁlters.CLEAN_COMMA plugin_dbui.filters.CLEAN_COMMA(value) Remove trailing comma(s). Search patterns are: “,” or “, ” or ” „ ” . . . Parameters value (object)– Returns the return the value is unchanged when it is not a string. Return type object

2.3.2 plugin_dbui.ﬁlters.CLEAN_SPACES plugin_dbui.filters.CLEAN_SPACES(value) Remove leading as well as trailing spaces and keep a single space between words. Parameters value (object)– Returns the return the value is unchanged when it is not a string. Return type object

2.3. Filters 7 plugin_dbui API Guide, Release 1.0.1

8 Chapter 2. Database model CHAPTER THREE

USER INTERFACE

3.1 Field

FieldsModifier(tablename) Customise the widgets associated to the ﬁelds of the database table tablename.

3.1.1 plugin_dbui.fieldsmodifier.FieldsModifier class plugin_dbui.fieldsmodifier.FieldsModifier(tablename) Bases: plugin_dbui.modifier.Modifier Customise the widgets associated to the fields of the database table tablename. Parameters tablename (str) – name of the database table data storage containing the instructions to tune the field widgets. It has two keys/attributes: • extjs_fields (dict): Ext JS configuration options for each field. Keys are the database field names. • composite_fields (gluon.storage.Storage): describe the fields embedded in the 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.

Type gluon.storage.Storage

Methods

configure_field(field, **kwargs) Define the configuration options of the widget associated to the field. merge_fields(*fields, **kwargs) Merge fields in the container FieldContainer.

plugin_dbui.fieldsmodifier.FieldsModifier.configure_field

FieldsModifier.configure_field(field, **kwargs) Define the configuration options of the widget associated to the field.

9 plugin_dbui API Guide, Release 1.0.1

Existing value of the configuration options are replace by those defined by the arguments. Parameters field (str) – name of the database field. It should belong to the database table defined in the constructor. Keyword Arguments **kwargs – any Ext JS configuration parameter of the widget class.

plugin_dbui.fieldsmodifier.FieldsModifier.merge_fields

FieldsModifier.merge_fields(*fields, **kwargs) Merge fields in the container FieldContainer. In form, the container is handled as a single widget with a unique label. By default, it is the one of the first field of the container. It can be supersede using the fieldLabel keyword argument. The default configuration of the container is an horizontal layout:

combineLabels= True, defaults={"flex":1}, layout= "hbox"

It can be changed via the keyword arguments. Parameters *fields – variable list of database field identified by their name. They have to belong to the database table defined in the constructor. Keyword Arguments **kwargs – any configuration parameter of the the FieldContainer.

3.2 Form

configure_forms(db, **extjs) Apply a set of conﬁguration parameters to all form widgets. FormModifier(tablename) Customise the form widget associated to the database table tablename.

3.2.1 plugin_dbui.formmodifier.configure_forms plugin_dbui.formmodifier.configure_forms(db, **extjs) Apply a set of configuration parameters to all form widgets. Parameters db (gluon.dal.DAL or list) – list of forms to be modified. They are identified by their associated database table name. Keyword Arguments **extjs – any configuration parameter of the FormPanel widget.

3.2.2 plugin_dbui.formmodiﬁer.FormModiﬁer class plugin_dbui.formmodifier.FormModifier(tablename) Bases: plugin_dbui.modifier.Modifier Customise the form widget associated to the database table tablename. Parameters tablename (str) – name of the database table

10 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

data storage containing the instructions to tune the form widgets. It has four keys/attributes: • extjs (dict): Ext JS configuration options for FormPanel widget. • field_sets (list): list of gluon.storage.Storage defining the FieldSet configurations. It has two keys/attributes: – 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. – extjs (dict): the configuration options of the FieldSet widget. • 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 (function): reference to the function used to organize the FieldSet in Tabs, for example.

Type gluon.storage.Storage

Methods

hide_fields(*fields) Hide the list of fields in the form. link_comboboxes(**kwargs) Link two fields rendered as ComboBox. merge_fields(*fields, **kwargs) Merge fields in the FieldSet widget. set_mapper(func) Link the mapper tool to the function func.

plugin_dbui.formmodifier.FormModifier.hide_fields

FormModifier.hide_fields(*fields) Hide the list of fields in the form. Each field is identified by its database field name. Parameters *fields – variable list of database field identified by their name.

plugin_dbui.formmodiﬁer.FormModiﬁer.link_comboboxes

FormModifier.link_comboboxes(**kwargs) Link two ﬁelds rendered as ComboBox. The values available for the second one depends on the value selected for the ﬁrst one.

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 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:

fieldsModifier= fieldsModifier("mytable") fieldsModifier.link_comboxes(master=virtdb.mytable.myfield1, slave=virtdb.mytable.myfield2, masterHasSlaveData="anotherTable") (continues on next page)

3.2. Form 11 plugin_dbui API Guide, Release 1.0.1

(continued from previous page) fieldsModifier.link_comboxes(master=virtdb.mytable.myfield1, slave=virtdb.mytable.myfield3, masterHasSlaveData="anotherTable")

• This method modify deeply the ﬁeld conﬁguration transforming the ComboBox into Dbui.form. LinkedComboBox.

Keyword Arguments • 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 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 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 ComboBox associated to the master reference field. • slaveExtJS (dict) – configuration option dictionary for the ComboBox associated to the slave reference field.

plugin_dbui.formmodifier.FormModifier.merge_fields

FormModifier.merge_fields(*fields, **kwargs) Merge fields in the FieldSet widget. Parameters *fields – variable list of database field identified by their name. Keyword Arguments **kwargs – any configuration options of the FieldSet widget.

plugin_dbui.formmodiﬁer.FormModiﬁer.set_mapper

FormModifier.set_mapper(func) Link the mapper tool to the function func. 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 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 TabPanel. 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 module mapper. Parameters func (function) – reference to a function.

map_default(fields) Map a list of field in the FormPanel. map_tabpanel(fieldsets) Map a list of FieldSet in the TabPanel.

12 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

3.2.3 plugin_dbui.mapper.map_default plugin_dbui.mapper.map_default(fields) Map a list of field in the FormPanel. Parameters fields (list) – database field names Returns the input list Return type list

3.2.4 plugin_dbui.mapper.map_tabpanel plugin_dbui.mapper.map_tabpanel(fieldsets) Map a list of FieldSet in the TabPanel. • A tab is associated to each fieldset. • the name of the tab is the name of the fieldset.

Parameters fieldsets (list) – a series of FieldSet Returns the TapPanel encapsulated in a list. Return type list

3.3 Grid

configure_grids(db, **extjs) Apply a set of conﬁguration parameters to all grid widgets. GridModifier(tablename) Customise the grid widget associated to the database table tablename.

3.3.1 plugin_dbui.gridmodifier.configure_grids plugin_dbui.gridmodifier.configure_grids(db, **extjs) Apply a set of configuration parameters to all grid widgets. Parameters db (gluon.dal.DAL or list) – list of grids to be modified. They are identified by their associated database table name. Keyword Arguments **extjs – any configuration parameter of the GridPanel widget.

3.3.2 plugin_dbui.gridmodifier.GridModifier class plugin_dbui.gridmodifier.GridModifier(tablename) Bases: plugin_dbui.modifier.Modifier Customise the grid widget associated to the database table tablename. Parameters tablename (str) – name of the database table data storage containing the instructions to tune the grid widgets. It has seven keys/attributes: • extjs (dict): Ext JS configuration options for GridPanel widget.

3.3. Grid 13 plugin_dbui API Guide, Release 1.0.1

• configure_columns (dict): the Ext JS configuration options for each GridColumn object. The grid has one column per per database field of the table. Therefore, the key is the database field name • delete_columns (list): list of database fields which are not displayed in the grid. They are identified by their database field name • grid_filters (gluon.storage.Storage): list of filter rules (see append_filter()) • grid_with_filter (dict): configuration options of the GridWithFilter widget. • hidden_columns (list): list of database fields which are hidden in the grid widget. • row_numbering (bool): the first column show the number of the row when true. • template_columns (list): the configurations of the Ext.column.Template.

Type gluon.storage.Storage

append_filter(fltr, **kwargs) Append a filter condition. configure_column(fieldname, **kwargs) Modify the configuration options for a given column. configure_filters(**kwargs) Configure the FieldSet embedded in the GridFilter. configure_gridWithFilter(**kwargs) Configure the GridWithFilter widget. delete_columns(*fields) Delete the columns in the GridPanel widget. hide_columns(*fields) Hide the columns in the GridPanel widget. merge_columns(*fields, **kwargs) Merge several database fields in a single TemplateColumn. set_rownumbering([value]) Activate or deactivate the row numbering.

plugin_dbui.gridmodifier.GridModifier.append_filter

GridModifier.append_filter(fltr, **kwargs) Append a filter condition. A filter is a condition applied on one database field. It is defined by a tuple containing three string: • database field identified either by its name when the field belong to the database table reference in the constructor, or by the more elaborate syntax table2.field1 for foreign field. • operator ==, !=, <, >, <=, >= as well as like, contains and startswith for string. • comment to help the user. It is displayed via a ToolTip. The series of filter are group in a FieldSet. The latter is rendered by the GridFilter widget located on the right side of the GridPanel. Parameters fltr (tuple)– ("field1", "operator", "comment") or ("table2.field3", "operator", "comment") Keyword Arguments **kwargs – any configuration options of the Field.

plugin_dbui.gridmodifier.GridModifier.configure_column

GridModifier.configure_column(fieldname, **kwargs) Modify the configuration options for a given column. The grid has one column per database field of the table. Parameters fieldname (str) – name of a database field. It has to belong to the table referenced in the constructor.

14 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Keyword Arguments **kwargs – any conﬁguration option of the GridColumn object.

plugin_dbui.gridmodifier.GridModifier.configure_filters

GridModifier.configure_filters(**kwargs) Configure the FieldSet embedded in the GridFilter. The latter is created automatically as soon as a filter is defined. Filter are defined and tuned individually using the method append_filter(). Keyword Arguments **kwargs – any configuration options of the FieldSet widget.

plugin_dbui.gridmodifier.GridModifier.configure_gridWithFilter

GridModifier.configure_gridWithFilter(**kwargs) Conﬁgure the GridWithFilter widget. Keyword Arguments **kwargs – any conﬁguration option of the GridwithFilter widget

plugin_dbui.gridmodiﬁer.GridModiﬁer.delete_columns

GridModifier.delete_columns(*fields) Delete the columns in the GridPanel widget. The grid has one column per database field of the table. This method defined the database fields not displayed in the grid. Parameters *fields – variable list of database field identified by their name.

plugin_dbui.gridmodiﬁer.GridModiﬁer.hide_columns

GridModifier.hide_columns(*fields) Hide the columns in the GridPanel widget. The grid has one column per database field of the table. This method defined the database fields hidden in the grid. Parameters *fields – variable list of database field identified by their name.

plugin_dbui.gridmodiﬁer.GridModiﬁer.merge_columns

GridModifier.merge_columns(*fields, **kwargs) Merge several database fields in a single TemplateColumn. The TemplateColumn is rendered by the Ext.grid.TemplateColumn. Parameters *fields – variable list of database field identified by their name. Keyword Arguments • header (str) – the header of the TemplateColumn. • tpl (list) – the template defining how field values are displayed in the TemplateColumn. The syntax of the template is is defined in the documentation of Ext.XTemplate constructor. There is some limitation when defining the template in python, namely the use of the template member function.

3.3. Grid 15 plugin_dbui API Guide, Release 1.0.1

Database fields are identified using the CapWord syntax TablenameFieldname. It works for standard and reference fields. HTML tags are understood. Example of a template list:

tpl=[ "{PeopleLast_name}
", "{PeopleFirst_name}
", "{PeoplePhone_number}" ]

• autohide (bool) – hide the columns associated to the fields consumed in the Template- Column when set to True. • position (int) – is the number defining where the column will be inserted in the grid widget. The first column is at 0. • extjs (dict) – contains the Ext JS configuration options of the Ext.grid. TemplateColumn.

plugin_dbui.gridmodiﬁer.GridModiﬁer.set_rownumbering

GridModifier.set_rownumbering(value=True) Activate or deactivate the row numbering. Row number is displayed in the ﬁrst column of the grid when activated. By default it is activate for all grids. Parameters value (boolean) – activate the row numbering when True.

3.4 Node

Node(text) The node is the key element of the navigation tree.

3.4.1 plugin_dbui.navtree.Node

class plugin_dbui.navtree.Node(text) The node is the key element of the navigation tree. It contains children (leaves) which are associated to widgets. The widget will be display on the panel of the Viewport. Parameters text (str) – name of the node appearing in the viewport navigation tree. text name of the node Type str children list of children Type list hidden list of children to be hidden

16 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Type list

Methods

add_child(text, cfg) Add a child (leaf) to the node. add_children(leaves[, func, hidden]) Add children (leaves) to the node. get_node() Get the dictionary deﬁning the node. sort_children() sort children according to alphabetical order.

plugin_dbui.navtree.Node.add_child

Node.add_child(text, cfg) Add a child (leaf) to the node. Parameters • text (str) – the name of the leaf • cfg (dict) – the Ext JS conﬁguration options deﬁning the widget associated to the leaf

plugin_dbui.navtree.Node.add_children

Node.add_children(leaves, func=None, hidden=[]) Add children (leaves) to the node. Parameters • leaves (list) – names of the leaves • func (function) – function mapping the leaf name to the Ext JS conﬁguration options dictionary. The latter deﬁnes the associated widget. • hidden (list) – list of children to be ignored.

Note: • Leaf names are translated in the current language • Leaf names are sorted in alphabetic order

plugin_dbui.navtree.Node.get_node

Node.get_node() Get the dictionary deﬁning the node. Returns • text (str): name of the node • children (list): list of leaves. Each element is a dictionary with three keys: – cfg (dict): conﬁguration for the widgets associated to the leaf. – leave (bool): always True. – text (str): name of the leaf

3.4. Node 17 plugin_dbui API Guide, Release 1.0.1

Return type dict

plugin_dbui.navtree.Node.sort_children

Node.sort_children() sort children according to alphabetical order.

3.5 Store

AddStore(name, **kwargs) A Ext JS store is associated to each database table. StoreModifier(tablename) Customise the Ext JS store associated to the database table tablename.

3.5.1 plugin_dbui.storemodifier.AddStore class plugin_dbui.storemodifier.AddStore(name, **kwargs) A Ext JS store is associated to each database table. Their configuration are derived from the table models using the to_jsonstore(). The Ext JS configuration options for all stores are kept in a persistent dictionary of the plugin_dbui. The configuration options are transported to the client using the plugin_dbui/dbui_conf action. From time to time, it is useful to defined static store, like ArrayStore. This tool allows to defined them and to add their configuration to the persistent dictionary. Thus they can be retrieve by the client in the standard way. This approach is generic and any store can be added to the persistent dictionary. Parameters name (str) – name of the store Keyword Arguments **kwargs – any configuration options for the target store. For example the ArrayStore requires the keyword fields and data. For more details see the Ext JS documentation.

Note: The key associated to this store in the persistent dictionary is the storeId. Its value is derived from the store name, e.g. nameStore.

Methods

3.5.2 plugin_dbui.storemodifier.StoreModifier class plugin_dbui.storemodifier.StoreModifier(tablename) Bases: plugin_dbui.modifier.Modifier Customise the Ext JS store associated to the database table tablename. Parameters tablename (str) – name of the database table data storage containing the instructions to tune the store widgets. It has two keys/attributes: • extjs (dict): Ext JS configuration options for Store object. • order_by (list): database fields to order the content of the store

18 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Type gluon.storage.Storage

Methods

orderby(*ﬁelds) Extend the list of database ﬁeld to order the store content. set_buffered(**kwargs) The grid buffering is activated.

plugin_dbui.storemodiﬁer.StoreModiﬁer.orderby

StoreModifier.orderby(*fields) Extend the list of database field to order the store content. Parameters *fields – variable list of database field

plugin_dbui.storemodiﬁer.StoreModiﬁer.set_buffered

StoreModifier.set_buffered(**kwargs) The grid buffering is activated. The method set the following conﬁguration options:

autoLoad= False buffered= True clearOnPageLoad= True pageSize= 25 leadingBufferZone=0 trailingBufferZone=0

They can be overwritten using the keyword arguments. Keyword Arguments kwargs (dict) – the conﬁguration parameter of the Store related to the buffering, namely: buffered, clearOnPaqgeLoad, leadingBufferZone, pageSize, purgePageCount and trailingBufferZone.

3.6 Viewport

ViewportModifier() Customise the viewport, the main application widget.

3.6.1 plugin_dbui.viewportmodifier.ViewportModifier class plugin_dbui.viewportmodifier.ViewportModifier Bases: plugin_dbui.modifier.Modifier Customise the viewport, the main application widget. data storage containing the instructions to tune the viewport widget. It has three keys/attributes: • extjs (dict): Ext JS configuration options for Viewport widget. • default (list): list of string defining the path of the node which will be opened at start up. Each node is identify its text string. • nodes (list): list of Node defining the navigation tree.

3.6. Viewport 19 plugin_dbui API Guide, Release 1.0.1

Type gluon.storage.Storage

Methods

add_node(*args) Add a list of Node to the navigation tree. default_node(*args) Deﬁned the node which will be opened at start up.

plugin_dbui.viewportmodiﬁer.ViewportModiﬁer.add_node

ViewportModifier.add_node(*args) Add a list of Node to the navigation tree. Parameters args (list) – variable list of Node

Note: Elements of the list equal to None are ignored.

Raises ViewportModifierException – when at least one element of the list is not a Node or None.

plugin_dbui.viewportmodiﬁer.ViewportModiﬁer.default_node

ViewportModifier.default_node(*args) Deﬁned the node which will be opened at start up. Parameters args (list) – variable list of string deﬁning the path of the leaf.

3.7 Convert database ﬁelds to widgets

to_field(field[, composite, linkedcombo]) Build the widget configuration for the database field. to_fields(table) Build the list of widget configurations for each field of the database table. to_formPanel(table, **kwargs) Build the configuration of the FormPanel widget for the database table. to_gridColumn(field, **kwargs) Build the configuration of the GridColumn for the database field. to_gridColumnModel(table) Build the configuration of the GridColumnModel for the database table. to_gridFilter(table, **kwargs) Build the configuration of the GridFilter widget for the database table. to_gridPanel(table, **kwargs) Build the configuration of the GridPanel widget for the database table. to_jsonstore(table, **kwargs) Build the configuration of the DirectStore associated to the database table. to_model(table) Build the configuration of the Model associated to the database table. to_panelWithUrlSelector(table[, . . . ]) Build the configuration of the PanelWithUrlSelector widget. Continued on next page

20 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Table 14 – continued from previous page to_treeNodes() Build the list of Node. to_viewport(**kwargs) Build the conﬁguration of the Viewport widget.

3.7.1 plugin_dbui.converter.to_ﬁeld

plugin_dbui.converter.to_field(field, composite=True, linkedcombo=True, **kwargs) Build the widget configuration for the database field. The return configuration depends on the type of the database field. It can be a Field, a ComboBox, a FieldDate, a FieldTextArea,... The conversion takes into account the FieldsModifier instructions and handles FieldContainer widget.

Note: Several database ﬁelds can be merged in a single FieldContainer widget using the method FieldsModifier.merge_fields().

Parameters • field (gluon.dal.Field) – database field. • composite (bool)– FieldContainer is ignored when False. • linkedcombo (bool)– LinkedComboBox are ignored when False. Keyword Arguments **kwargs (dict) – any Ext JS configuration parameter of the the 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.

3.7.2 plugin_dbui.converter.to_fields plugin_dbui.converter.to_fields(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 Field, a ComboBox, a FieldDate, a FieldTextArea,..., The configuration of the widget takes into account FieldsModifier instructions. It also handles FieldSet as well as FieldContainer widgets.

Note: Several database ﬁelds can be merged in a single FieldContainer widget using the method FieldsModifier.merge_fields(). Similarly, they can be grouped in a FieldSet widget via the method FormModifier.merge_fields().

Parameters table (gluon.dal.Table) – database table Returns list of Field elements.

3.7. Convert database ﬁelds to widgets 21 plugin_dbui API Guide, Release 1.0.1

3.7.3 plugin_dbui.converter.to_formPanel

plugin_dbui.converter.to_formPanel(table, **kwargs) Build the configuration of the FormPanel widget for the database table. The conversion takes into account the FormModifier instructions. Parameters table (gluon.dal.Table) – database table Keyword Arguments **kwargs (dict) – any Ext JS configuration parameter of the class FormPanel. They are applied in the following order: constructor, modifiers and keyword arguments. Returns FormPanel

3.7.4 plugin_dbui.converter.to_gridColumn

plugin_dbui.converter.to_gridColumn(field, **kwargs) Build the configuration of the GridColumn for the database field. The conversion takes into account the GridModifier instructions. Parameters field (gluon.dal.Field) – database field Keyword Arguments **kwargs (dict) – any Ext JS configuration parameter of the class GridColumn. They are applied in the following order: constructor, modifiers and keyword arguments. Returns GridColumn

3.7.5 plugin_dbui.converter.to_gridColumnModel plugin_dbui.converter.to_gridColumnModel(table) Build the conﬁguration of the GridColumnModel for the database table. The conversion takes into account the GridModifier instructions. Parameters table (gluon.dal.Table) – database table Returns GridColumnModel

3.7.6 plugin_dbui.converter.to_gridFilter plugin_dbui.converter.to_gridFilter(table, **kwargs) Build the configuration of the GridFilter widget for the database table. The GridFilter is defined by the method GridModifier.append_filter() and GridModifier. configure_filters() A GridFilter is a collection of widget. Each of them is associated to a database field. The configuration of the widget is similar to one use in the form for the database field. The configuration of the widget can be tuned via the keyword arguments. The configuration of the widget can be fully specified, without any link to the form. In that case, the keyword argument xtype has to be defined. Parameters table (gluon.dal.Table) – database table

22 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Keyword Arguments **kwargs (dict) – any of the Ext JS configuration parameters of the the GridFilter class. They are applied in the following order: constructor, modifiers, keyword arguments. Returns • GridFilter • Empty dictionary when filters are not defined

3.7.7 plugin_dbui.converter.to_gridPanel plugin_dbui.converter.to_gridPanel(table, **kwargs) Build the configuration of the GridPanel widget for the database table. The conversion takes into account the GridModifier instructions. Parameters table (gluon.dal.Table) – database table Keyword Arguments **kwargs (dict) – any of the Ext JS configuration parameters of the GridPanel class. They are applied in the following order: constructor, modifiers, keyword arguments. Returns GridPanel

3.7.8 plugin_dbui.converter.to_jsonstore plugin_dbui.converter.to_jsonstore(table, **kwargs) Build the configuration of the DirectStore associated to the database table. The conversion takes into account the StoreModifier instructions. Parameters table (gluon.dal.Table) – database table Keyword Arguments **kwargs (dict) – any of the Ext JS configuration parameters of the DirectStore class. They are applied in the following order: constructor, modifiers, keyword arguments. Returns DirectStore

3.7.9 plugin_dbui.converter.to_model plugin_dbui.converter.to_model(table) Build the conﬁguration of the Model associated to the database table. Parameters table (gluon.dal.Table) – database table Returns dict

3.7.10 plugin_dbui.converter.to_panelWithUrlSelector plugin_dbui.converter.to_panelWithUrlSelector(table, selectorLayout={’align’: ’stretch’, ’type’: ’vbox’, ’vertical’: True}, selec- torPlugins=[’pFormToolTip’], selectorTi- tle=’Select’, **kwargs) Build the conﬁguration of the PanelWithUrlSelector widget. Parameters

3.7. Convert database ﬁelds to widgets 23 plugin_dbui API Guide, Release 1.0.1

• table (gluon.dal.Table) – database table. It is used to build the form to select values. The form has one entry per table field. • selectorLayout (dict) – the layout for the field, by default vbox. • selectorPlugins (list) – list of plugins to be used by the selector. • 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 will be published in the panel. It is mandatory to specified the baseUrl. Keyword Arguments **kwargs (dict) – any of the Ext JS configuration parameters of the PanelWithUrlSelector` class. Returns PanelWithUrlSelector Raises BaseException – when the argument baseUrl is not defined.

3.7.11 plugin_dbui.converter.to_treeNodes plugin_dbui.converter.to_treeNodes() Build the list of Node. The nodes are displayed by the viewport widget. The list is built via the method ViewportModifier. add_node(). Returns list

3.7.12 plugin_dbui.converter.to_viewport plugin_dbui.converter.to_viewport(**kwargs) Build the conﬁguration of the Viewport widget. The conversion takes into account the ViewportModifier instructions. Keyword Arguments **kwargs (dict) – any of the Ext JS conﬁguration parameters of the Viewport` class. Returns dict

3.8 Ext JS widget mappings

ArrayStore(**kwargs) Configurator for the Ext.data.ArrayStore. CheckBox(**kwargs) Configurator for Ext.form.field.Checkbox. ComboBox(**kwargs) Configurator for Dbui.form.field.CombBox. DirectStore(**kwargs) Configurator for Dbui.data.DirectStore. Field(**kwargs) Configurator for Ext.form.field.Field. FieldAceEditor(**kwargs) Configurator for Dbui.form.field.AceEditor. FieldContainer(**kwargs) Configurator for Ext.form.FieldContainer. FieldDate(**kwargs) Configurator for Ext.form.field.Date. FieldDict(**kwargs) Configurator for Dbui.form.field.Dict. FieldList(**kwargs) Configurator for Dbui.form.field.List. Continued on next page

24 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Table 15 – continued from previous page FieldNumber(**kwargs) Configurator for Ext.form.field.Number. FieldSet(**kwargs) Configurator for Ext.form.FieldSet. FieldText(**kwargs) Configurator for Ext.form.field.Text. FieldTextArea(**kwargs) Configurator for Ext.form.field.TextArea. FieldTime(**kwargs) Configurator for Ext.form.field.Time. FormPanel(**kwargs) Configurator for Dbui.form.Panel. GridColumn Configurator for Ext.grid.Column. GridColumnModel Configurator for Ext.grid.ColumnModel. GridFilter(**kwargs) Configurator for Dbui.grid.Filter. GridPanel(**kwargs) Configurator for Dbui.grid.Panel. GridRowNumberer(**kwargs) Configurator for Ext.grid.column.RowNumberer. GridTemplateColumn(**kwargs) Configurator for Ext.grid.TemplateColumn. GridWithFilter(**kwargs) Configurator for Dbui.panel.GridWithFilter. JsonStore(**kwargs) Configurator for Ext.data.JsonStore. Model(**kwargs) Configurator for Ext.data.Model. Panel(**kwargs) Configurator for Ext.panel.Panel. PanelWithUrlSelector(**kwargs) Configurator for Dbui.panel.WithUrlSelector. Store(**kwargs) Configurator for Ext.data.Store. TabPanel(**kwargs) Configurator for Ext.tab.Panel. Viewport(**kwargs) Configurator for Dbui.container.Viewport. Window(**kwargs) Configurator for Ext.Window. XmlStore(**kwargs) Configurator for Ext.data.XmlStore.

3.8.1 plugin_dbui.extjs.ArrayStore class plugin_dbui.extjs.ArrayStore(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for the Ext.data.ArrayStore.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.ArrayStore.append_items

ArrayStore.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.ArrayStore.append_plugins

ArrayStore.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8. Ext JS widget mappings 25 plugin_dbui API Guide, Release 1.0.1

3.8.2 plugin_dbui.extjs.CheckBox class plugin_dbui.extjs.CheckBox(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.ﬁeld.Checkbox.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.CheckBox.append_items

CheckBox.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.CheckBox.append_plugins

CheckBox.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.3 plugin_dbui.extjs.ComboBox class plugin_dbui.extjs.ComboBox(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.form.ﬁeld.CombBox.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.ComboBox.append_items

ComboBox.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

26 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

plugin_dbui.extjs.ComboBox.append_plugins

ComboBox.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.4 plugin_dbui.extjs.DirectStore class plugin_dbui.extjs.DirectStore(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.data.DirectStore.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.DirectStore.append_items

DirectStore.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.DirectStore.append_plugins

DirectStore.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.5 plugin_dbui.extjs.Field class plugin_dbui.extjs.Field(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.ﬁeld.Field.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

3.8. Ext JS widget mappings 27 plugin_dbui API Guide, Release 1.0.1

plugin_dbui.extjs.Field.append_items

Field.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.Field.append_plugins

Field.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.6 plugin_dbui.extjs.FieldAceEditor class plugin_dbui.extjs.FieldAceEditor(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.form.ﬁeld.AceEditor.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldAceEditor.append_items

FieldAceEditor.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldAceEditor.append_plugins

FieldAceEditor.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.7 plugin_dbui.extjs.FieldContainer class plugin_dbui.extjs.FieldContainer(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.FieldContainer.

Methods

28 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldContainer.append_items

FieldContainer.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldContainer.append_plugins

FieldContainer.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.8 plugin_dbui.extjs.FieldDate class plugin_dbui.extjs.FieldDate(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.ﬁeld.Date.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldDate.append_items

FieldDate.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldDate.append_plugins

FieldDate.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8. Ext JS widget mappings 29 plugin_dbui API Guide, Release 1.0.1

3.8.9 plugin_dbui.extjs.FieldDict

class plugin_dbui.extjs.FieldDict(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.form.ﬁeld.Dict.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldDict.append_items

FieldDict.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldDict.append_plugins

FieldDict.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.10 plugin_dbui.extjs.FieldList class plugin_dbui.extjs.FieldList(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.form.ﬁeld.List.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldList.append_items

FieldList.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

30 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

plugin_dbui.extjs.FieldList.append_plugins

FieldList.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.11 plugin_dbui.extjs.FieldNumber class plugin_dbui.extjs.FieldNumber(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.ﬁeld.Number.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldNumber.append_items

FieldNumber.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldNumber.append_plugins

FieldNumber.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.12 plugin_dbui.extjs.FieldSet class plugin_dbui.extjs.FieldSet(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.FieldSet.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

3.8. Ext JS widget mappings 31 plugin_dbui API Guide, Release 1.0.1

plugin_dbui.extjs.FieldSet.append_items

FieldSet.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldSet.append_plugins

FieldSet.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.13 plugin_dbui.extjs.FieldText

class plugin_dbui.extjs.FieldText(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.ﬁeld.Text.

Note: Regular expression for the validation can be written as a string.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldText.append_items

FieldText.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldText.append_plugins

FieldText.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.14 plugin_dbui.extjs.FieldTextArea class plugin_dbui.extjs.FieldTextArea(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.ﬁeld.TextArea.

32 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Note: Regular expression for the validation can be written as a string.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldTextArea.append_items

FieldTextArea.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldTextArea.append_plugins

FieldTextArea.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.15 plugin_dbui.extjs.FieldTime class plugin_dbui.extjs.FieldTime(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.form.ﬁeld.Time.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FieldTime.append_items

FieldTime.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FieldTime.append_plugins

FieldTime.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

3.8. Ext JS widget mappings 33 plugin_dbui API Guide, Release 1.0.1

Parameters *args – variable list of plugin conﬁguration.

3.8.16 plugin_dbui.extjs.FormPanel

class plugin_dbui.extjs.FormPanel(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.form.Panel.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.FormPanel.append_items

FormPanel.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.FormPanel.append_plugins

FormPanel.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.17 plugin_dbui.extjs.GridColumn class plugin_dbui.extjs.GridColumn Bases: dict Conﬁgurator for Ext.grid.Column.

Methods

3.8.18 plugin_dbui.extjs.GridColumnModel

class plugin_dbui.extjs.GridColumnModel Bases: list Conﬁgurator for Ext.grid.ColumnModel.

Note: It is implemented as a list of GridColumn.

34 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Methods

3.8.19 plugin_dbui.extjs.GridFilter class plugin_dbui.extjs.GridFilter(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.grid.Filter.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.GridFilter.append_items

GridFilter.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.GridFilter.append_plugins

GridFilter.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.20 plugin_dbui.extjs.GridPanel class plugin_dbui.extjs.GridPanel(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.grid.Panel.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.GridPanel.append_items

GridPanel.append_items(*args) Append an widget conﬁgurations to the internal items list.

3.8. Ext JS widget mappings 35 plugin_dbui API Guide, Release 1.0.1

Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.GridPanel.append_plugins

GridPanel.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.21 plugin_dbui.extjs.GridRowNumberer class plugin_dbui.extjs.GridRowNumberer(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.grid.column.RowNumberer.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.GridRowNumberer.append_items

GridRowNumberer.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.GridRowNumberer.append_plugins

GridRowNumberer.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.22 plugin_dbui.extjs.GridTemplateColumn class plugin_dbui.extjs.GridTemplateColumn(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.grid.TemplateColumn.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. Continued on next page

36 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Table 37 – continued from previous page append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.GridTemplateColumn.append_items

GridTemplateColumn.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.GridTemplateColumn.append_plugins

GridTemplateColumn.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.23 plugin_dbui.extjs.GridWithFilter class plugin_dbui.extjs.GridWithFilter(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.panel.GridWithFilter.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.GridWithFilter.append_items

GridWithFilter.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.GridWithFilter.append_plugins

GridWithFilter.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.24 plugin_dbui.extjs.JsonStore class plugin_dbui.extjs.JsonStore(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.data.JsonStore.

3.8. Ext JS widget mappings 37 plugin_dbui API Guide, Release 1.0.1

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.JsonStore.append_items

JsonStore.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.JsonStore.append_plugins

JsonStore.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.25 plugin_dbui.extjs.Model class plugin_dbui.extjs.Model(**kwargs) Bases: dict Conﬁgurator for Ext.data.Model.

Methods

3.8.26 plugin_dbui.extjs.Panel

class plugin_dbui.extjs.Panel(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.panel.Panel.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.Panel.append_items

Panel.append_items(*args) Append an widget conﬁgurations to the internal items list.

38 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.Panel.append_plugins

Panel.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.27 plugin_dbui.extjs.PanelWithUrlSelector class plugin_dbui.extjs.PanelWithUrlSelector(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.panel.WithUrlSelector.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.PanelWithUrlSelector.append_items

PanelWithUrlSelector.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.PanelWithUrlSelector.append_plugins

PanelWithUrlSelector.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.28 plugin_dbui.extjs.Store class plugin_dbui.extjs.Store(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.data.Store.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. Continued on next page

3.8. Ext JS widget mappings 39 plugin_dbui API Guide, Release 1.0.1

Table 43 – continued from previous page append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.Store.append_items

Store.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.Store.append_plugins

Store.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.29 plugin_dbui.extjs.TabPanel class plugin_dbui.extjs.TabPanel(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.tab.Panel.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.TabPanel.append_items

TabPanel.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.TabPanel.append_plugins

TabPanel.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.30 plugin_dbui.extjs.Viewport class plugin_dbui.extjs.Viewport(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Dbui.container.Viewport.

40 Chapter 3. User interface plugin_dbui API Guide, Release 1.0.1

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.Viewport.append_items

Viewport.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.Viewport.append_plugins

Viewport.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8.31 plugin_dbui.extjs.Window class plugin_dbui.extjs.Window(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.Window.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.Window.append_items

Window.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.Window.append_plugins

Window.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

3.8. Ext JS widget mappings 41 plugin_dbui API Guide, Release 1.0.1

3.8.32 plugin_dbui.extjs.XmlStore class plugin_dbui.extjs.XmlStore(**kwargs) Bases: plugin_dbui.extjs.Base Conﬁgurator for Ext.data.XmlStore.

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.XmlStore.append_items

XmlStore.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.XmlStore.append_plugins

XmlStore.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

42 Chapter 3. User interface CHAPTER FOUR

CONTROLLER

4.1 Selector

Selector(table[, exclude_ﬁelds]) Basic tool to build a report:

4.1.1 plugin_dbui.selector.Selector class plugin_dbui.selector.Selector(table, exclude_fields=()) Bases: gluon.storage.Storage Basic tool to build a report: • Decode the data send by the selector form. • Build the query for a given table of the database. The basic query handles constraints from the selected values as well as the the inner join for reference field. Additional constraints can also be added via the method append_query(). • Select Rows for a given table of the database using the query defined in the previous item.

Parameters • table (gluon.dal.Table) – the model of the database table is used to build the form. Each field of the table is transformed into a form field widget. In addition, each database field is mapped to a selector attribute containing the value chosen by the user. • exclude_fields (tuple) – a list of database field names which have to be ignored in query and select operations.

Methods

append_query(query) Add constraints which will be used in the database query and select operations. as_dict() Return the selector fields and their values. fields() Get the list of field names defined in the selector. query(table) Build the database query for the database table. repr_url() Get the URL string corresponding to the current request. select(table, *args, **kwargs) Select the records of the table according to the selector constraints and to the extra queries.

43 plugin_dbui API Guide, Release 1.0.1

plugin_dbui.selector.Selector.append_query

Selector.append_query(query) Add constraints which will be used in the database query and select operations. Parameters query (gluon.dal.Query) – database query

plugin_dbui.selector.Selector.as_dict

Selector.as_dict() Return the selector ﬁelds and their values. Returns Return type dict

plugin_dbui.selector.Selector.ﬁelds

Selector.fields() Get the list of ﬁeld names deﬁned in the selector. Returns Return type list

plugin_dbui.selector.Selector.query

Selector.query(table) Build the database query for the database table. It includes: • inner join for reference ﬁelds • selector constraints • extra queries added via the append_query() method. • the extfield attribute as well as the exclude_fields speciﬁed in the constructor are not take into account in the query.

Parameters table (gluon.dal.Table) – database table Returns Return type gluon.dal.Query

plugin_dbui.selector.Selector.repr_url

Selector.repr_url() Get the URL string corresponding to the current request. Returns Return type str

44 Chapter 4. Controller plugin_dbui API Guide, Release 1.0.1

plugin_dbui.selector.Selector.select

Selector.select(table, *args, **kwargs) Select the records of the table according to the selector constraints and to the extra queries.

Notes

• The extfield attribute as well as the exclude_fields speciﬁed in the constructor are not take into account in the underlying query. • the returns Rows contains reference tables and columns.

Parameters • table (gluon.dal.Table) – database table • *args (list) – variable list of ﬁelds with operator like avg, count, max, min and sum. Keyword Arguments **kwargs (dict) – the keyword arguments are those of the gluon.dal.Set.select method: orderby, groupby, . . . . Returns Return type gluon.dal.Rows

4.2 Helper functions

as_list(val) Encapsulated val into a list when val is not an instance of a list. close_user_session() Close a user session. decode_field(field) Decode a string in CapitalizeWords into a list of words where all words are in lower case. dummy_row(table[, val]) Create a dummy Row for the table. encode_field(*args) Encode the string arguments into a CapitalizeWords. encode_validator_errors(error) Encode and translate the validator errors. get_all_tables(dal) Get the list of names for all tables in the database, dal, including alias table. get_create_id(table, **kwargs) Get the id of the record identified by a set of field=value keyword arguments. get_field_validators(field) Get the Ext JS configuration parameters to run database gluon.dal.Field validators on the client-side. get_file_paths(path[, ext, alpha]) get the local paths for files matching the arguments. get_foreign_field(field) Get reference table, field, and primary key names. get_id(table, **kwargs) Get the id of the record identified by a set of field=value keyword arguments. get_language() Get the primary language of the application from the HTML language code, e.g. en, fr,.... get_plugin_path(plugin_name) Get the local path of the plugin identified by its name. get_reference_paths() Get a tuple with the absolute and local paths: get_set_field(field) Get the list of the set data for the field when defines. Continued on next page

4.2. Helper functions 45 plugin_dbui API Guide, Release 1.0.1

Table 3 – continued from previous page get_script_path(plugin) Get the local path of the main javascript script to be ran on the client-side. get_set_field(field) Get the list of the set data for the field when defines. get_store_id(name) Build the store identifier using name. get_versions() Get the versions of the application and plugins. get_where_query(table) Build the gluon.dal.Query resolving foreign keys for the table. is_foreign_field(field) Return True when the field is a reference field. is_mathjax() Return True when the plugin mathjax is installed. is_set_field(field) Return True when the field value should matches those of a set. is_table_with_foreign_fields(table) Return True when the database table has at least one reference field. rows_serializer(rows) Serialize a gluon.dal.Rows as a list of dictionary.

4.2.1 plugin_dbui.helper.as_list

plugin_dbui.helper.as_list(val) Encapsulated val into a list when val is not an instance of a list. Parameters val (any) – input value Returns Return type list

4.2.2 plugin_dbui.helper.close_user_session

plugin_dbui.helper.close_user_session() Close a user session. Logout the user and destroy the session ﬁle.

4.2.3 plugin_dbui.helper.decode_ﬁeld

plugin_dbui.helper.decode_field(ﬁeld) Decode a string in CapitalizeWords into a list of words where all words are in lower case. The reverse function is encode_field(). Note useful to decode database ﬁeld name: TableField or TableFieldFunction Parameters field (str) – value Returns Return type tuple

4.2.4 plugin_dbui.helper.dummy_row plugin_dbui.helper.dummy_row(table, val=”) Create a dummy Row for the table. The row contains keys for the table and for the reference tables. Each ﬁeld are set to val. The Row van be inserted in a gluon.dal.Rows:

46 Chapter 4. Controller plugin_dbui API Guide, Release 1.0.1

rows= db(query).select(orderby=db.table.field) empty_row= dummy_row(db.table) row.records.append(row)

Parameters • table (gluon.dal.Table) – database table • val (str) – value associated to each ﬁeld either an empty string of None Returns Return type gluon.dal.Row

4.2.5 plugin_dbui.helper.encode_ﬁeld plugin_dbui.helper.encode_field(*args) Encode the string arguments into a CapitalizeWords. The reverse function is decode_field(). Returns Return type str

Note: useful to build database ﬁeld name like TableField or TableFieldFunc.

Note: The Ext JS ComboBox don’t decode properly any separator between table and ﬁeld like table+ﬁeld. Therefore choice for the encoding are very limited.

4.2.6 plugin_dbui.helper.encode_validator_errors

plugin_dbui.helper.encode_validator_errors(error) Encode and translate the validator errors. Parameters error (dict) – the key is the table ﬁeld encode as TablenameFieldname while the value is the error message return by the validator Returns error message are translated and should be more friendly since it contains the ﬁeld name with its error. Return type dict

4.2.7 plugin_dbui.helper.get_all_tables

plugin_dbui.helper.get_all_tables(dal) Get the list of names for all tables in the database, dal, including alias table. Parameters dal (gluon.dal.DAL) – the database Returns Return type list

4.2. Helper functions 47 plugin_dbui API Guide, Release 1.0.1

Note: It is recommend to use standard iterator provided by the gluon.dal.DAL class. However by construction, they ignore alias table.

4.2.8 plugin_dbui.helper.get_create_id plugin_dbui.helper.get_create_id(table, **kwargs) Get the id of the record identiﬁed by a set of field=value keyword arguments. If the record does not exist it is created with the values speciﬁed in the keywords arguments.

Example

rec_id = get_create_id(db.person, ﬁrst_name=”Joe”, last_name=”Doe”) Parameters table (gluon.dal.Table) – database table Returns the id of the record Return type int

4.2.9 plugin_dbui.helper.get_field_validators plugin_dbui.helper.get_field_validators(field) Get the Ext JS configuration parameters to run database gluon.dal.Field validators on the client-side. Parameters field (gluon.dal.Field) – database field Returns the keys depend on the validators. Possible values are minValue, maxValue, regex, regexText,‘‘maxLength‘‘, minLength,... Return type dict

4.2.10 plugin_dbui.helper.get_file_paths plugin_dbui.helper.get_file_paths(path, ext=None, alpha=True) get the local paths for files matching the arguments. For example, to get the paths of the javascript source files located in the local directory static/plugin_dbui/src:

li= get_file_paths("static/plugin_dbui/src", ext=".js")

The local paths are relative to the application directory. Parameters • path (None, list or str) – local path defining the target files: – None. – a string pointing to one files. – a list of strings pointing to several files. – a string pointing to a directory. – a list of string pointing to files and directory. • ext (str) – select only files with the extension ext, e.g .js, .css,...

48 Chapter 4. Controller plugin_dbui API Guide, Release 1.0.1

• alpha (bool) – sort the paths in alphabetic order Returns • paths for all selected ﬁles, • absolute path with respect to application • for example: /myapp/static/myapp-min.js Return type list or string

4.2.11 plugin_dbui.helper.get_foreign_field plugin_dbui.helper.get_foreign_field(field) Get reference table, field, and primary key names. Parameters field (gluon.dal.Field) – database field Returns • k_tablename name of the reference table • k_fieldname name of the reference field • k_keyname name of the primary key of the reference table. • None for standard field. Return type tuple

4.2.12 plugin_dbui.helper.get_id plugin_dbui.helper.get_id(table, **kwargs) Get the id of the record identiﬁed by a set of field=value keyword arguments. Return None if the record does not exist. Parameters table (gluon.dal.Table) – database table Returns • int – the id of the record • None when the record does not exist

4.2.13 plugin_dbui.helper.get_language plugin_dbui.helper.get_language() Get the primary language of the application from the HTML language code, e.g. en, fr,.... Returns str

4.2.14 plugin_dbui.helper.get_plugin_path plugin_dbui.helper.get_plugin_path(plugin_name) Get the local path of the plugin identiﬁed by its name. Parameters plugin_name (str) – name of the plugin, e.g. plugin_dbui Returns

4.2. Helper functions 49 plugin_dbui API Guide, Release 1.0.1

• the path of the ﬁrst directory starting with plugin_name. • absolute path with respect to application • for example: /myapp/static/plugin_foo • None if the plugin is not found. Return type str

4.2.15 plugin_dbui.helper.get_reference_paths plugin_dbui.helper.get_reference_paths() Get a tuple with the absolute and local paths: • The absolute path is relative to the web2py directory. It is useful on the server-side • The local path is relative to the applications directory. It is useful on the client-side

Returns ("applications/myapp", "/myapp") Return type tuple

4.2.16 plugin_dbui.helper.get_set_field plugin_dbui.helper.get_set_field(field) Get the list of the set data for the field when defines. Parameters field (gluon.dal.Field) – database field Returns Return type list

4.2.17 plugin_dbui.helper.get_script_path plugin_dbui.helper.get_script_path(plugin) Get the local path of the main javascript script to be ran on the client-side:

import plugin_dbui as dbui plugin= plugins.dbui path= dbui.get_script_path(plugin)

The main script can be selected in several ways: • via the default script • via the URL calling the application • via the conﬁguration parameter of the plugin_dbui Via the default value: • the default script is located in static/plugin_dbui/main.js Via the URL: • the URL should contain the argument script=foo or script=foo.js • the script is search in app_script_dir, one of the plugin_dbui conﬁguration parameters.

50 Chapter 4. Controller plugin_dbui API Guide, Release 1.0.1

Via plugin_dbui configuration: • the script path is defined by the plugin_dbui configuration parameters app_script.

Parameters plugin (reference) – web2py plugin instance Returns • absolute path with respect to the application • for example /myapp/blabla. Return type str

4.2.18 plugin_dbui.helper.get_store_id

plugin_dbui.helper.get_store_id(name) Build the store identiﬁer using name. Parameters name (str)– Returns nameStore Return type str

4.2.19 plugin_dbui.helper.get_versions

plugin_dbui.helper.get_versions() Get the versions of the application and plugins. Returns each dictionary contains the name of the software and its version identiﬁer. The keys are code and version Return type list of dict

4.2.20 plugin_dbui.helper.get_where_query

plugin_dbui.helper.get_where_query(table) Build the gluon.dal.Query resolving foreign keys for the table. Parameters table (gluon.dal.Table) – database table Returns • gluon.dal.Query • None when the table has no foreign key

4.2.21 plugin_dbui.helper.is_foreign_field plugin_dbui.helper.is_foreign_field(field) Return True when the field is a reference field. Parameters field (gluon.dal.Field) – database field Returns Return type bool

4.2. Helper functions 51 plugin_dbui API Guide, Release 1.0.1

4.2.22 plugin_dbui.helper.is_mathjax plugin_dbui.helper.is_mathjax() Return True when the plugin mathjax is installed. Returns Return type bool

4.2.23 plugin_dbui.helper.is_set_field plugin_dbui.helper.is_set_field(field) Return True when the field value should matches those of a set. Parameters field (gluon.dal.Field) – database field Returns Return type bool

4.2.24 plugin_dbui.helper.is_table_with_foreign_ﬁelds plugin_dbui.helper.is_table_with_foreign_fields(table) Return True when the database table has at least one reference ﬁeld. Parameters table (gluon.dal.Table) – database table Returns Return type bool

4.2.25 plugin_dbui.helper.rows_serializer plugin_dbui.helper.rows_serializer(rows) Serialize a gluon.dal.Rows as a list of dictionary. It handle the general case where ﬁeld belongs to different table and where function are applied. Parameters rows (gluon.dal.Rows) – list of database records Returns • [{Table1Field1: val1,...}, {Table1Field1: val2,...}, ...] • A dictionary per row. • Field are encoded as TableField. • Field with an applied function like COUNT(table.ﬁeld) are encoded as TableFieldCount. Return type list

52 Chapter 4. Controller CHAPTER FIVE

SERVICES, EXCEPTION AND BASE CLASSES

5.1 Services

DbSvc() Interface the database and the client request.

5.1.1 plugin_dbui.dbsvc.DbSvc class plugin_dbui.dbsvc.DbSvc Bases: plugin_dbui.basesvc.BaseSvc Interface the database and the client request. It is the glue between wep2py and Ext JS library. This service is the companion of DirectSvc which implements the Ext.Direct protocol on the server side. This protocol exposes methods of the DbSvc service directly on the client-side. The main methods allow to: • create a new record in a table. • read the content of a a table resolving foreign key. • update the record of a table. • destroy the record of a table. These methods receive the transaction data dictionary, arg. It as mainly three keys: • tableName the name of the table in the database • dbFields The list of database fields of the table, [["table1", "field1"], ... ] including foreign keys and their reference fields. • records (optional) A list of dictionaries containing key, value pairs for fields to be created or updated, [{"Table1Field1": val1,...}] including foreign key and reference field values. Each dictionary also contains the id of the record to be updated. The keys are encoded as Table1Field1. The records can also be a list containing the id of the records to be deleted. Each method return the dictionary:

{success: True, records:[{blabla},..], msg:"blalbla"}

• The keyword success is always present. It is mandatory for the FormPanel widget of the Ext JS library, but not strictly required since failure can be propagated through HTTP errors. • The keys of the record dictionary are the database ﬁelds encoded as TableField.

53 plugin_dbui API Guide, Release 1.0.1

The DbSvcException is raised when the action failed. It can be caught to generate an HTTP error.

Methods

count(tablename) Count the total number of records in the table create(arg) Create new records defined by the transaction dictionary arg. destroy(arg) Delete existing records defined by the transaction dictionary arg. read(arg) Read the content of a table as specified in the transaction dictionary arg. update(arg) Update records defined by the transaction dictionary arg.

plugin_dbui.dbsvc.DbSvc.count

DbSvc.count(tablename) Count the total number of records in the table Parameters tablename (str) – name of the database table

plugin_dbui.dbsvc.DbSvc.create

DbSvc.create(arg) Create new records defined by the transaction dictionary arg. Several create transactions can be processed at the same time. Parameters arg (dict) – input transaction dictionary Returns output transaction dictionary. The full transaction is aborted when: • at least one field value is not validated by the database engine. The keyword errors contains the dictionary returns by the validator (the key is the field identifier encoded as Table1Field1 while the value is the error message). • It is is killed by the callback defined in the database model, db[tablename]. _before_insert. The keyword errors contains the string returns by the callback. Return type dict

plugin_dbui.dbsvc.DbSvc.destroy

DbSvc.destroy(arg) Delete existing records deﬁned by the transaction dictionary arg. Several destroy transactions can be processed at the same time. Parameters arg (dict) – input transaction dictionary. The keyword records contains the list of rec_id to be deleted e.g. [id1, id2, ... ]. Returns output transaction dictionary.

54 Chapter 5. Services, exception and base classes plugin_dbui API Guide, Release 1.0.1

• The keyword records is the list of dictionary containing the rec_id of the deleted records e.g. [{TableId:xx}, ..]. • The full transaction is aborted when: one record does not exist. The delete operation is rejected by the callback db[tablename]._before_delete deﬁned in the database model. The keyword errors contains the error message returns by the callback. Return type dict

plugin_dbui.dbsvc.DbSvc.read

DbSvc.read(arg) Read the content of a table as speciﬁed in the transaction dictionary arg. Parameters arg (dict) – input transaction dictionary: • The optional key where is a list of string to build the inner join when handling foreign key:

["db.table1.field1 == db.table2.id",...]

The syntax follows the web2py convention db.table1.field1 == db.table2. id. The different conditions are ANDed. • the optional key orderby is a list of tuples to build the order directive:

[("table1","field1","dir"), ("table2","field3","dir"),...]

The third argument is equal to "ASC" or "DESC". • The transaction dictionary can also contains parameters useful for paging. For more details, see the Ext.toolbar.Paging conﬁguration parameters: page, start, limit, sort and dir. Returns output transaction dictionary: • The keyword records is a list of dictionary containing all key value pairs for the record found in the database. Return type dict

plugin_dbui.dbsvc.DbSvc.update

DbSvc.update(arg) Update records deﬁned by the transaction dictionary arg. Several update transactions can be processed at the same time. Parameters arg (dict) – input transaction dictionary. The keyword records is the list of dictionaries, one per record to be updated. Each dictionary contains key, value pairs for ﬁelds to be updated as well as the record id.

5.1. Services 55 plugin_dbui API Guide, Release 1.0.1

Returns output transaction dictionary: • the key records is a list of dictionary containing the complete key, value pairs for the record updated in the database. • The full transaction is aborted when: a field value is not validated by the database engine. The errors key contains the dictionary returns by the validator (the key is the field identifier encoded as Table1Field1 while the value is the error message). The transaction is killed by the callback db[tablename]._before_update defined in the database model. The errors key contains the message (str) returns by callback. Return type dict

DirectSvc() Generic service to implement the Ext.Direct protocol on the server-side.

5.1.2 plugin_dbui.directsvc.DirectSvc class plugin_dbui.directsvc.DirectSvc Bases: plugin_dbui.basesvc.BaseSvc Generic service to implement the Ext.Direct protocol on the server-side. This implementation is based on the web2py service using a simpliﬁed version of the class gluon.tools. Service. To functions have to registered in order to be available on the client-side. The technique is based on decorator:

service= DirectSvc()

@service.register def myfunction(a, b):

The same approach can be used for methods. On the client-side: • the API deﬁnition can be retrieved at the URL: /myapplication/plugin_dbui/call/get_api • the URL to send requests is /myapplication/plugin_dbui/call • remote functions and methods are available in the Dbui name space. They can be call in the following way Dbui.myfunction(a, b, callback) and Dbui.MyClass.mymethod(c, d, callback) respectively. In this implementation requests and responses are JSON encoded. procedures Type dict

Methods

56 Chapter 5. Services, exception and base classes plugin_dbui API Guide, Release 1.0.1

echo(x) Return the input arguments to run echo tests. error(code, message) Build and raise the gluon.http.HTTP exception. register(f) Register a function/method. route() Route the request to the appropriate function / method.

plugin_dbui.directsvc.DirectSvc.echo

DirectSvc.echo(x) Return the input arguments to run echo tests.

plugin_dbui.directsvc.DirectSvc.error

DirectSvc.error(code, message) Build and raise the gluon.http.HTTP exception. Parameters • code (int) – code of the HTTP error • message (str) – explanation for the HTTP error Raises gluon.http.HTTP –

plugin_dbui.directsvc.DirectSvc.register

DirectSvc.register(f ) Register a function/method. The technique relies on decorator:

service= DirectSvc()

@service.register def myfunction(a, b):

Parameters f (function) – reference to a function Returns the input function

plugin_dbui.directsvc.DirectSvc.route

DirectSvc.route() Route the request to the appropriate function / method. Returns the response of the function / method encoded as a JSON string. Return type str Raises gluon.http.HTTP – with the code 500 when the execution of the function / method crash. The python trace back is stored in the web2py ticket system.

5.1. Services 57 plugin_dbui API Guide, Release 1.0.1

5.2 Exceptions

DbSvcException

5.2.1 plugin_dbui.dbsvc.DbSvcException

exception plugin_dbui.dbsvc.DbSvcException

ExtJSException

5.2.2 plugin_dbui.extjs.ExtJSException

exception plugin_dbui.extjs.ExtJSException

GridModifierException

5.2.3 plugin_dbui.gridmodiﬁer.GridModiﬁerException

exception plugin_dbui.gridmodifier.GridModifierException

ViewportModifierException

5.2.4 plugin_dbui.viewportmodiﬁer.ViewportModiﬁerException

exception plugin_dbui.viewportmodifier.ViewportModifierException

5.3 Base classes

BaseSvc() Base class to build service.

5.3.1 plugin_dbui.basesvc.BaseSvc

class plugin_dbui.basesvc.BaseSvc Bases: object Base class to build service. debug activate the debug mode Type bool

Methods

58 Chapter 5. Services, exception and base classes plugin_dbui API Guide, Release 1.0.1

dbg(*args) Print the arguments when the attribute debug is true.

plugin_dbui.basesvc.BaseSvc.dbg

BaseSvc.dbg(*args) Print the arguments when the attribute debug is true. Parameters *args (object) – variable list of objects to be printed

Base(**kwargs) Base class for Ext JS conﬁgurator.

5.3.2 plugin_dbui.extjs.Base class plugin_dbui.extjs.Base(**kwargs) Bases: gluon.storage.Storage Base class for Ext JS conﬁgurator. Keyword Arguments **kwargs – any Ext JS conﬁguration parameter of the target class Raises ExtJSException – when the keyword xtype is presented in the keyword arguments. xtype the xtype of the target Ext JS widget. Type str

Methods

append_items(*args) Append an widget conﬁgurations to the internal items list. append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list.

plugin_dbui.extjs.Base.append_items

Base.append_items(*args) Append an widget conﬁgurations to the internal items list. Parameters *args – variable list of widget conﬁguration.

plugin_dbui.extjs.Base.append_plugins

Base.append_plugins(*args) Append an plugin conﬁgurations to the internal plugin list. Parameters *args – variable list of plugin conﬁguration.

Modifier(dpname[, tablename]) Base class to construct Modiﬁer tools.

5.3. Base classes 59 plugin_dbui API Guide, Release 1.0.1

5.3.3 plugin_dbui.modifier.Modifier class plugin_dbui.modifier.Modifier(dpname, tablename=None) Base class to construct Modifier tools. Parameters • dpname (str) – name of the data point. • tablename (str) – name of the database table.

Notes

• A modiﬁer stores its instructions in a global buffer handles by the web2py PluginManager. • The instructions are kept in a gluon.storage.Storage. Its path is deﬁned by the dpname and tablename arguments. • The storage can be accessed from anywhere:

p= PluginManager("dbui") modifier=p.dbui[dpname]

or when the tablename is deﬁned:

p= PluginManager("dbui") modifier=p.dbui[dpname][tablename]

data contains all the instructions. It has one key/attribute: • extjs to store conﬁguration options of the associate Ext JS widget.

Type gluon.storage.Storage

Methods

configure(**extjs) Set the conﬁguration parameters for the associated Ext JS widget.

plugin_dbui.modifier.Modifier.configure

Modifier.configure(**extjs) Set the conﬁguration parameters for the associated Ext JS widget. Keyword Arguments **extjs – any conﬁguration options of the associated Ext JS widget.

Notes

• Existing value of the configuration parameters are replaced by those defined in the keyword arguments. • The keyword argument plugins contains a list of plugins. The current list of plugins are extend with the new ones defined by the keyword argument plugins.

60 Chapter 5. Services, exception and base classes plugin_dbui API Guide, Release 1.0.1

If a plugin with the same ptype alsready exists in the list it is replaced by the new definition. • A plugin can be defined by a string containing is pType. • A plugin can be defined by a dictionary containing the pType and the plugin configuration options:

{"ptype": foo,"option1": val,...}

• The widget associated by default is replaced by a new one when the keyword argument xtype is used.

5.3. Base classes 61 plugin_dbui API Guide, Release 1.0.1

62 Chapter 5. Services, exception and base classes CHAPTER SIX

INDICES AND TABLES

• genindex • search