User-input widgets

Widgets provide a mechanism for displaying basic HTML inputs to the user and then cleaning the input and passing it into a report.

All widgets accept the following parameters as keyword arguments. Some widgets may accept or require additional arguments, which will be specified in their documentation.

• label: The label the user sees for this widget. Defaults to 'Filter'.
• default: A default value that is initially displayed in the widget. This can be a callable, which will be evaluated lazily when rendering the widget. Defaults to None.
• required: Whether the input can be left blank. If True, a blank value will be added to the errors produced by the report’s clean_user_inputs method. By default, user input is not required, and a blank value will be returned as None.
• extra_class: A string or list of strings that will add extra HTML classes to the rendered widget. Defaults to no extra classes.
• extra_attrs: A dict of attribute names to values. These will be added as attributes on the rendered widget. Defaults to no extra attributes.

Widget types

class blingalytics.widgets.Checkbox(label=None, default=None, required=False, extra_class=None, extra_attrs=None)

Produces a checkbox user input widget. The widget’s default value will be evaluated as checked if it’s truthy and unchecked if it’s falsy.

class blingalytics.widgets.DatePicker(date_format='%m/%d/%Y', end_of_day=False, **kwargs)

Produces a text input to build into a datepicker widget. It accepts one additional optional argument:

• date_format: This is the string passed to the datetime.strptime function to convert the textual user input into a datetime object. Defaults to '%m/%d/%Y'.

Note that this widget is rendered simply as an HTML text input with a class of 'bl_datepicker'. It is left up to you to throw a JavaScript datepicker widget on top of it with jQuery or whatever.

For this widget, the default argument can be:

• A string in the format specified by the date_format option.
• A date or datetime object.
• One of the following special strings: 'today', 'yesterday', 'first_of_month'.
• A callable that evaluates to any of the previous options.

class blingalytics.widgets.Select(choices=[], **kwargs)

Produces an select input widget. This takes one additional optional argument:

• choices: A list of two-tuples representing the select options to display. The first item in each tuple should be the “cleaned” value that will be returned when the user selects this option. The second item should be the label to be displayed to the user for this option. This can also be a callable. Defaults to [], an empty list of choices.

For the default argument for this type of widget, you provide an index into the choices list, similar to how you index into a Python list. For example, if you have three select options, you can default to the second option by passing in default=1. If you want the last selection to be default, you can pass in default=-1.

class blingalytics.widgets.Autocomplete(multiple=False, **kwargs)

Produces a text input for an autocomplete widget. Unlike most widgets, this does not accept the default argument. It takes the following extra argument:

• multiple: Whether the autocomplete should accept just one or multiple values. When set to True, this will add a class of 'bl_multiple' to the widget. Defaults to False.

Note that this widget is rendered simply as an HTML text input with a class of 'bl_autocomplete', and optionally a class of 'bl_multiple'. It is left up to you to throw a JavaScript autocompletion widget on top of it with jQuery or whatever.

The cleaned user input will be coerced to a list of integer IDs.