Built-in Renderers

class webgrid.renderers.HTML(grid)

Renderer for HTML output.

buffer_th(colspan, **kwargs)

Render a placeholder TH tag for spacing between column groups.

can_render()

Guard method for preventing a renderer from overflowing the target format.

For instance, spreadsheets have limitation in the number of possible rows. A renderer to that format should check that the record count does not exceed that limit.

Returns:

bool: True if the renderer can proceed.

property columns

Cache a set of columns from the grid that will render on this target.

confirm_export()

Export confirmation data as a JSON object for use by the JS asset.

current_url(**kwargs)

Generate a URL from current request args and the given kwargs.

export_url(renderer)

Generate a URL that will trigger an export to one of the grid’s renderers.

Args:

renderer (str): Export key (e.g. xlsx, csv) for rendering target.

filtering_add_filter_select()

Render the select box for adding a new filter. Used by the filter template.

filtering_col_inputs1(col)

Render the first input, which can be freeform or select.

filtering_col_inputs2(col)

Render the second filter input, currently only a freeform.

filtering_col_label(col)

Label getter for filter column.

filtering_col_op_select(col)

Render select box for filter Operator options.

filtering_fields()

Table rows for the filter area.

filtering_filter_options_multi(filter, field_name)

Render the multiselect options.

filtering_json_data()

Export certain filter data as a JSON object for use by the JS asset.

filtering_multiselect(field_name, current_selected, options)

Almost all selects are rendered with multiselect UI. Render that here.

Structure is based on the jQuery Multiselect plugin. For efficiency of render with large numbers of options, we customized the plugin for WebGrid use and offloaded the main render/transform here.

filtering_session_key()

Hidden input to preserve the session key on form submission.

filtering_table_attrs(**kwargs)

HTML attributes to render on the grid filter table element.

filtering_table_row(col)

Single filter row with op and inputs.

footer()

Render the grid footer area from template.

form_action_method()

Detect whether the header form should have a GET or POST action.

By default, we look at the grid manager’s args_loaders for RequestFormLoader. If it is present, the form will be POST.

form_action_url()

URL target for the grid header form.

get_add_filter_row()

Render just the Add Filter area on a row.

get_group_heading_colspans()

Computes the number of columns spanned by various groups.

Note, this may not be the number of columns in the group in the grid definition, because some of those columns may not render in this target.

get_search_row()

Render the single-search input, along with filter select.

grid_attrs()

HTML attributes to render on the main grid div element.

group_th(group, colspan, **kwargs)

Render a column group heading with the needed span.

Note, will render an empty placeholder if the column has no group.

has_groups()

Returns True if any of the renderer’s columns is part of a column group.

header()

Return content for the grid header area. Used by the grid template.

header_filtering()

Return content for the grid filter area. Used by the header template.

header_form_attrs(**kwargs)

HTML attributes to render on the grid header form element.

header_paging()

Render the paging area of the grid header.

header_sorting()

Render the sort area. Used by the header template.

load_content(endpoint, **kwargs)

Load content via Jinja templates.

Gives the grid manager a chance to render the template, in order to allow for application-level overrides on the grid templates. Otherwise, defaults to the internal Jinja environment set up for this renderer.

property name

Identifier used to find columns that will render on this target.

no_records()

Render a message paragraph indicating the current filters return no records.

paging_img_first()

Render the footer icon for the first page of the grid.

paging_img_first_dead()

Render the footer disabled icon for the first page of the grid.

paging_img_last()

Render the footer icon for the last page of the grid.

paging_img_last_dead()

Render the footer disabled icon for the last page of the grid.

paging_img_next()

Render the footer icon for the next page of the grid.

paging_img_next_dead()

Render the footer disabled icon for the next page of the grid.

paging_img_prev()

Render the footer icon for the previous page of the grid.

paging_img_prev_dead()

Render the footer disabled icon for the previous page of the grid.

paging_input()

Render the per-page input.

paging_select()

Render the page selection input.

paging_url_first()

