Columns

Class Reference

• canary.columns.Column
• canary.columns.Text
• canary.columns.Tag
• canary.columns.Link
• canary.columns.ReverseLink
• canary.columns.AdminLink
• canary.columns.BooleanValue
• canary.columns.Date
• canary.columns.EmailLink
• canary.columns.ColumnHeader
• canary.columns.get_column_for_field

class canary.columns.Column(label=None, filters=None, sorts=None, aggregates=None)

Base column class that contains all shared functionality.

__init__(label=None, filters=None, sorts=None, aggregates=None)

Create a Column.

Args:

label: The label used for column display (e.g. the header). filters: A list of filters to apply to the column.

class canary.columns.Text(text=None, default=None, *args, **kwargs)

The most basic column that most people will use.

Extends canary.columns.Column.

__init__(text=None, default=None, *args, **kwargs)

Create a Text column.

Unless overridden, the column is sortable and the Search filter is included by default.

Args:

text: The column or attribute name to use for getting the text to display. default: A default value to display if the text attribute can’t be resolved.

Example:

thinger = Text(‘contact__name’, None, ‘Thinger’, (SearchFilter,))

get_field_name()

Used by filters in order to filter by a Django column name. It is used to build the kwargs passed to QuerySet.filter.

See the filter_queryset methods on included filters to see how this is used.

resolve_text(view, obj, default=None)

Resolve all attributes of the column that are defined in Column.resolve.

Args:

view: The report view. obj: The QuerySet object. default: A default value to use if the text can’t be resolved.

Returns:

A dictionary where the attribute names from Column.resolve are the keys. The values are the resolved values.

render(view, obj)

Render the column value for an object in the QuerySet.

Args:

view: The report view. obj: The QuerySet object.

Returns:

A string containing the resolved text.

class canary.columns.Tag(text=None, autoid=None, autoid_prefix=None, params=None, allow_empty=False, *args, **kwargs)

The next most basic Column, this is the base of all columns that should be displayed as HTML elements.

Extends canary.columns.Text.

__init__(text=None, autoid=None, autoid_prefix=None, params=None, allow_empty=False, *args, **kwargs)

Create a Tag column.

Args:

text: The column name to use for getting the text to display. autoid: The attribute to use for the element id. autoid_prefix: The prefix to use for the element id. params: A dictionary of parameters to include in the element declaration. allow_empty: A boolean indicating whether the element should be rendered even if there is not content.

Example:

a = Tag(‘title__name’, ‘title__id’, ‘report-link’, (‘report-link’,), {‘href’: ‘’}, False, True, None, ‘Thinger’, (SearchFilter,))

render(view, obj)

Renders the filter controls (form, buttons).

Args:

view: The canary view. obj: The QuerySet object.

Returns:

A string of HTML containing the filter controls. By default, this is rendered as part of canary.columns.ColumnHeader.render.

class canary.columns.Link(url=None, *args, **kwargs)

A link column. Displays the value as an anchor tag.

Extends canary.columns.Tag.

__init__(url=None, *args, **kwargs)

Create a Link column.

Args:

url: The attribute to reolve to get the url for a row object.

Example:

thinger = Link(‘title__get_absolute_url’, ‘title__name’, ‘title__id’, ‘report-link-‘, (‘report-link’,), {‘rel’: ‘title__id’}, False, True, None, ‘Thinger’, (SearchFilter,))

render(view, obj)

Renders the filter controls (form, buttons).

Args:

view: The canary view. obj: The QuerySet object.

Returns:

A string of HTML containing the filter controls. By default, this is rendered as part of canary.columns.ColumnHeader.render.

class canary.columns.ReverseLink(text, reverse_path, reverse_args=None, reverse_kwargs=None, *args, **kwargs)

A link column, where the URL is built using Django’s reverse.

Extends canary.columns.Link.

__init__(text, reverse_path, reverse_args=None, reverse_kwargs=None, *args, **kwargs)

Create a ReverseLink column.

The reverse_path, reverse_args and reverse_kwargs arguments are the same as you would use when reversing urls with Django’s reverse utility (found in django.core.urlresolvers).

The big difference is that you can provide attributes that will be resolved from the view or QuerySet object in order to provide (for example) the id or slug of the object being displayed.

Args:

text: The attribute to resolve to use for getting the text to display. reverse_path: The path to be passed to Django’s reverse method.

Example:

