sqlhtml Module

This file is part of the web2py Web Framework
Copyrighted by Massimo Di Pierro <mdipierro@cs.depaul.edu>

Holds:

  • SQLFORM: provide a form for a table (with/without record)
  • SQLTABLE: provides a table for a set of records
  • form_factory: provides a SQLFORM for an non-db backed table
class gluon.sqlhtml.AutocompleteWidget(request, field, id_field=None, db=None, orderby=None, limitby=(0, 10), distinct=False, keyword='_autocomplete_%(tablename)s_%(fieldname)s', min_length=2, help_fields=None, help_string=None, at_beginning=True)[source]

Bases: object

callback()[source]
class gluon.sqlhtml.BooleanWidget[source]

Bases: gluon.sqlhtml.FormWidget

classmethod widget(field, value, **attributes)[source]

Generates an INPUT checkbox tag.

see also: FormWidget.widget

class gluon.sqlhtml.CacheRepresenter[source]

Bases: object

class gluon.sqlhtml.CheckboxesWidget[source]

Bases: gluon.sqlhtml.OptionsWidget

classmethod widget(field, value, **attributes)[source]

Generates a TABLE tag, including INPUT checkboxes (multiple allowed)

see also: FormWidget.widget

class gluon.sqlhtml.DateWidget[source]

Bases: gluon.sqlhtml.StringWidget

class gluon.sqlhtml.DatetimeWidget[source]

Bases: gluon.sqlhtml.StringWidget

class gluon.sqlhtml.DecimalWidget[source]

Bases: gluon.sqlhtml.StringWidget

class gluon.sqlhtml.DoubleWidget[source]

Bases: gluon.sqlhtml.StringWidget

class gluon.sqlhtml.ExportClass(rows)[source]

Bases: object

content_type = None
export()[source]
file_ext = None
label = None
represented()[source]
class gluon.sqlhtml.ExporterCSV(rows)[source]

Bases: gluon.sqlhtml.ExportClass

content_type = 'text/csv'
export()[source]
file_ext = 'csv'
label = 'CSV'
class gluon.sqlhtml.ExporterCSV_hidden(rows)[source]

Bases: gluon.sqlhtml.ExportClass

content_type = 'text/csv'
export()[source]
file_ext = 'csv'
label = 'CSV'
class gluon.sqlhtml.ExporterHTML(rows)[source]

Bases: gluon.sqlhtml.ExportClass

content_type = 'text/html'
export()[source]
file_ext = 'html'
label = 'HTML'
class gluon.sqlhtml.ExporterJSON(rows)[source]

Bases: gluon.sqlhtml.ExportClass

content_type = 'application/json'
export()[source]
file_ext = 'json'
label = 'JSON'
class gluon.sqlhtml.ExporterTSV(rows)[source]

Bases: gluon.sqlhtml.ExportClass

content_type = 'text/tab-separated-values'
export()[source]
file_ext = 'csv'
label = 'TSV'
class gluon.sqlhtml.ExporterXML(rows)[source]

Bases: gluon.sqlhtml.ExportClass

content_type = 'text/xml'
export()[source]
file_ext = 'xml'
label = 'XML'
class gluon.sqlhtml.FormWidget[source]

Bases: object

Helper for SQLFORM to generate form input fields (widget), related to the fieldtype

classmethod widget(field, value, **attributes)[source]

Generates the widget for the field.

When serialized, will provide an INPUT tag:

  • id = tablename_fieldname
  • class = field.type
  • name = fieldname
Parameters:
  • field – the field needing the widget
  • value – value
  • attributes – any other attributes to be applied
class gluon.sqlhtml.IntegerWidget[source]

Bases: gluon.sqlhtml.StringWidget

class gluon.sqlhtml.JSONWidget[source]

Bases: gluon.sqlhtml.FormWidget

classmethod widget(field, value, **attributes)[source]

Generates a TEXTAREA for JSON notation.

see also: FormWidget.widget

class gluon.sqlhtml.ListWidget[source]

Bases: gluon.sqlhtml.StringWidget

classmethod widget(field, value, **attributes)[source]
class gluon.sqlhtml.MultipleOptionsWidget[source]

Bases: gluon.sqlhtml.OptionsWidget

classmethod widget(field, value, size=5, **attributes)[source]