Generate a URL for the first page of the grid.

paging_url_last()

Generate a URL for the last page of the grid.

paging_url_next()

Generate a URL for the next page of the grid.

paging_url_prev()

Generate a URL for the previous page of the grid.

render()

Main renderer method returning the output.

render_select(options, current_selection=None, placeholder=('', Markup(' ')), name=None, id=None, **kwargs)

Generalized select box renderer.

Args:

options (iterable): Option tuples (value, label) or (value, label, data). If the data piece is present, it will be rendered as the value of a “data-render” attribute on the option tag.

current_selection (iterable, optional): Option values to be marked as selected. Defaults to None.

placeholder (tuple(str), optional): Option to use as a “blank” value.

name (str, optional): Value for HTML name attribute. Defaults to None.

id (str, optional): Value for HTML id attribute. Defaults to a sanitized value derived from name.

kwargs: Passed as HTML attributes on the select tag.

reset_url(session_reset=True)

Generate a URL that will trigger a reset of the grid’s UI options.

sorting_select(number)

Render the dropdown select of sorting options.

Args:

number (int): Priority of ordering option.

Returns:

str: Jinja-rendered string.

sorting_select1()

Render the first sort select.

sorting_select2()

Render the second sort select.

sorting_select3()

Render the third sort select.

sorting_select_options()

Generate list of tuple pairs (key, label) and (-key, label DESC) for sort options.

Returns:

list: List of tuple pairs.

table()

Render the table area of the grid from template.

table_attrs(**kwargs)

Apply default HTML table attributes to the supplied kwargs.

Returns:

dict: keys/values to be rendered as attributes

table_column_headings()

Combine all rendered column headings and return as Markup.

table_grandtotals(rownum, record)

Render a Grand totals row based on subtotal columns defined in the grid.

table_group_headings()

Combine all rendered column group headings and return as Markup.

table_pagetotals(rownum, record)

Render a Page totals row based on subtotal columns defined in the grid.

table_rows()

Combine rows rendered from grid records, return as Markup.

Page/Grand totals are included here as rows if enabled in the grid.

table_td(col, record)

Render a table data cell.

Value is obtained for render from the grid column’s render method. To override how a column’s data is rendered specifically for HTML, supply a render_html method on the column.

table_th(col)

Render a single column heading TH tag.

Sortable columns are rendered as links with the needed URL args.

table_totals(rownum, record, label, numrecords)

Render a totals row based on subtotal columns defined in the grid.

table_tr(rownum, record)

Generate rendered cells and pass to table_tr_output for rendered result.

table_tr_output(cells, row_hah)

Combine rendered cells and output a TR tag.

table_tr_styler(rownum, record)

Compile the styling to be used on a given HTML grid row.

Applies odd/even class based on the row number. Adds in any row stylers present in grid configuration.

Args:

rownum (int): row number in the rendered grid. record (Any): result record.

Returns:

HTMLAttributes: attributes collection to be applied on a TR.

class webgrid.renderers.JSON(grid)

Renderer for JSON output

as_response()

Return a response via the grid’s manager.

can_render()

Guard method for preventing a renderer from overflowing the target format.

For instance, spreadsheets have limitation in the number of possible rows. A renderer to that format should check that the record count does not exceed that limit.

Returns:

bool: True if the renderer can proceed.

property columns

Cache a set of columns from the grid that will render on this target.

property name

Identifier used to find columns that will render on this target.

render()

Main renderer method returning the output.

serialized_columns()

Usually we would use the renderer’s column list. For JSON, though, we want to supply any labels possible for use in a front-end app. The front-end needs to know names for filters, for example.

class webgrid.renderers.XLSX(grid)

Renderer for Excel XLSX output.

adjust_column_widths(writer, wb)

Apply stored column widths to the XLSX worksheet.

as_response(wb=None, sheet_name=None)

Return an attachment file via the grid’s manager.

body_headings(xlh, wb)

Render group and column label rows.

Args:

xlh (WriterX): Helper for writing worksheet cells. wb (Workbook): xlsxwriter Workbook object for direct usage.

body_records(xlh, wb)

Render records and totals rows.

Args:

xlh (WriterX): Helper for writing worksheet cells. wb (Workbook): xlsxwriter Workbook object for direct usage.

build_sheet(wb=None, sheet_name=None)

Create and populate a worksheet for the current grid.

Args:

wb (Workbook, optional): xlsxwriter Workbook. Defaults to None (create one). sheet_name (str, optional): Sheet name. Defaults to None (use grid identity).

Raises:

ImportError: No suitable XLSX library installed. RenderLimitExceeded: Too many records to render to the target.

Returns:

Workbook: Created/supplied workbook with the rendered worksheet added.

can_render()

Guard method for preventing a renderer from overflowing the target format.

For instance, spreadsheets have limitation in the number of possible rows. A renderer to that format should check that the record count does not exceed that limit.

Returns:

bool: True if the renderer can proceed.

property columns

Cache a set of columns from the grid that will render on this target.

file_name()

Return an output filename based on grid identifier.

A random numeric suffix is added. This is due to Excel’s limitation to having only one workbook open with a given name. Excel will not allow a second file with the same name to open, even if the files are in different paths.

get_group_heading_colspans()

Computes the number of columns spanned by various groups.

Note, this may not be the number of columns in the group in the grid definition, because some of those columns may not render in this target.

has_groups()

Returns True if any of the renderer’s columns is part of a column group.

property name

Identifier used to find columns that will render on this target.

record_row(xlh, rownum, record, wb)

Render a single row from data record.

Value is obtained for render from the grid column’s render method. To override how a column’s data is rendered specifically for XLSX, supply a render_xlsx method on the column.

Args:

xlh (WriterX): Helper for writing worksheet cells. rownum (int): Not used by default, but helpful for style overrides. record (Any): Object containing row data. wb (Workbook): xlsxwriter Workbook object for direct usage.

render()

Main renderer method returning the output.

sanitize_sheet_name(sheet_name)

Work around Excel limitations on names of worksheets.

sheet_body(xlh, wb)

Render the headings/records area of the worksheet.

Args:

xlh (WriterX): Helper for writing worksheet cells. wb (Workbook): xlsxwriter Workbook object for direct usage.

sheet_footer(xlh, wb)

Placeholder method for app-specific sheet footer rendering.

Args:

xlh (WriterX): Helper for writing worksheet cells. wb (Workbook): xlsxwriter Workbook object for direct usage.

sheet_header(xlh, wb)

Placeholder method for app-specific sheet header rendering.

Args:

xlh (WriterX): Helper for writing worksheet cells. wb (Workbook): xlsxwriter Workbook object for direct usage.

totals_row(xlh, rownum, record, wb)

Render a totals row based on subtotal columns defined in the grid.

update_column_width(col, data)

Compute and store a column width from length of current data.

class webgrid.renderers.CSV(grid)

Renderer for CSV output.

as_response()

Return an attachment file via the grid’s manager.

body_headings()

Render the column headers.

Note, column groups do not have real meaning in the CSV context, so they are left out here.

body_records()

Render all rows from grid records.

Value is obtained for render from each grid column’s render method. To override how a column’s data is rendered specifically for CSV, supply a render_csv method on the column.

build_csv()

Render grid output as CSV and return the contents in an IO stream.

can_render()

Guard method for preventing a renderer from overflowing the target format.

For instance, spreadsheets have limitation in the number of possible rows. A renderer to that format should check that the record count does not exceed that limit.

Returns:

bool: True if the renderer can proceed.

property columns

Cache a set of columns from the grid that will render on this target.

file_name()

Return an output filename based on grid identifier.

A random numeric suffix is added. This is due to Excel’s limitation to having only one workbook open with a given name. Excel will not allow a second file with the same name to open, even if the files are in different paths.

property name

Identifier used to find columns that will render on this target.

render()

Main renderer method returning the output.