thinger = ReverseLink(‘title__name’, ‘titles_title_change’, (‘title__id’,), {}, ‘title__id’, ‘report-admin-link-‘, (‘report-link’,), {‘rel’: ‘title__id’}, False, True, None, ‘Thinger’, (SearchFilter,))

In the example, the URL is built in a way similar to:

title_id = obj.title.id url = reverse(‘titles_title_change’, (title_id, ), {})

render(view, obj)

Renders the filter controls (form, buttons).

Args:

view: The canary view. obj: The QuerySet object.

Returns:

A string of HTML containing the filter controls. By default, this is rendered as part of canary.columns.ColumnHeader.render.

class canary.columns.AdminLink(text, reverse_path, reverse_args=None, reverse_kwargs=None, *args, **kwargs)

A link column, where the URL is built using Django’s reverse for an admin URL.

Extends canary.columns.ReverseLink.

__init__(text, reverse_path, reverse_args=None, reverse_kwargs=None, *args, **kwargs)

Create an AdminLink column.

The reverse_path, reverse_args and reverse_kwargs arguments are the same as you would use when reversing urls with Django’s reverse utility (found in django.core.urlresolvers), only the class prefixes the path with ‘admin:’ for you, as a convenience.

The big difference is that you can provide attributes that will be resolved from the view or QuerySet object in order to provide (for example) the id or slug of the object being displayed.

Args:

text: The attribute to resolve to use for getting the text to display. reverse_path: The path to be passed to Django’s reverse method (prefixed by ‘admin:’).

Example:

thinger = AdminLink(‘title__name’, ‘titles_title_change’, (‘title__id’,), {}, ‘title__id’, ‘report-admin-link-‘, (‘report-link’,), {‘rel’: ‘title__id’}, False, True, None, ‘Thinger’, (SearchFilter,))

In the example, the URL is built in a way similar to:

title_id = obj.title.id url = reverse(‘admin:titles_title_change’, (title_id, ), {})

render(view, obj)

Renders the filter controls (form, buttons).

Args:

view: The canary view. obj: The QuerySet object.

Returns:

A string of HTML containing the filter controls. By default, this is rendered as part of canary.columns.ColumnHeader.render.

class canary.columns.BooleanValue(*args, **kwargs)

A column that gets its value from a Django models.BooleanField.

Extends canary.columns.Tag.

__init__(*args, **kwargs)

Create a BooleanValue column.

Example:

thinger = BooleanValue(label=’Thinger’, (SearchFilter,))

resolve_text(view, obj, default=None)

Overriding to inject the ‘text’ attribute into the dictionary of resolved values.

Args:

view: The report view. obj: The QuerySet object.

Returns:

A dictionary where the attribute names from Column.resolve are the keys. The values are the resolved values.

class canary.columns.Date(text=None, default=None, strftime=None, *args, **kwargs)

A column that gets its value from a Django models.DateField.

Extends canary.columns.Text.

__init__(text=None, default=None, strftime=None, *args, **kwargs)

Create a Date column.

Unless overridden, the column is sortable and the DateRange filter is included by default.

Args:

text: The column name to use for getting the text to display. default: A default value to display if the text attribute can’t be resolved. strftime: A string for date formatting.

Sets:

strftime: A string for date formatting.

Example:

thinger = Text(‘contact__name’, None, ‘%Y/%m/%d’, ‘Thinger’, None, (SearchFilter,))

class canary.columns.EmailLink(mailto=None, *args, **kwargs)

A column that display an e-mail link.

Extends canary.columns.Link.

__init__(mailto=None, *args, **kwargs)

Create an EmailLink column.

Args:

mailto: The attribute to resolve to use for the e-mail address.

resolve_text(view, obj, default=None)

Overriding to inject the ‘mailto’ and ‘url’ attributes into the dictionary of resolved values.

Args:

view: The report view. obj: The QuerySet object.

Returns:

A dictionary where the attribute names from Column.resolve are the keys. The values are the resolved values.

class canary.columns.ColumnHeader(column, view, id=None)

A header column.

__init__(column, view, id=None)

Create a ColumnHeader column.

Args:

column: The canary column. view: The canary report view. id: An attribute to resolve to use to create an HTML id.

render(request)

Render the header column.

Args:

request: The Django request.

Returns:

A string containing HTML for the header column.

static columns.get_column_for_field(field)

Return an approriate canary column for a Django model field.

For example, given a Django models.DateField, this method returns a canary columns.Date object for the field.

This is handy for building a canary report view for a Django model.

Args:

field: A Django model field.

Returns:

A canary column of an appropriate type.