Generates a SELECT tag, including OPTIONs (multiple options allowed)

see also: FormWidget.widget

Parameters:size – optional param (default=5) to indicate how many rows must be shown
class gluon.sqlhtml.OptionsWidget[source]

Bases: gluon.sqlhtml.FormWidget

static has_options(field)[source]

Checks if the field has selectable options

Parameters:field – the field needing checking
Returns:True if the field has options
classmethod widget(field, value, **attributes)[source]

Generates a SELECT tag, including OPTIONs (only 1 option allowed)

see also: FormWidget.widget

class gluon.sqlhtml.PasswordWidget[source]

Bases: gluon.sqlhtml.FormWidget

classmethod widget(field, value, **attributes)[source]

Generates a INPUT password tag. If a value is present it will be shown as a number of ‘*’, not related to the length of the actual value.

see also: FormWidget.widget

class gluon.sqlhtml.RadioWidget[source]

Bases: gluon.sqlhtml.OptionsWidget

classmethod widget(field, value, **attributes)[source]

Generates a TABLE tag, including INPUT radios (only 1 option allowed)

see also: FormWidget.widget

class gluon.sqlhtml.SQLFORM(table, record=None, deletable=False, linkto=None, upload=None, fields=None, labels=None, col3={}, submit_button='Submit', delete_label='Check to delete', showid=True, readonly=False, comments=True, keepopts=[], ignore_rw=False, record_id=None, formstyle=None, buttons=['submit'], separator=None, extra_fields=None, **attributes)[source]

Bases: gluon.html.FORM

SQLFORM is used to map a table (and a current record) into an HTML form.

Given a Table like db.table

Generates an insert form:

SQLFORM(db.table)

Generates an update form:

record=db.table[some_id]
SQLFORM(db.table, record)

Generates an update with a delete button:

SQLFORM(db.table, record, deletable=True)
Parameters:
  • tableTable object
  • record – either an int if the id is an int, or the record fetched from the table
  • deletable – adds the delete checkbox
  • linkto – the URL of a controller/function to access referencedby records
  • upload – the URL of a controller/function to download an uploaded file
  • fields – a list of fields that should be placed in the form, default is all.
  • labels – a dictionary with labels for each field, keys are the field names.
  • col3 – a dictionary with content for an optional third column (right of each field). keys are field names.
  • submit_button – text to show in the submit button
  • delete_label – text to show next to the delete checkbox
  • showid – shows the id of the record
  • readonly – doesn’t allow for any modification
  • comments – show comments (stored in col3 or in Field definition)
  • ignore_rw – overrides readable/writable attributes
  • record_id – used to create session key against CSRF
  • formstyle – what to use to generate the form layout
  • buttons – override buttons as you please (will be also stored in form.custom.submit)
  • separator – character as separator between labels and inputs

any named optional attribute is passed to the <form> tag for example _class, _id, _style, _action, _method, etc.

AUTOTYPES = {<type 'datetime.datetime'>: ('datetime', <gluon.validators.IS_DATETIME object>), <type 'float'>: ('double', <gluon.validators.IS_FLOAT_IN_RANGE object>), <type 'bool'>: ('boolean', None), <type 'int'>: ('integer', <gluon.validators.IS_INT_IN_RANGE object>), <type 'str'>: ('string', None), <type 'datetime.date'>: ('date', <gluon.validators.IS_DATE object>), <type 'unicode'>: ('string', None), <type 'list'>: ('list:string', None)}
FIELDKEY_DELETE_RECORD = 'delete_record'
FIELDNAME_REQUEST_DELETE = 'delete_this_record'
ID_LABEL_SUFFIX = '__label'
ID_ROW_SUFFIX = '__row'
accepts(request_vars, session=None, formname='%(tablename)s/%(record_id)s', keepvalues=None, onvalidation=None, dbio=True, hideerror=False, detect_record_change=False, **kwargs)[source]

Similar to FORM.accepts but also does insert, update or delete in DAL. If detect_record_change is True than:

  • form.record_changed = False (record is properly validated/submitted)
  • form.record_changed = True (record cannot be submitted because changed)

If detect_record_change == False than:

  • form.record_changed = None
assert_status(status, request_vars)[source]
static build_query(fields, keywords)[source]
createform(xfields)[source]
static dictform(dictionary, **kwargs)[source]
static factory(*fields, **attributes)[source]

Generates a SQLFORM for the given fields.

Internally will build a non-database based data model to hold the fields.

formstyles = <Storage {'bootstrap3_stacked': <function formstyle_bootstrap3_stacked>, 'bootstrap': <function formstyle_bootstrap>, 'bootstrap3_inline': <function _inner>, 'table2cols': <function formstyle_table2cols>, 'table3cols': <function formstyle_table3cols>, 'inline': <function formstyle_inline>, 'divs': <function formstyle_divs>, 'ul': <function formstyle_ul>}>
static grid(query, fields=None, field_id=None, left=None, headers={}, orderby=None, groupby=None, searchable=True, sortable=True, paginate=20, deletable=True, editable=True, details=True, selectable=None, create=True, csv=True, links=None, links_in_grid=True, upload='<default>', args=[], user_signature=True, maxtextlengths={}, maxtextlength=20, onvalidation=None, onfailure=None, oncreate=None, onupdate=None, ondelete=None, sorter_icons=(<gluon.html.XML object>, <gluon.html.XML object>), ui='web2py', showbuttontext=True, _class='web2py_grid', formname='web2py_grid', search_widget='default', advanced_search=True, ignore_rw=False, formstyle=None, exportclasses=None, formargs={}, createargs={}, editargs={}, viewargs={}, selectable_submit_button='Submit', buttons_placement='right', links_placement='right', noconfirm=False, cache_count=None, client_side_delete=False, ignore_common_filters=None, auto_pagination=True, use_cursor=False)[source]
static search_menu(fields, search_options=None, prefix='w2p')[source]
static smartdictform(session, name, filename=None, query=None, **kwargs)[source]
static smartgrid(table, constraints=None, linked_tables=None, links=None, links_in_grid=True, args=None, user_signature=True, divider='>', breadcrumbs_class='', **kwargs)[source]

Builds a system of SQLFORM.grid(s) between any referenced tables

Parameters:
  • table – main table
  • constraints (dict) – {‘table’:query} that limits which records can be accessible
  • links (dict) – like {‘tablename’:[lambda row: A(....), ...]} that will add buttons when table tablename is displayed
  • linked_tables (list) – list of tables to be linked

Example

given you defined a model as:

db.define_table('person', Field('name'), format='%(name)s')
db.define_table('dog',
    Field('name'), Field('owner', db.person), format='%(name)s')
db.define_table('comment', Field('body'), Field('dog', db.dog))
if db(db.person).isempty():
    from gluon.contrib.populate import populate
    populate(db.person, 300)
    populate(db.dog, 300)
    populate(db.comment, 1000)

in a controller, you can do:

@auth.requires_login()
def index():
    form=SQLFORM.smartgrid(db[request.args(0) or 'person'])
    return dict(form=form)
widgets = <Storage {'multiple': <class 'gluon.sqlhtml.MultipleOptionsWidget'>, 'string': <class 'gluon.sqlhtml.StringWidget'>, 'text': <class 'gluon.sqlhtml.TextWidget'>, 'datetime': <class 'gluon.sqlhtml.DatetimeWidget'>, 'boolean': <class 'gluon.sqlhtml.BooleanWidget'>, 'radio': <class 'gluon.sqlhtml.RadioWidget'>, 'date': <class 'gluon.sqlhtml.DateWidget'>, 'integer': <class 'gluon.sqlhtml.IntegerWidget'>, 'password': <class 'gluon.sqlhtml.PasswordWidget'>, 'double': <class 'gluon.sqlhtml.DoubleWidget'>, 'decimal': <class 'gluon.sqlhtml.DecimalWidget'>, 'list': <class 'gluon.sqlhtml.ListWidget'>, 'upload': <class 'gluon.sqlhtml.UploadWidget'>, 'autocomplete': <class 'gluon.sqlhtml.AutocompleteWidget'>, 'json': <class 'gluon.sqlhtml.JSONWidget'>, 'checkboxes': <class 'gluon.sqlhtml.CheckboxesWidget'>, 'time': <class 'gluon.sqlhtml.TimeWidget'>, 'options': <class 'gluon.sqlhtml.OptionsWidget'>, 'blob': None}>
class gluon.sqlhtml.SQLTABLE(sqlrows, linkto=None, upload=None, orderby=None, headers={}, truncate=16, columns=None, th_link='', extracolumns=None, selectid=None, renderstyle=False, cid=None, colgroup=False, **attributes)[source]

Bases: gluon.html.TABLE

Given with a Rows object, as returned by a db().select(), generates an html table with the rows.

Parameters:
  • sqlrows – the Rows object
  • linkto – URL (or lambda to generate a URL) to edit individual records
  • upload – URL to download uploaded files
  • orderby – Add an orderby link to column headers.
  • headers – dictionary of headers to headers redefinions headers can also be a string to generate the headers from data for now only headers=”fieldname:capitalize”, headers=”labels” and headers=None are supported
  • truncate – length at which to truncate text in table cells. Defaults to 16 characters.
  • columns – a list or dict contaning the names of the columns to be shown Defaults to all
  • th_link – base link to support orderby headers
  • extracolumns – a list of dicts
  • selectid – The id you want to select
  • renderstyle – Boolean render the style with the table
  • cid – use this cid for all links
  • colgroup – #FIXME

Extracolumns example

[{'label':A('Extra', _href='#'),
'class': '', #class name of the header
'width':'', #width in pixels or %
'content':lambda row, rc: A('Edit', _href='edit/%s'%row.id),
'selected': False #agregate class selected to this column}]
style()[source]
class gluon.sqlhtml.StringWidget[source]

Bases: gluon.sqlhtml.FormWidget

classmethod widget(field, value, **attributes)[source]

Generates an INPUT text tag.

see also: FormWidget.widget

class gluon.sqlhtml.TextWidget[source]

Bases: gluon.sqlhtml.FormWidget

classmethod widget(field, value, **attributes)[source]

Generates a TEXTAREA tag.

see also: FormWidget.widget

class gluon.sqlhtml.TimeWidget[source]

Bases: gluon.sqlhtml.StringWidget

class gluon.sqlhtml.UploadWidget[source]

Bases: gluon.sqlhtml.FormWidget

DEFAULT_WIDTH = '150px'
DELETE_FILE = 'delete'
GENERIC_DESCRIPTION = 'file ## download'
ID_DELETE_SUFFIX = '__delete'
static is_image(value)[source]

Tries to check if the filename provided references to an image

Checking is based on filename extension. Currently recognized:
gif, png, jp(e)g, bmp
Parameters:value – filename
classmethod represent(field, value, download_url=None)[source]

How to represent the file:

  • with download url and if it is an image: <A href=...><IMG ...></A>
  • otherwise with download url: <A href=...>file</A>
  • otherwise: file
Parameters:
  • field – the field
  • value – the field value
  • download_url – url for the file download (default = None)
classmethod widget(field, value, download_url=None, **attributes)[source]

generates a INPUT file tag.

Optionally provides an A link to the file, including a checkbox so the file can be deleted.

All is wrapped in a DIV.

see also: FormWidget.widget

Parameters:
  • field – the field
  • value – the field value
  • download_url – url for the file download (default = None)
gluon.sqlhtml.add_class(a, b)[source]
gluon.sqlhtml.form_factory(*fields, **attributes)

Generates a SQLFORM for the given fields.

Internally will build a non-database based data model to hold the fields.

gluon.sqlhtml.formstyle_bootstrap(form, fields)[source]

bootstrap 2.3.x format form layout

gluon.sqlhtml.formstyle_bootstrap3_inline_factory(col_label_size=3)[source]

bootstrap 3 horizontal form layout

Note

Experimental!

gluon.sqlhtml.formstyle_bootstrap3_stacked(form, fields)[source]

bootstrap 3 format form layout

Note

Experimental!

gluon.sqlhtml.formstyle_divs(form, fields)[source]

divs only

gluon.sqlhtml.formstyle_inline(form, fields)[source]

divs only, but inline

gluon.sqlhtml.formstyle_table2cols(form, fields)[source]

2 column table

gluon.sqlhtml.formstyle_table3cols(form, fields)[source]

3 column table - default

gluon.sqlhtml.formstyle_ul(form, fields)[source]

unordered list

gluon.sqlhtml.represent(field, value, record)[source]
gluon.sqlhtml.safe_float(x)[source]
gluon.sqlhtml.safe_int(x)[source]
gluon.sqlhtml.show_if(cond)[source]