UI¶

A collection of resources for creating a user interface, similar to the Django admin, but for users.

Version: 4.0.0-d

Provides

Compat
Constants
Context Processors
Descriptors
Registry
Views

Install¶

Utilizing the UI system requires several additional setup steps.

You must first decide whether you want to load UI configurations automatically, or manage them manually.

Tip

It is possible to use the built-in UI site with either manually or automatically added configurations. It is also possible to use the built-in UI site with additional manually created sites.

The settings to be added are:

The UI app must be added to use automatic configuration.
An HTML framework must be selected.
Context processors will need to be included in template settings.
The form renderer must be overridden.

Here is an excerpt from an example settings.py:

# settings.py
INSTALLED_APPS = [
    # ...
    'superdjango.assets.apps.DefaultConfig',
    'superdjango.html.frameworks.bootstrap4',
    'superdjango.ui.apps.AutoConfig',
]

TEMPLATES = [
    {
        # ...
        'OPTIONS': {
            'context_processors': [
                # ...
                'superdjango.ui.context_processors.constants',
                'superdjango.ui.context_processors.menu_items',
            ],
        },
    },
]
FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'

The urls.py file is the next thing to be updated.

Include site URLs.
For translation of UI JavaScript files, the JavaScriptCatalog must also be added.

# urls.py
# ...
from django.views.i18n import JavaScriptCatalog
from superdjango.ui import site
# ...

urlpatterns = [
    # ...
    path('jsi18n/assets/', JavaScriptCatalog.as_view(packages=['superdjango.assets']), name='sd-javascript-catalog'),
    # Use apps/ (or whatever) or "" if the site is to serve all other URLs.
    path('apps/', include(site.get_urls())),
]

Then include the catalog URL in your base template:

<!-- this MUST come before form.media -->
<script type="text/javascript" src="{% url 'sd-javascript-catalog' %}"></script>

{% if form %}{{ form.media }}{% endif %}

Constants¶

Constants used within the UI.

Component Reference: Constants

Various constants are used throughout the UI to maintain consistency and reduce the possibility of errors. In some cases, changing the behavior of the UI requires the use of a value represented by a constant. When this is required, you are strongly encouraged to use the appropriate constant rather than a “raw” variable.

Filtering¶

List filters may make use of constants to manage the orientation and style of filters presented to the user.

Lists¶

List constants refer to the “mode” of output and also pagination style.

Locations¶

Location constants refer to an area of the rendered page where something should be displayed. While built-in templates seek to honor a specified location, the output will in some cases still depend upon the theme’s handling of layout.

Menus¶

Standardize menu locations.

Orientations¶

Horizontal or vertical orientation of output elements.

Pagination¶

Various controls over paged results.

Size¶

Various indicators for the relative size of an element rendered on a page.

User¶

USER helps identify the type or user.

ALL: All (or any) user.
CUSTOMER: A paying customer.
NORMAL: A normal user.
ROOT is an administrator or superuser.
STAFF a staff user.

Verbs¶

Standard verbs/actions.

class superdjango.ui.constants.FILTER[source]¶

Bases: object

Control over the style of list filters.

class superdjango.ui.constants.LIST[source]¶

Bases: object

List types (object templates).

class superdjango.ui.constants.LOCATION[source]¶

Bases: object

Location of elements in UI output.

class superdjango.ui.constants.MENU[source]¶

Bases: object

Standardize menu locations.

class superdjango.ui.constants.ORIENTATION[source]¶

Bases: object

Orientation of elements such as filters, detail data, etc. in UI output.

class superdjango.ui.constants.PAGINATION[source]¶

Bases: object

List pagination values.

class superdjango.ui.constants.SIZE[source]¶

Bases: object

Relative size descriptions for UI elements.

class superdjango.ui.constants.USER[source]¶

Bases: object

Identifies a type of user.

class superdjango.ui.constants.VERB[source]¶

Bases: object

A verb is any action within the UI, typically associated with a model. Verb constants are therefore tied to the “base” name of a view; that is, the name of the view before an app label and model name have been applied.

Context Processors¶

Context processors for the UI

Component Reference: Context Processors

superdjango.ui.context_processors.constants(request)[source]¶

Include SuperDjango UI constants to the context.

Parameters: request – The current HTTP request instance.
Return type: dict

superdjango.ui.context_processors.menu_items(request)[source]¶

Add SuperDjango UI menus to the context.

Parameters: request – The current HTTP request instance.
Return type: dict

Note

This context processor assumes you are either using superdjango.ui.apps.AutoConfig or that menus are registered manually with site.register().

Options¶

UI resources, once configured, may be transferred or output as runtime instances.

Component Reference: Options

actions¶

Actions represent activities within a user interface, typically with regard to a model. This module defines the standard actions supported by SuperDjango UI.

class superdjango.ui.options.actions.AjaxCreateAction[source]¶

Bases: superdjango.ui.options.actions.CreateAction

Definition of the AJAX create action.

class superdjango.ui.options.actions.AjaxDeleteAction[source]¶

Bases: superdjango.ui.options.actions.DeleteAction

Definition of the AJAX delete action.

class superdjango.ui.options.actions.AjaxDetailAction[source]¶

Bases: superdjango.ui.options.actions.DetailAction

Definition of the AJAX detail action.

class superdjango.ui.options.actions.AjaxMarkCompleteAction[source]¶

Bases: superdjango.ui.options.actions.MarkCompleteAction

Provides support for CompletedByModel via AJAX.

class superdjango.ui.options.actions.AjaxUpdateAction[source]¶

Bases: superdjango.ui.options.actions.UpdateAction

Definition of the AJAX update action.

class superdjango.ui.options.actions.BaseAction[source]¶

Bases: object

Base class for model “actions”.

as_runtime(request, ui, next_url=None, record=None)[source]¶

Load the action.

Parameters

request – The current HTTP request instance.
ui (ModelUI) – The model UI instance.
next_url (str) – The value of the next_url, especially on form submit.
record – The current model instance, if any.

Return type

Action | None

Returns

If the pattern exists and a URL is available, an Action instance is returned. Otherwise None is returned.

class superdjango.ui.options.actions.BaseBulkAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Base class for bulk actions.

as_runtime(request, ui, next_url=None, queryset=None)[source]¶

Load the bulk action.

Parameters

request – The current HTTP request instance.
ui (ModelUI) – The model UI instance.
next_url (str) – The value of the next_url, especially on form submit.
queryset – The current queryset instance, if any.

Return type

Action | None

Returns

If the pattern exists and a URL is available, an Action instance is returned. Otherwise None is returned.

Note

The queryset parameter is not used by default.

class superdjango.ui.options.actions.BatchChangeAction[source]¶

Bases: superdjango.ui.options.actions.BaseBulkAction

Definition of the batch change action.

class superdjango.ui.options.actions.BulkCompareAction[source]¶

Bases: superdjango.ui.options.actions.BaseBulkAction

Definition of the bulk compare action.

class superdjango.ui.options.actions.BulkDeleteAction[source]¶

Bases: superdjango.ui.options.actions.BaseBulkAction

Definition of the bulk delete action.

class superdjango.ui.options.actions.BulkEditAction[source]¶

Bases: superdjango.ui.options.actions.BaseBulkAction

Definition of the bulk edit action.

class superdjango.ui.options.actions.BulkTrashAction[source]¶

Bases: superdjango.ui.options.actions.BaseBulkAction

Definition of the bulk trash action.

class superdjango.ui.options.actions.CreateAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the create action.

class superdjango.ui.options.actions.DashboardAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the dashboard action.

as_runtime(request, ui, next_url=None, record=None)[source]¶: Override to ignore next URL.

class superdjango.ui.options.actions.DeleteAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the delete action.

class superdjango.ui.options.actions.DetailAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the detail action.

class superdjango.ui.options.actions.DividerAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

A fake action that may be used to add a divider to a model actions menu.

class TodoUI(ui.ModelUI):
    # ...
    list_options = ui.ListOptions(
        # ...
        actions=["create", "dashboard", "divider", "search", "divider"],
    )

as_runtime(request, ui, next_url=None, record=None)[source]¶: The divider action has no pattern or URL.

class superdjango.ui.options.actions.DuplicateAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the duplicate action.

class superdjango.ui.options.actions.ListAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the create action.

as_runtime(request, ui, next_url=None, record=None)[source]¶: List action never responds to specific record instance.

class superdjango.ui.options.actions.MarkArchivedAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Provides support for ArchivedByModel.

as_runtime(request, ui, next_url=None, record=None)[source]¶: A record must exist and be archived.

class superdjango.ui.options.actions.MarkCompleteAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Provides support for CompletedByModel.

as_runtime(request, ui, next_url=None, record=None)[source]¶: A record must exist and be completed.

class superdjango.ui.options.actions.MarkPublishedAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Provides support for PublishedByModel.

as_runtime(request, ui, next_url=None, record=None)[source]¶: A record must exist and be published.

class superdjango.ui.options.actions.MarkResolvedAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Provides support for ReviewedByModel.

as_runtime(request, ui, next_url=None, record=None)[source]¶: A record must exist and be resolved.

class superdjango.ui.options.actions.MarkReviewedAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Provides support for ReviewedByModel.

as_runtime(request, ui, next_url=None, record=None)[source]¶: A record must exist and be unreviewed.

class superdjango.ui.options.actions.SearchAction[source]¶

Bases: superdjango.ui.options.actions.ListAction

Definition of the search action.

class superdjango.ui.options.actions.TrashAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the trash action.

class superdjango.ui.options.actions.UpdateAction[source]¶

Bases: superdjango.ui.options.actions.BaseAction

Definition of the update action.

controls¶

Controls represent both form inputs as well as individual fields within a model for output in lists and detail views.

class superdjango.ui.options.controls.BaseControl(align=None, auto_title=True, default=None, empty_value=None, field_name=None, filter_in_place=False, help_text=None, initial=None, input_prefix=None, input_suffix=None, label=None, max_length=None, on_select=None, read_only=False, remote_field=None, ui=None, widget=None)[source]¶

Bases: object

Base class for describing field/column data.

__init__(align=None, auto_title=True, default=None, empty_value=None, field_name=None, filter_in_place=False, help_text=None, initial=None, input_prefix=None, input_suffix=None, label=None, max_length=None, on_select=None, read_only=False, remote_field=None, ui=None, widget=None)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_datum(record, request, default=None, url=None)[source]¶

Get the value of the field in a class wrapper that carries additional attributes.

Parameters

record – The current model instance.
request – The current HTTP request instance.
default – A default value to display.
url (str) – The URL to which the value should be linked, if any.

Return type

Datum

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_field_kwargs(model_field, request, record=None)[source]¶

Get the keyword arguments used to instantiate a field instance for use in a form.

Return type: dict

get_form_class(model_field, request, record=None)[source]¶

Get the class used for instantiating a field instance for use in a form.

Returns None by default, so child classes should override as needed.

get_form_css()[source]¶

Get the CSS, if any, used for this field in forms.

Return type: StyleSheet | None

get_form_field(model_field, request, record=None, **kwargs)[source]¶

Get the form field instance for a given model field.

Parameters

model_field – The model field instance.
request – The current HTTP request instance.
record – The current model instance.

Returns

A field instance.

kwargs are updated and passed to the formfield() method of the model_field.

This method is called from the ModelUI and performs the following tasks:

get_field_kwargs() is called to populate or update the keyword arguments given to the model_field.formfield() method.
The input prefix and suffix (if present) is added to the form field instance.
If get_widget_attributes() returns a dictionary, the widget attributes of form field instance are updated.

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

get_help_text(request)[source]¶

Get the help text to display.

Parameters: request – The current HTTP request.
Return type: HelpText | None

get_preview_value(record, request, url=None)[source]¶

Get the “preview” of the value. By default this None so templates may test for preview_value and use it if it exists. Child classes may override to provide a preview if appropriate.

Return type: str | None

get_type()[source]¶

Get the type of control. Used for programmatic or template-based identification.

Return type: str

get_value(record, request)[source]¶

Get the current value of the field from the given record.

Parameters

record – The model instance.
request – The current HTTP request instance.

get_widget_attributes(request, record=None)[source]¶

Get widget attributes based on the configuration of the control.

Parameters

record – The model instance.
request – The current HTTP request instance.

Return type

dict() | None

property is_special¶

Indicates this is a special control.

Return type: bool

property label¶

Get the label for the control.

Return type: str

property type¶: An alias for get_type.

class superdjango.ui.options.controls.BooleanControl(css_icon=False, graphical_icon=False, toggle=None, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

__init__(css_icon=False, graphical_icon=False, toggle=None, **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

get_widget_attributes(request, record=None)[source]¶

Get widget attributes based on the configuration of the control.

Parameters

record – The model instance.
request – The current HTTP request instance.

Return type

dict() | None

class superdjango.ui.options.controls.CallableControl(align=None, auto_title=True, default=None, empty_value=None, field_name=None, filter_in_place=False, help_text=None, initial=None, input_prefix=None, input_suffix=None, label=None, max_length=None, on_select=None, read_only=False, remote_field=None, ui=None, widget=None)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

get_value(record, request)[source]¶

Get the current value of the field from the given record.

Parameters

record – The model instance.
request – The current HTTP request instance.

property is_special¶

Indicates this is a special control.

Return type: bool

class superdjango.ui.options.controls.CharControl(counter_enabled=False, truncate=None, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

A control for varchar fields.

__init__(counter_enabled=False, truncate=None, **kwargs)[source]¶

Initialize a char field control.

Parameters

counter_enabled (bool) – Indicates a character/word counter should be displayed.
truncate (int) – The number of characters to which the text should be truncated for the field’s preview value.

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

get_preview_value(record, request, url=None)[source]¶: Get the preview value of the rendered value.

get_widget_attributes(request, record=None)[source]¶

Get widget attributes based on the configuration of the control.

Parameters

record – The model instance.
request – The current HTTP request instance.

Return type

dict() | None

class superdjango.ui.options.controls.ChoiceControl(align=None, auto_title=True, default=None, empty_value=None, field_name=None, filter_in_place=False, help_text=None, initial=None, input_prefix=None, input_suffix=None, label=None, max_length=None, on_select=None, read_only=False, remote_field=None, ui=None, widget=None)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

class superdjango.ui.options.controls.CodeControl(language='python', theme='monokai', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.TextControl

Display a text field as highlighted source code.

__init__(language='python', theme='monokai', **kwargs)[source]¶

Initialize a text field control.

Parameters

collapse (bool) – Indicates whether collapse functionality should be enabled.
collapse_label (str) – The label for showing less text. Default: _("Less"). Not necessarily supported by all frameworks.
counter_enabled (bool) – Indicates a character/word counter should be displayed.
output_format (str) – The output format of the text; OUTPUT_LINE_BREAKS, OUTPUT_PLAIN, OUTPUT_PARAGRAPHS. Default: OUTPUT_PLAIN
preview_lines (int) – The number of lines to display for the field’s preview value.
programming_language (str) – For OUTPUT_CODE, the programming language to use for highlighting.
truncate (int) – For OUTPUT_PLAIN, the number of characters to which the text should be truncated for the field’s preview value.
uncollapse_label (str) – The label for showing less text. Default: _("More"). Not necessarily supported by all frameworks.

get_display_value(record, request, url=None)[source]¶: Get rendered value of the text field.

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

get_preview_value(record, request, url=None)[source]¶: Get the preview of the rendered value.

class superdjango.ui.options.controls.ColorControl(input_format='css', input_type='wcp', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

A control for implementing a color-picker.

__init__(input_format='css', input_type='wcp', **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_widget_attributes(request, record=None)[source]¶

Get widget attributes based on the configuration of the control.

Parameters

record – The model instance.
request – The current HTTP request instance.

Return type

dict() | None

class superdjango.ui.options.controls.DateControl(increment=None, mask='%b %d, %Y', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

__init__(increment=None, mask='%b %d, %Y', **kwargs)[source]¶

Initialize a date control

Parameters

increment (DateIncrement) – The increment options for the date, which uses JavaScript to populate the field based on the value entered in another field.
mask (str) – The strftime() <https://docs.python.org/3.7/library/datetime.html#strftime-strptime-behavior>_ specification which should be used to format dates.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_form_css()[source]¶: Get style for the datepicker.

get_form_js()[source]¶: Get JavaScript for the datepicker.

get_widget_attributes(request, record=None)[source]¶

Get widget attributes based on the configuration of the control.

Parameters

record – The model instance.
request – The current HTTP request instance.

Return type

dict() | None

class superdjango.ui.options.controls.DateTimeControl(date_format='%Y-%m-%d', increment=None, mask='%b %d, %Y %I:%M %p', time_format='%I:%M%p', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

BaseControl over datetime fields.

For forms, this control makes use of Django’s forms.SplitDateTimeWidget to create two separate inputs; one for the date, the other for the time.

Two jQuery plugins are used to provide date and time lookups.

Warning

Changing the date_format and time_format is programmatically possible, but not currently supported by the underlying template or the JavaScript.

__init__(date_format='%Y-%m-%d', increment=None, mask='%b %d, %Y %I:%M %p', time_format='%I:%M%p', **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_field_kwargs(model_field, request, record=None)[source]¶: Override to provide input date and time formats.

get_form_class(model_field, request, record=None)[source]¶: Override to return forms.SplitDateTimeField.

get_form_css()[source]¶: Get style for the datepicker.

get_form_js()[source]¶: Get JavaScript for the datepicker.

get_widget_attributes(request, record=None)[source]¶

Get widget attributes based on the configuration of the control.

Parameters

record – The model instance.
request – The current HTTP request instance.

Return type

dict() | None

class superdjango.ui.options.controls.DecimalControl(align=None, auto_title=True, default=None, empty_value=None, field_name=None, filter_in_place=False, help_text=None, initial=None, input_prefix=None, input_suffix=None, label=None, max_length=None, on_select=None, read_only=False, remote_field=None, ui=None, widget=None)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Control for decimal fields.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.DurationControl(align=None, auto_title=True, default=None, empty_value=None, field_name=None, filter_in_place=False, help_text=None, initial=None, input_prefix=None, input_suffix=None, label=None, max_length=None, on_select=None, read_only=False, remote_field=None, ui=None, widget=None)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Describes a duration field.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.EmailControl(link_enabled=True, obfuscate=False, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Describes an email field.

__init__(link_enabled=True, obfuscate=False, **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.ForeignKeyControl(input_type='select2', limit_choices_to=None, link_enabled=True, link_to='detail', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Describes a foreign key field.

__init__(input_type='select2', limit_choices_to=None, link_enabled=True, link_to='detail', **kwargs)[source]¶

Initialize a control for a foreign key field.

Parameters

input_type (str | None) – The type of input to display; chooser, select2, or None for a standard dropdown menu. Note that chooser and select2 requires additional options on the target model UI.
limit (int) – The query limit to be applied when acquiring the display value.
limit_choices_to (callable | dict) – Used when building the model form, this is a dictionary or callable that may be used to filter the queryset. When a callable is supplied it must accept a request arg and record=None kwarg. It must also return a dictionary or None.
link_enabled (bool) – Indicates links to the should be enabled to the referenced record.
link_to (str) – The verb (view name) to which a link should be included.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_field_kwargs(model_field, request, record=None)[source]¶

Get the keyword arguments used to instantiate a field instance for use in a form.

Return type: dict

get_form_css()[source]¶: Provide support for chooser and select2.

get_form_js()[source]¶: Provide support for chooser and select2.

class superdjango.ui.options.controls.HTMLControl(collapse=False, collapse_label=None, counter_enabled=False, output_format='plain', preview_lines=1, truncate=None, uncollapse_label=None, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.TextControl

Display a text field as HTML.

get_display_value(record, request, url=None)[source]¶: Get rendered value of the text field.

get_preview_value(record, request, url=None)[source]¶: Get the preview of the rendered value.

class superdjango.ui.options.controls.IconControl(library='fontawesome', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.CharControl

Display an icon.

__init__(library='fontawesome', **kwargs)[source]¶

Initialize a char field control.

Parameters

counter_enabled (bool) – Indicates a character/word counter should be displayed.
truncate (int) – The number of characters to which the text should be truncated for the field’s preview value.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_preview_value(record, request, url=None)[source]¶: Get the preview value of the rendered value.

class superdjango.ui.options.controls.ImageControl(height=None, width=None, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

A control for image fields.

__init__(height=None, width=None, **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_datum(record, request, default=None, url=None)[source]¶

Get the value of the field in a class wrapper that carries additional attributes.

Parameters

record – The current model instance.
request – The current HTTP request instance.
default – A default value to display.
url (str) – The URL to which the value should be linked, if any.

Return type

Datum

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.IntegerControl(align=None, auto_title=True, default=None, empty_value=None, field_name=None, filter_in_place=False, help_text=None, initial=None, input_prefix=None, input_suffix=None, label=None, max_length=None, on_select=None, read_only=False, remote_field=None, ui=None, widget=None)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

A control for integer fields.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.ManyToManyControl(criteria=None, input_type=None, limit=3, limit_choices_to=None, limit_continuation='...', link_enabled=True, link_to='detail', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Describes a many to many field.

__init__(criteria=None, input_type=None, limit=3, limit_choices_to=None, limit_continuation='...', link_enabled=True, link_to='detail', **kwargs)[source]¶

Initialize a control for a many to many field.

Parameters

criteria (dict) – Criteria to be applied when acquiring the display value.
input_type (str) – Specify an advanced input type: multiselectjs or select2.
limit (int) – The query limit to be applied when acquiring the display value.
limit_choices_to (callable | dict) – Used when building the model form, this is a dictionary or callable that may be used to filter the queryset. When a callable is supplied it must accept a request arg and record=None kwarg. It must also return a dictionary or None.
limit_continuation (str) – The string to display when the display limit is applied.
link_enabled (bool) – Indicates links to the should be enabled to the referenced record.
link_to (str) – The verb (view name) to which a link should be included.

get_datum(record, request, default=None, url=None)[source]¶: Override to deal with empty queries.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_field_kwargs(model_field, request, record=None)[source]¶

Get the keyword arguments used to instantiate a field instance for use in a form.

Return type: dict

get_form_css()[source]¶

Get the CSS, if any, used for this field in forms.

Return type: StyleSheet | None

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

class superdjango.ui.options.controls.MarkdownControl(**kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.TextControl

Display a text field as Markdown.

__init__(**kwargs)[source]¶

Initialize a text field control.

Parameters

collapse (bool) – Indicates whether collapse functionality should be enabled.
collapse_label (str) – The label for showing less text. Default: _("Less"). Not necessarily supported by all frameworks.
counter_enabled (bool) – Indicates a character/word counter should be displayed.
output_format (str) – The output format of the text; OUTPUT_LINE_BREAKS, OUTPUT_PLAIN, OUTPUT_PARAGRAPHS. Default: OUTPUT_PLAIN
preview_lines (int) – The number of lines to display for the field’s preview value.
programming_language (str) – For OUTPUT_CODE, the programming language to use for highlighting.
truncate (int) – For OUTPUT_PLAIN, the number of characters to which the text should be truncated for the field’s preview value.
uncollapse_label (str) – The label for showing less text. Default: _("More"). Not necessarily supported by all frameworks.

get_display_value(record, request, url=None)[source]¶: Get rendered value of the text field.

get_preview_value(record, request, url=None)[source]¶: Get the preview of the rendered value.

class superdjango.ui.options.controls.NullBooleanControl(css_icon=False, graphical_icon=False, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Describes a null-boolean field.

__init__(css_icon=False, graphical_icon=False, **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.OneToOneControl(link_enabled=False, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Describes a one to one field.

__init__(link_enabled=False, **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.PercentageControl(input_suffix='%', rounding=None, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Represents a percentage number (float or int).

__init__(input_suffix='%', rounding=None, **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_preview_value(record, request, url=None)[source]¶

Get the “preview” of the value. By default this None so templates may test for preview_value and use it if it exists. Child classes may override to provide a preview if appropriate.

Return type: str | None

class superdjango.ui.options.controls.RichTextControl(input_options=None, input_type='summernote', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.HTMLControl

__init__(input_options=None, input_type='summernote', **kwargs)[source]¶

Initialize a text field control.

Parameters

collapse (bool) – Indicates whether collapse functionality should be enabled.
collapse_label (str) – The label for showing less text. Default: _("Less"). Not necessarily supported by all frameworks.
counter_enabled (bool) – Indicates a character/word counter should be displayed.
output_format (str) – The output format of the text; OUTPUT_LINE_BREAKS, OUTPUT_PLAIN, OUTPUT_PARAGRAPHS. Default: OUTPUT_PLAIN
preview_lines (int) – The number of lines to display for the field’s preview value.
programming_language (str) – For OUTPUT_CODE, the programming language to use for highlighting.
truncate (int) – For OUTPUT_PLAIN, the number of characters to which the text should be truncated for the field’s preview value.
uncollapse_label (str) – The label for showing less text. Default: _("More"). Not necessarily supported by all frameworks.

get_form_css()[source]¶

Get the CSS, if any, used for this field in forms.

Return type: StyleSheet | None

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

class superdjango.ui.options.controls.SlugControl(from_field='title', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

__init__(from_field='title', **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

class superdjango.ui.options.controls.TextControl(collapse=False, collapse_label=None, counter_enabled=False, output_format='plain', preview_lines=1, truncate=None, uncollapse_label=None, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Additional control over text fields.

__init__(collapse=False, collapse_label=None, counter_enabled=False, output_format='plain', preview_lines=1, truncate=None, uncollapse_label=None, **kwargs)[source]¶

Initialize a text field control.

Parameters

collapse (bool) – Indicates whether collapse functionality should be enabled.
collapse_label (str) – The label for showing less text. Default: _("Less"). Not necessarily supported by all frameworks.
counter_enabled (bool) – Indicates a character/word counter should be displayed.
output_format (str) – The output format of the text; OUTPUT_LINE_BREAKS, OUTPUT_PLAIN, OUTPUT_PARAGRAPHS. Default: OUTPUT_PLAIN
preview_lines (int) – The number of lines to display for the field’s preview value.
programming_language (str) – For OUTPUT_CODE, the programming language to use for highlighting.
truncate (int) – For OUTPUT_PLAIN, the number of characters to which the text should be truncated for the field’s preview value.
uncollapse_label (str) – The label for showing less text. Default: _("More"). Not necessarily supported by all frameworks.

get_display_value(record, request, url=None)[source]¶: Get rendered value of the text field.

get_form_js()[source]¶

Get the JavaScript, if any, used for this field in forms.

Return type: JavaScript | None

get_preview_value(record, request, url=None)[source]¶: Get the preview of the rendered value.

get_widget_attributes(request, record=None)[source]¶

Get widget attributes based on the configuration of the control.

Parameters

record – The model instance.
request – The current HTTP request instance.

Return type

dict() | None

class superdjango.ui.options.controls.TimeControl(mask='%I:%M %p', time_format='%I:%M%p', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Control over time fields.

For forms, this control makes use of Django’s forms.SplitDateTimeWidget to create two separate inputs; one for the date, the other for the time.

Two jQuery plugins are used to provide date and time lookups.

Warning

Changing the time_format is programmatically possible, but not currently supported by the underlying template or the JavaScript.

__init__(mask='%I:%M %p', time_format='%I:%M%p', **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

get_field_kwargs(model_field, request, record=None)[source]¶

Get the keyword arguments used to instantiate a field instance for use in a form.

Return type: dict

get_form_css()[source]¶: Get style for the datepicker.

get_form_js()[source]¶: Get JavaScript for the datepicker.

class superdjango.ui.options.controls.TimeZoneControl(choices=None, **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.TextControl

__init__(choices=None, **kwargs)[source]¶

Initialize a text field control.

Parameters

collapse (bool) – Indicates whether collapse functionality should be enabled.
collapse_label (str) – The label for showing less text. Default: _("Less"). Not necessarily supported by all frameworks.
counter_enabled (bool) – Indicates a character/word counter should be displayed.
output_format (str) – The output format of the text; OUTPUT_LINE_BREAKS, OUTPUT_PLAIN, OUTPUT_PARAGRAPHS. Default: OUTPUT_PLAIN
preview_lines (int) – The number of lines to display for the field’s preview value.
programming_language (str) – For OUTPUT_CODE, the programming language to use for highlighting.
truncate (int) – For OUTPUT_PLAIN, the number of characters to which the text should be truncated for the field’s preview value.
uncollapse_label (str) – The label for showing less text. Default: _("More"). Not necessarily supported by all frameworks.

get_form_css()[source]¶: Provide support for select2.

get_form_js()[source]¶: Provide support for select2.

class superdjango.ui.options.controls.URLControl(link_enabled=True, link_text=None, target='_blank', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.BaseControl

Describes a URL field.

__init__(link_enabled=True, link_text=None, target='_blank', **kwargs)[source]¶

Initialize a control.

Parameters

align (str) – Request that the output be aligned. Requires supporting CSS.
auto_title (bool) – Automatically convert the label to title format.
default – The default value from the model field instance. A Default instance may also be provided which applies the default post-submit. See ModelUI.save_record(). Note: If the model specifies a default, this is always used.
empty_value (str) – The default value when a display value, value, or field default is not available. This is useful in views that display data that isn’t required and the model field has no default. For example, you might set this to “NA” or “-“.
field_name (str) – The name of the field. NOTE: This is auto-populated by the factory() or when the ModelUI initializes controls.
help_text (str | HelpText | dict) – The help text to display for the field. This will override help text set on the model field. This text may be displayed in forms and list, and detail views. When provided as a dictionary the keys should be from the USER constant and the values should be HelpText instances. See get_help_text().
initial – The initial value to use when acquiring the form field. May be specified as any valid Python type for the field, or as a Default instance.
input_prefix (str) – The prefix to be displayed as part of the beginning of the form input.
input_suffix (str) – The suffix to be displayed as part of the end of the form input.
label (str) – The label for the field. This will override the verbose_name set on the model field.
read_only (bool) – Indicates the value is read only in forms.
remote_field – The value of remote_field on reference field instances.
ui (ModelUI) – The model UI instance utilizing the control.
widget – The form field widget class (or instance) used to display the field in forms.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

class superdjango.ui.options.controls.UserControl(input_type='select2', limit_choices_to=None, link_enabled=True, link_to='detail', **kwargs)[source]¶

Bases: superdjango.ui.options.controls.library.ForeignKeyControl

Extend ForeignKeyControl to provide first/last name when possible.

get_display_value(record, request, url=None)[source]¶

Get the human-friendliest value that may displayed for the field.

Parameters

record – The current model instance.
request – The current HTTP request instance.
url (str) – The URL to which the value should be linked, if any.

Return type

str

superdjango.ui.options.controls.factory(field, ui)[source]¶

Get a control instance for the given field.

Parameters

field (str | BaseType[BaseControl] | BaseType[Field]) – The field for which a control is provided.
ui (ModelUI) – The model UI instance.

Return type

BaseType[BaseControl] | None

The field may be given as a field name (string), field instance, or control instance. If the latter is provided, the namespace of the ui is simply assigned to the control.

filters¶

List filters for UI model lists.

class superdjango.ui.options.filters.AdHocFilter(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Bases: superdjango.ui.options.filters.BaseFilter

Attempts to allow any filed to be filtered.

Warning

This filter is not provided by the factory and must be used manually and intentionally due to the potential performance ramifications.

get_choices(request, ui)[source]¶: Acquire choices from distinct field values.

get_queryset(queryset, request, ui)[source]¶: Provide adhoc filter results.

class superdjango.ui.options.filters.BaseFilter(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Bases: object

Base class for defining filters.

__init__(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Initialize a filter.

Parameters

empty_choice (str) – The label for an empty choice.
field_instance – The field instance to which the filter is applied. This is added dynamically when the UI is initialized.
field_name (str) – The name of the field being filtered. This is added dynamically when the UI is initialized.
keyword (str) – The keyword used to identify the filter in GET. Added dynamically.
label (str) – The label of the filter.
location (str) – The desired location of the filter on the page.
orientation (str) – The orientation of the filter. Influenced by the location.
template (str) – The output template of the filter.

get_choices(request, ui)[source]¶

Get the filter choices. Must be implemented by child classes.

Return type: list[superdjango.ui.runtime.filter.Choice]

get_current_value(request)[source]¶

Get the value of the current choice.

Return type: list[str] | str | None

get_empty_choice()[source]¶

Get the empty/no choice instance.

Return type: superdjango.ui.runtime.filter.Choice

get_keyword()[source]¶

Get the keyword used for filtering.

Return type: str

get_queryset(queryset, request, ui)[source]¶

Get the filtered queryset.

Parameters

queryset (django.db.models.QuerySet) – The existing queryset to be filtered.
request – The current HTTP request instance.
ui (ModelUI) – The current model UI instance.

Return type

django.db.models.QuerySet

get_template(request, ui)[source]¶

Get the template to use for the filter.

Parameters

request – The current request instance.
ui – The current ModelUI instance.

Return type

str

The template is resolved in the following manner:

If a template was given upon instantiation, it is always used.
The location of the filter is used to set the default template.

property is_horizontal¶

Indicates the intended orientation for filter controls is horizontal.

Return type: bool

property is_vertical¶

Indicates the intended orientation for filter controls is vertical.

Return type: bool

property label¶

Get the label for the filter.

Return type: str

load(request, ui)[source]¶

Load the filter, performing any pre-rendering steps required to process the filter or its results.

Parameters

request (HttpRequest) – The current request instance.
ui (superdjango.ui.interfaces.ModelUI) – The model UI instance.

Return type

Filter

Raise

ImproperlyConfigured

class superdjango.ui.options.filters.BooleanFilter(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Bases: superdjango.ui.options.filters.BaseFilter

A filter for boolean fields.

get_choices(request, ui)[source]¶: Handle boolean choices.

get_queryset(queryset, request, ui)[source]¶: Handle boolean filtering

class superdjango.ui.options.filters.ChoiceFilter(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Bases: superdjango.ui.options.filters.BaseFilter

A filter for fields with choices.

get_choices(request, ui)[source]¶

Get the filter choices displayed to the user.

Return type: list[superdjango.ui.runtime.filter.Choice]

get_queryset(queryset, request, ui)[source]¶: Handle choices filtering.

class superdjango.ui.options.filters.DateFilter(choices=None, keyword_null=None, keyword_since=None, keyword_until=None, **kwargs)[source]¶

Bases: superdjango.ui.options.filters.BaseFilter

A filter for dates and datetimes.

__init__(choices=None, keyword_null=None, keyword_since=None, keyword_until=None, **kwargs)[source]¶

Initialize the date filter.

Parameters

choices – Override the standard choices.
keyword_null (str) – The GET keyword to use for “no choice”.
keyword_since (str) – The GET keyword to use for the “since” filter.
keyword_until (str) – The GET keyword to use for the “until” filter.

get_choices(request, ui)[source]¶: Get the choices based on the filter options provided upon instantiation.

get_criteria()[source]¶: Advanced handling of date-related criteria.

get_queryset(queryset, request, ui)[source]¶: Get the queryset based on various date-related conditions.

get_times()[source]¶

Get the date and datetime values used for filtering.

Return type: dict

load(request, ui)[source]¶: Override to deal with special keywords.

class superdjango.ui.options.filters.ForeignKeyFilter(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Bases: superdjango.ui.options.filters.BaseFilter

A filter for foreign keys.

get_choices(request, ui)[source]¶: Get the choices from a queryset.

get_criteria(request, ui)[source]¶

Provide extra criteria for get_choices().

Return type: dict | None

get_lookup()[source]¶: Get the lookup key used to identify the filtered records.

get_queryset(queryset, request, ui)[source]¶: Get the queryset using various conditions.

class superdjango.ui.options.filters.ManyToManyFilter(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Bases: superdjango.ui.options.filters.BaseFilter

A filter for many to many fields.

get_choices(request, ui)[source]¶: Get the choices from a queryset.

get_criteria(request, ui)[source]¶

Provide extra criteria for get_choices().

Return type: dict | None

get_lookup()[source]¶: Get the lookup key used to identify the filtered records.

get_queryset(queryset, request, ui)[source]¶: Get the queryset using various conditions.

class superdjango.ui.options.filters.NullBooleanFilter(empty_choice=None, field_instance=None, field_name=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Bases: superdjango.ui.options.filters.BaseFilter

A filter for null-boolean fields.

get_choices(request, ui)[source]¶: Get choices specific to null-boolean values.

get_queryset(queryset, request, ui)[source]¶: Get the queryset specific to null-boolean values.

superdjango.ui.options.filters.factory(field_instance, filter_class=None, keyword=None, label=None, location='top', orientation=None, template=None)[source]¶

Create a filter for the given field.

Parameters

field_instance (BaseType[django.db.models.Field]) – The field instance to be checked.
filter_class – The filter class to use. If omitted a guess will be made.
keyword (str) – The GET keyword to use for identifying filter value.
label (str) – The label for the filter control. Defaults to the verbose name of the field.
location (str) – The location of the field.
orientation (str) – The orientation of the filter.
template (str) – The path to the filter template.

Return type

BaseType[BaseFilter] | None

superdjango.ui.options.filters.guess_factory(field_instance)[source]¶

Attempt to guess the appropriate filter class based on the field instance.

Parameters: field_instance (BaseType[django.db.models.Field]) – The field instance to be checked.
Return type: class | None

interfaces¶

class superdjango.ui.options.interfaces.BaseModelUI(*args, **kwargs)[source]¶

Bases: object

Base class for model user interfaces. This class provides the commonality between InlineModelUI and ModelUI.

Child classes are expected to:

Set self.meta to the model’s _meta attribute as part of __init__.
Call _init_controls() during __init__.
Initialize a default PermissionPolicy if one is not provided. Example: self.permission_policy = PermissionPolicy(self.meta.app_label, self.model)

__init__(*args, **kwargs)[source]¶: Initialize the UI.

check_lock(request, verb, field=None, record=None)[source]¶

Check whether a record is locked.

Parameters

request – The current request instance.
verb (str) – The verb in question. This method looks only at verbs that delete or update a record.
field (str) – The field name, if any. Not used by default.
record – The model instance. Note that record is an optional parameter (for the sake of runtime operation), it is required to check for locking. It is, however, safe to pass record as None.

Return type

bool | None

Returns

True if the user has permission on a locked record, or False if permission should be denied. None indicates “no opinion”; the model doesn’t support locking or the conditions for granting or denying permission have not been met. See the check_permission() method.

Tip

Override this method if you have implemented custom permissions which grant delete or update on locked records to authorized users.

check_permission(request, verb, field=None, record=None)[source]¶

Use the UI permission_policy to verify that user has permission on a view.

Parameters

request – The current request instance.
verb (str) – The verb in question.
field (str) – The field name, if any.
record – The model instance, if any.

Return type

bool

get_control(name, record=None, request=None)[source]¶

Get the control instance for the named control.

Parameters

name (str) – The name of the field.
record – The model instance. Not used in the default implementation.
request – The current HTTP request instance.

Return type

BaseType[BaseControl] | None

get_display_value(record, as_choice=False, label_field=None)[source]¶

Get the human-friendly representation of a record.

Parameters

record – The record (model instance).
as_choice (bool) – Indicates whether the record should be represented specifically as a lookup choice (if supported).
label_field (str) – The field on the model that may be used to represent the record.

Return type

str

This resolves the display value in the following order:

If label_field exists, the value for the record is returned.
When as_choice is True and get_choice_name() exists on the model, this value is returned.
The value of get_display_name() if this method exists on the model.
The str(record) representation of the model instance.

get_dotted_path()[source]¶

Get the “dotted” path to the model.

Return type: str

get_field_queryset(model_field, request, criteria=None)[source]¶

Get the queryset for a remote (foreign key, many to many, one to one) field.

Parameters

model_field – The field instance on the current model that refers to a remote field.
request – The current request instance.
criteria (dict) – Additional criteria to be used when obtaining the queryset.

Return type

django.db.models.QuerySet

get_form_field(model_field, request, form_options=None, record=None, **kwargs)[source]¶

Get the field instance for a given field on the model.

Parameters

model_field – The model field instance.
request – The current HTTP request instance.
form_options – The form options in use.
record – The current model instance.

Returns

A field instance.

kwargs are updated and passed to the formfield() method of the model_field.

get_help(request)[source]¶

Get help information.

Parameters: request – The current request instance.

get_identifier(record)[source]¶

Get the value of the lookup_field (the record identifier) for a given record.

Parameters: record – The model instance.
Return type: int | str

get_limit_choices_to(control, request, record=None)[source]¶

Get the criteria for limiting choices of a foreign key or many to many field.

Parameters

control (ForeignKeyControl | ManyToManyControl | OneToOneControl) – The control upon which limit_choices_to is defined.
request – The current HTTP request instance.
record – The current model instance.

Return type

dict | None

get_lookup_field()[source]¶

Get the name of the field used to uniquely identify a record.

Return type: str

Note

By default, pk is returned if the lookup_field is not set. See ModelUI for how this is overridden and improved.

get_lookup_key()[source]¶

Get the key used in GET to uniquely identify a model instance.

Return type: str

get_remote_model(field, dotted=False)[source]¶

Get the remote model for the given reference field.

Parameters

field (str | BaseType[models.Field]) – The name or instance of the foreign key, many to many, or one to one field that exists on the UI’s model.
dotted (bool) – Return the dotted path rather the model.

Return type

str | Model | None

get_verbose_name()[source]¶

Get the singular verbose name of the inline model.

Return type: str

get_verbose_name_plural()[source]¶

Get the plural verbose name of the inline model.

Return type: str

is_audit_model()[source]¶

Indicates whether the model has an audit method.

Return type: bool

is_locked_model()[source]¶

Indicates whether the model supports record locking.

Return type: bool

is_owned_model()[source]¶

Indicates whether record ownership is defined for the model.

Return type: bool

is_polymorphic_model()[source]¶

Indicates whether the model implements polymorphic behaviors.

Return type: bool

is_published_model()[source]¶

Indicates whether the model supports publish-type workflows.

Return type: bool

is_resolved_model()[source]¶

Indicates whether the model supports resolution workflows.

Return type: bool

is_reviewed_model()[source]¶

Indicates whether the model supports review-type workflows.

Return type: bool

is_sort_model()[source]¶

Indicates whether the model is sortable.

Return type: bool

is_viewed_model()[source]¶

Indicates whether the model supports viewed by functionality.

Return type: bool

preserve_verbs = ['create', 'delete', 'update']¶: A list of verb names that should preserve filters (and other GET parameters) for the next_url value.

property verbose_name¶: Alias for get_verbose_name().

property verbose_name_plural¶: Alias for get_verbose_name_plural().

class superdjango.ui.options.interfaces.InlineModelUI(parent_model, current_site=None)[source]¶

Bases: superdjango.ui.options.interfaces.BaseModelUI

A UI for handling “inlines”.

__init__(parent_model, current_site=None)[source]¶

Initialize the inline UI.

Parameters

parent_model – The parent model class to which the inline refers.
current_site (SiteUI) – The current SiteUI instance.

get_action(request, verb, record=None)[source]¶

Get an action to be used with an inline model.

Parameters

request – The current HTTP request instance.
verb (str) – The action to be performed.
record – The model instance, if any, to which the action applies.

Return type

Action | None

Note

This requires that a model interface also be defined for the inline model and that it is registered with the same site instance as the parent model.

get_foreign_key()[source]¶

Get the foreign key (field instance) that points to the parent model.

Return type: BaseType[models.Field]
Raise: ValueError
Raises: ValueError if the key could not be identified.

get_form_class(request, record=None)[source]¶

Get the form class to use in the inline formset.

Parameters

request – The current HTTP request instance.
record – The current model instance.

Returns

A form class.

get_formset(request, record=None, **kwargs)[source]¶

Get the formset instance.

Parameters

request – The current HTTP request instance.
record – The current model instance.

Returns

An inline formset instance.

get_formset_class(request, record=None, **kwargs)[source]¶

Get the formset class for the inline records.

Parameters

request – The current HTTP request instance.
record – The current model instance.

Returns

An inline formset class.

kwargs are passed to inlineformset_factory().

get_url(verb, record=None)[source]¶

Get the URL of the inline model.

Parameters

verb (str) – The action to be performed.
record – The model instance, if any, to which the action applies.

Return type

str | None

Note

This requires that a model interface also be defined for the inline model and that it is registered with the same site instance as the parent model.

class superdjango.ui.options.interfaces.ModelUI(site=None)[source]¶

Bases: superdjango.ui.options.interfaces.ModelViewMixin, superdjango.ui.options.interfaces.BaseModelUI

Builds a user interface for a given model.

__init__(site=None)[source]¶

Initial a user interface for a model.

Parameters: site (SiteUI) – The site instance to which this UI is registered.

after_save_record(record, request, verb, form=None)[source]¶

Executed just after a record (and many to many relationships) is saved.

Parameters

record (django.db.models.Model) – The model instance.
request – The current HTTP request instance.
verb – The verb of the view calling the save.
form – The form instance.

before_save_record(record, request, verb, form=None)[source]¶

Executed just before a record is saved.

Parameters

form – The form instance.
record (django.db.models.Model) – The model instance.
request – The current HTTP request instance.
verb – The verb of the view calling the save.

delete_record(record, request)[source]¶

Delete a record.

Parameters

record – The model instance to be deleted.
request – The current HTTP request.

get_action(request, verb, check=False, record=None)[source]¶

Get the action instance for the given verb.

Parameters

request – The current request instance.
verb (str) – The name of action/verb.
check (bool) – Also check permissions for the given verb.
record – The model instance, if any, to which the action applies.

Return type

BaseType[BaseAction] | None

Tip

This method does not check permission by default. In general, when processing records, this should be done prior to getting an action. However, doing both may impact performance as the permission check will run more than once. Use check carefully.

get_base_template(request, verb=None)[source]¶

Get the base template to use for rendering a view.

Parameters

request – The current HTTP instance.
verb (str) – The verb/action of the current view.

Return type

str | None

get_breadcrumbs(request, verb, record=None)[source]¶

Get the breadcrumbs for the current view.

Parameters

request – The current request instance.
verb (str) – The verb of the current view.
record – The current model instance.

Return type

Breadcrumbs

get_bulk_action(request, verb, queryset=None)[source]¶

Get the action instance for the given verb.

Parameters

request – The current request instance.
verb (str) – The name of action/verb.
queryset – The queryset instance, if any, to which the action applies.

Return type

BaseType[BaseBulkAction] | None

get_css(request, verb, queryset=None, record=None)[source]¶

Get adhoc styles to be supplied in the response..

Parameters

request – The current HTTP request instance.
verb (str) – The action/verb of the current view.
queryset (QuerySet) – The current queryset.
record – The current record (model) instance.

Return type

Stylesheet | None

get_fields(form_options, request, record=None)[source]¶

Get the fields to be included in a form.

Parameters

form_options – The options instance.
request – The current request instance.
record – The current model instance.

Return type

list[str]

Returns

A list of field names.

get_fieldsets(form_options, request, record=None)[source]¶

Get the fields to be included in a form.

Parameters

form_options – The options instance.
request – The current request instance.
record – The current model instance.

Return type

list[FieldSet] | None

Returns

A list of fieldset instances or None if no fieldsets have been defined.

get_filter(field, request)[source]¶

Get the filter for a given field.

Parameters

field (str) – The field name.
request – The current request instance. Not used by default.

Returns

The filter instance or None if no filter is defined for the field.

get_form(request, data=None, files=None, record=None, **kwargs)[source]¶

Get the form instance.

Parameters

request – The current request.
data – The data to provide to the form.
files – Submitted files.
record – The record (model instance).

Keyword arguments are passed to the form class.

get_form_class(form_options, request, record=None)[source]¶

Get the form class to use for instantiating a model form.

Parameters

form_options – The UI options instance.
request – The current request instance.
record – The current record (model instance).

Returns

The form class, by default using forms.modelform_factory().

get_form_tabs(form_options, request, record=None)[source]¶

Get the fields to be included in a form with a tabbed interface.

Parameters

form_options – The options instance.
request – The current request instance.
record – The current model instance.

Return type

list[Tab] | None

Returns

A list of tab instances or None if no tabs have been defined.

get_history_callback(request)[source]¶

Get the function used to save model history.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: A callable that accepts the model instance, user, verb, and (optionally) fields, url and verb_display. fields should be a list of :py:class`superdjango.db.history.utils.FieldChange`` instances. If no history_callback is defined, then None is returned.

get_index_url()[source]¶

Get (reverse) the model’s index page.

Return type: str | None

get_inlines(request, verb)[source]¶

Get the inline instances associated with the model.

Parameters

request – The current HTTP request instance.
verb (str) – The current verb being requested.

Return type

list[InlineModelUI] | None

get_js(request, verb, queryset=None, record=None)[source]¶

Get adhoc JavaScript to be supplied in the response..

Parameters

request – The current HTTP request instance.
verb (str) – The action/verb of the current view.
queryset (QuerySet) – The current queryset.
record – The current record (model) instance.

Return type

JavaScript | None

get_lookup_field()[source]¶

Automatically get the name of the lookup field used to uniquely identify a record.

Return type: str

Note

This method is overridden to provide automatic support for fields that guarantee uniqueness; it checks for unique_id, uuid, and slug fields that are unique before returning pk as the default.

get_messages(request, object_or_object_list=None)[source]¶

Get the messages to be displayed to the user.

Parameters

request – The current request instance.
object_or_object_list – The record or queryset of the current view.

Returns

A list of level, message tuples to be displayed to the user.

get_namespace()[source]¶

Get the URL namespace for this UI.

Return type: str | None

Note

This method is overridden to check the site’s namespace.

get_queryset(request, criteria=None)[source]¶

Get the queryset for the model.

Parameters

request – The current HTTP request instance.
criteria (dict) – Additional criteria.

Return type

django.db.models.QuerySet

get_root_url()[source]¶

Get the “root” URL of the UI.

If the UI is associated with a site, an attempt is made to find out what other app this UI may “live under”. Otherwise (or failing that), the index of the UI is returned.

Return type: tuple[str, str]
Returns: The menu label and URL of the parent UI.

get_url_history(request, back=1)[source]¶

Get URL history.

Parameters

request – The current HTTP request instance.
back (int) – The number of steps to go back.

Return type

list(str, str, str | None)

Returns

A list with 3 elements; the URL, title, and optional icon.

See the get_cancel_url() and get_success_url() methods of UIFormMixin` for how this method is called.

Note

History is scanned backward until a URL is found that doesn’t match current request path.

save_form(form, request, verb)[source]¶

Save a record on form submit.

Parameters

form – The form instance.
request – The current HTTP request instance.
verb – The verb of the view calling the save.

Returns

The new or updated record (model instance).

save_history(form, record, request, verb)[source]¶

Save history if a callback is defined.

Parameters

form – The validated form instance (used to support field changes).
record – The current record instance. If this is an update, it should be passed before record.save() is called. See save_record() for an example.
request – The current request.
verb – The verb (action) being taken.

Returns

The history instance received from the callback.

save_record(record, request, verb, form=None)[source]¶

Save a record on submit.

Parameters

record – The model instance.
request – The current HTTP request instance.
verb – The verb of the view calling the save.
form – The form instance.

Returns

The new or updated record (model instance).

save_url_history(request, title)[source]¶

Save URL history to a session variable.

Parameters

request – The current HTTP request instance.
title (str) – A title to save with the current URL.

See the render_to_response() and save_url_history() methods of UIModelView` for how this method is called.

class superdjango.ui.options.interfaces.ModelViewMixin[source]¶

Bases: object

A mixin which defines view classes, options, and related methods.

Note

The extending class must define the model and implement the get_form_field() method.

ajax_auto_complete_class¶: alias of superdjango.ui.views.ajax.UIAjaxAutoCompleteView

ajax_auto_complete_view(request)[source]¶

Get the auto-complete (AJAX) view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_chained_lookup_class¶: alias of superdjango.ui.views.ajax.UIAjaxChainedLookupView

ajax_chained_lookup_view(request)[source]¶

Get the chained lookup (AJAX) view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_chooser_class¶: alias of superdjango.ui.views.ajax.UIAjaxChooserView

ajax_chooser_view(request)[source]¶

Get the chooser (AJAX) view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_create_class¶: alias of superdjango.ui.views.ajax.UIAjaxCreateView

ajax_create_view(request)[source]¶

Get the AJAX create view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_detail_class¶: alias of superdjango.ui.views.ajax.UIAjaxDetailView

ajax_detail_view(request, identifier)[source]¶

Get the AJAX detail view for the model.

Parameters

request (django.http.request.HttpRequest) – The current HTTP request.
identifier (int | str) – The record identifier, e.g. the value of the primary key, UUID, or unique slug.

Returns

The view function.

ajax_drag_and_drop_class¶: alias of superdjango.ui.views.ajax.UIAjaxDragAndDropView

ajax_drag_and_drop_view(request)[source]¶

Get the drag and drop view (AJAX) view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_list_class¶: alias of superdjango.ui.views.ajax.UIAjaxListView

ajax_list_view(request)[source]¶

Get the AJAX list view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_mark_complete_class¶: alias of superdjango.ui.views.ajax.UIAjaxMarkCompleteView

ajax_mark_complete_view(request, identifier)[source]¶

Get the AJAX mark complete view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_reorder_class¶: alias of superdjango.ui.views.ajax.UIAjaxReorderView

ajax_reorder_view(request)[source]¶

Get the reorder view (AJAX) view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_search_class¶: alias of superdjango.ui.views.ajax.UIAjaxSearchView

ajax_search_view(request)[source]¶

Get the AJAX search view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

ajax_update_class¶: alias of superdjango.ui.views.ajax.UIAjaxUpdateView

ajax_update_view(request, identifier)[source]¶

Get the AJAX create view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

batch_change_class¶: alias of superdjango.ui.views.bulk.UIBatchChangeView

batch_change_view(request)[source]¶

Get the batch-change view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

bulk_compare_class¶: alias of superdjango.ui.views.bulk.UIBulkCompareView

bulk_compare_view(request)[source]¶

Get the bulk-compare view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

bulk_delete_class¶: alias of superdjango.ui.views.bulk.UIBulkDeleteView

bulk_delete_view(request)[source]¶

Get the bulk-delete view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

bulk_edit_class¶: alias of superdjango.ui.views.bulk.UIBulkEditView

bulk_edit_view(request)[source]¶

Get the bulk-edit view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

chooser_class¶: alias of superdjango.ui.views.extended.UIChooserView

chooser_view(request)[source]¶

Get the chooser view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

create_class¶: alias of superdjango.ui.views.crud.UICreateView

create_view(request)[source]¶

Get the create view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

dashboard_class¶: alias of superdjango.ui.views.extended.UIDashboardView

dashboard_view(request)[source]¶

Get the dashboard view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

delete_class¶: alias of superdjango.ui.views.crud.UIDeleteView

delete_view(request, identifier)[source]¶

Get the delete view for the model.

Parameters

request (django.http.request.HttpRequest) – The current HTTP request.
identifier (int | str) – The record identifier, e.g. the value of the primary key, UUID, or unique slug.

Returns

The view function.

detail_class¶: alias of superdjango.ui.views.crud.UIDetailView

detail_view(request, identifier)[source]¶

Get the detail view for the model.

Parameters

request (django.http.request.HttpRequest) – The current HTTP request.
identifier (int | str) – The record identifier, e.g. the value of the primary key, UUID, or unique slug.

Returns

The view function.

duplicate_class¶: alias of superdjango.ui.views.extended.UIDuplicateView

duplicate_view(request, identifier)[source]¶

Get the duplicate view for the model.

Parameters

request (django.http.request.HttpRequest) – The current HTTP request.
identifier (int | str) – The record identifier, e.g. the value of the primary key, UUID, or unique slug.

Returns

The view function.

get_namespace()[source]¶

Get the URL namespace for this UI.

Return type: str | None

get_pattern(verb)[source]¶

Get the pattern for the given verb.

Parameters: verb (str) – The name of the verb.
Return type: ModelPattern | None

Important

This patterns dictionary is empty until get_urls() is called.

get_patterns(prefix=None)[source]¶

Get the URL patterns supported by the UI.

Return type: list[ModelPattern]

See get_urls().

Important

A pattern is instantiated only if the corresponding view options have been specified.

get_url(verb, record=None)[source]¶

Get (reverse) the URL for the given verb.

Parameters

verb (str) – The verb (action) representing the requested view.
record – The model instance for record-specific views.

Return type

str | None

get_urls(prefix=None)[source]¶

Get the URLs associated with the model.

Return type: list

history_class¶: alias of superdjango.ui.views.extended.UIHistoryView

history_view(request, identifier)[source]¶: Get the history view for the model.

intermediate_choice_class¶: alias of superdjango.ui.views.extended.UIIntermediateChoiceView

intermediate_form_class¶: alias of superdjango.ui.views.extended.UIIntermediateFormView

list_class¶: alias of superdjango.ui.views.crud.UIListView

list_view(request)[source]¶

Get the list view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

mark_archived_class¶: alias of superdjango.ui.views.extended.UIMarkArchivedRedirect

mark_archived_redirect_view(request, identifier)[source]¶: Provide the view for marking a record as archived.

mark_complete_class¶: alias of superdjango.ui.views.extended.UIMarkCompleteRedirect

mark_complete_redirect_view(request, identifier)[source]¶: Provide the view for marking a record as completed.

mark_published_class¶: alias of superdjango.ui.views.extended.UIMarkPublishedRedirect

mark_published_redirect_view(request, identifier)[source]¶: Provide the view for marking a record as published.

mark_resolved_class¶: alias of superdjango.ui.views.extended.UIMarkResolvedRedirect

mark_resolved_redirect_view(request, identifier)[source]¶: Provide the view for marking a record as reviewed.

mark_reviewed_class¶: alias of superdjango.ui.views.extended.UIMarkReviewedRedirect

mark_reviewed_redirect_view(request, identifier)[source]¶: Provide the view for marking a record as reviewed.

save_as_class¶: alias of superdjango.ui.views.extended.UISaveAsView

save_as_view(request, identifier)[source]¶

Get the save as view for the model.

Parameters

request (django.http.request.HttpRequest) – The current HTTP request.
identifier (int | str) – The record identifier, e.g. the value of the primary key, UUID, or unique slug.

Returns

The view function.

search_class¶: alias of superdjango.ui.views.extended.UISearchView

search_view(request)[source]¶

Get the search view for the model.

Parameters: request (django.http.request.HttpRequest) – The current HTTP request.
Returns: The view function.

update_class¶: alias of superdjango.ui.views.crud.UIUpdateView

update_view(request, identifier)[source]¶

Get the update view for the model.

Parameters

request (django.http.request.HttpRequest) – The current HTTP request.
identifier (int | str) – The record identifier, e.g. the value of the primary key, UUID, or unique slug.

Returns

The view function.

class superdjango.ui.options.interfaces.SiteUI[source]¶

Bases: object

A site is a collection of menus.

__init__()[source]¶: Initialize the models and registry for the site.

check_permission(model, request, verb, field=None, record=None)[source]¶

Check permission on a model that has been registered with the site.

Parameters

model (class | str) – The model in question. This may be a model class or a dotted path of app_label.ModelName.
request – The current request instance.
verb (str) – The verb in question.
field (str) – The field name, if any.
record – The model instance, if any.

Return type

bool

Raise

ValueError

get_base_template(request, verb=None)[source]¶

Get the base template to use for rendering a view.

Parameters

request – The current HTTP instance.
verb (str) – The verb/action of the current view.

Return type

str | None

get_menus(request)[source]¶

Get the site’s menus.

Parameters: request – The current request instance.
Return type: dict
Returns: A dictionary where the keys are the menu locations and values are a list of menu instances.

get_model_ui(dotted)[source]¶

Get the model UI instance for the given dotted path.

Parameters: dotted (str) – The app_label.model_name.
Return type: ModelUI | None

get_url(dotted, verb, record=None)[source]¶

Get the URL from a model registered with the site.

Parameters

dotted (str) – The app_label.model_name.
verb (str) – The action to be performed.
record – The model instance, if any, to which the action applies.

Return type

str | None

get_urls()[source]¶

Get the URLs for the site’s apps.

Return type: list

is_registered_model(dotted)[source]¶

Indicates whether the given model has a UI registered with the site.

Parameters: dotted (str) – The app_label.model_name.
Return type: bool

register(menu)[source]¶

Register a menu with the site.

Parameters: menu (BaseType[superdjango.ui.menus.library.Menu]) – The menu to be registered.
Raise: ModelAlreadyRegistered, ViewAlreadyExists

lists¶

List options are used to configure the display of records as tables, cards, and so on.

menus¶

class superdjango.ui.options.menus.Menu(site=None)[source]¶

Bases: object

A menu which contains one or more menu items.

This option class is meant to be extended and registered:

from superdjango import ui

class MyMenu(ui.Menu):
    items = [
        # ...
    ]

ui.site.register(MyMenu)

__init__(site=None)[source]¶

Initialize the menu.

Parameters: site (superdjango.ui.options.interfaces.SiteUI) – The current site instance.

as_runtime(request)[source]¶

Export the menu as a runtime instance.

Parameters: request – The current HTTP request instance.
Return type: RuntimeMenu | RuntimeItem | None

check_permission(request)[source]¶

Determine whether the current user has access to the menu as a whole.

Parameters: request – The current HTTP request instance.
Return type: bool

Note

By default, True is always returned. You may extend this class and override the method to impelment your own permission check.

flat = False¶: Indicates menu items should be displayed in sequence rather than nested. Templates must provide support.

get_items(request)[source]¶

Get the items in the menu.

Parameters: request – The current HTTP request instance.
Return type: list[Menu | MenuItem | MenuSeparator | MenuView]

get_urls()[source]¶

Get the URLs of the items contained within the menu.

Return type: list()

icon = None¶: The menu icon to display with the menu. Templates must provide support.

property is_separator¶

Indicates this menu is not a separator.

Return type: bool

items = []¶: A list of items to be included in the menu; a MenuItem, MenuSeparator, or ModelUI.

kwargs = {}¶: Additional keyword arguments to be passed to the runtime menu instance.

label = None¶: The label of the menu. Templates must provide support.

location = 'main_menu'¶: The location of the menu.

name = None¶: A unique name for the menu. If omitted, a name will be automatically assigned.

prefix = None¶: The URL prefix of items in the menu.

root = None¶: the item which serves as the root for all other menu items.

sort_order = None¶: The order in which the menu appears in the given location. If omitted, an order is automatically applied, but you may wish to set this explicitly for the best results.

class superdjango.ui.options.menus.MenuItem(label, args=None, authenticated=True, icon=None, kwargs=None, pattern_name=None, permissions=None, prefix=None, sort_order=None, url=None)[source]¶

Bases: object

An individual menu item.

This class is meant to be instantiated as part of a menus items:

from superdjango import ui

class MyMenu(ui.Menu):
    items = [
        ui.MenuItem(_("Help"), icon="fas fa-life-ring", url="/help/"),
        ui.MenuItem(_("Log In"), authenticated=None, url="/login/"),
        ui.MenuItem(_("Log Out"), authenticated=True, icon="fas fa-sign-out-alt", url="/logout/"),
    ]
    location = ui.MENU.SECONDARY

__init__(label, args=None, authenticated=True, icon=None, kwargs=None, pattern_name=None, permissions=None, prefix=None, sort_order=None, url=None)[source]¶

Define a menu item.

Parameters

label (str) – The label of the item.
args (list) – Pattern arguments. See get_url().
authenticated (bool | None) – Indicates whether a user must be authenticated to see the item. Setting this to None indicates the menu is not available when the user is authenticated.
icon (str) – The FontAwesome icon to use for the menu item.
kwargs – Pattern keyword arguments. See get_url().
pattern_name (str) – The pattern name to reverse for the item. See get_url().
permissions (list[str]) – The as list of permissions required to see the item in the form of app_label.permission_name. Permissions are checked after authentication.
prefix (str) – The URL prefix.
url (str) – A partial or absolute URL. If prefix is used, the URL should be provided without the prefix.

as_runtime(request)[source]¶

Export the item as a runtime menu item.

Parameters: request – The current HTTP request instance.
Return type: RuntimeItem

check_permission(request)[source]¶

Check permissions.

Parameters: request – The current HTTP request instance.
Return type: bool

get_url()[source]¶

Get the URL for the item.

Return type: str
Raise: ImproperlyConfigured

property is_separator¶

Indicates this item is not a separator.

Return type: bool

property name¶

Alias for pattern_name.

Return type: str

property url¶: Alias for get_url().

class superdjango.ui.options.menus.MenuSeparator(sort_order=None)[source]¶

Bases: object

A separator for menu items.

This class is meant to be instantiated as part of a menus items:

from superdjango import ui

class MyMenu(ui.Menu):
    items = [
        # ...
        ui.MenuSeparator(),
        # ...
    ]

__init__(sort_order=None)[source]¶

Initialize the separator.

Parameters: sort_order (int) – The order in which the separator appears.

as_runtime(request)[source]¶: Just returns self. No additional work required.

property is_separator¶

Indicates this item is a separator.

Return type: bool

class superdjango.ui.options.menus.MenuView(view, icon=None, label=None, menu_enabled=True, sort_order=None)[source]¶

Bases: object

A view that is incorporated into the menu system.

__init__(view, icon=None, label=None, menu_enabled=True, sort_order=None)[source]¶

Initialize the menu view.

Parameters

view – The view class.
icon (str) – The icon for the view.
label (str) – The label of the the menu item.
menu_enabled (bool) – Indicates the view should be included in the menu. Setting this to False can be useful to initialize the view without actually including it in a menu.
sort_order (int) – The order in which the view should appear in menus.

as_runtime(request)[source]¶: Export the view as a runtime menu item.

get_path(prefix=None)[source]¶: Get the URL path.

property is_separator¶

Indicates this item is not a separator.

Return type: bool

property url¶: Alias for get_url().

panels¶

class superdjango.ui.options.panels.BasePanel[source]¶

Bases: object

Base class for panel implementations.

__init__()[source]¶: Initialize the panel. Simply sets the request and ui to None for later use.

as_runtime(request, ui)[source]¶

Load the panel for use in output.

Parameters

request – The current HTTP request instance.
ui (ModelUI) – The current model UI instance.

Return type

Panel

Note

This method sets the request and ui attributes for use in other methods.

get_content()[source]¶

Get the content (output) of the panel.

Return type: str

Note

Content is marked safe.

get_context()[source]¶

Get the context to be used for rendering the panel template.

Return type: dict

Note

By default, this simply returns get_kwargs(), but child classes may override to include additional context variables.

get_kwargs()[source]¶

Get the keyword arguments to be passed to the the Panel instance.

Return type: dict

get_template()[source]¶

Get the template to use for rendering the panel.

Return type: str
Raise: IMustBeMissingSomething

get_url()[source]¶

Get the URL for linking to related pages or content.

Return type: str | None

load(request, ui)[source]¶

Load the panel for use in output.

Parameters

request – The current HTTP request instance.
ui (ModelUI) – The current model UI instance.

Return type

Panel

Note

This method sets the request and ui attributes for use in other methods.

class superdjango.ui.options.panels.BigNumberPanel[source]¶

Bases: superdjango.ui.options.panels.BasePanel

A panel that prominently displays a numeric value.

get_context()[source]¶: Add number and style to the context.

get_number()[source]¶

Get the number to be displayed.

Return type: decimal | float | int

Note

Child classes must implement this method.

class superdjango.ui.options.panels.ImagePanel[source]¶

Bases: superdjango.ui.options.panels.BasePanel

A panel that displays an image.

get_context()[source]¶: Add image and style to the context.

get_image()[source]¶

Get the URL of the image to be displayed.

Return type: str

class superdjango.ui.options.panels.TabularPanel[source]¶

Bases: superdjango.ui.options.panels.BasePanel

A panel for displaying limited tabular data.

get_context()[source]¶: Add table to the context.

get_table()[source]¶: Get the table instance to be displayed.

Note

Child classes must implement. The table instance is expected to have a columns attribute that contains a column instance with a label attribute, and a rows attribute that includes a data list attribute that contains the data to be displayed.

utils¶

class superdjango.ui.options.utils.Actions(*items, enabled=True, label=None, location='default')[source]¶

Bases: object

A collection of actions used to output buttons, links, or context menus.

This class may be used instead of a list of action names.

__init__(*items, enabled=True, label=None, location='default')[source]¶

Initialize the instance.

Parameters

items – A list of action (verb) names to be included in the set. These may also be supplied as instances that extend the BaseAction class.
enabled (bool) – Indicates the actions are available to users. This may be toggled programmatically.
label (str) – The label for this group of actions. Defaults to _("Actions") but may be disabled by passing an empty string.
location (str) – The desired location of the actions.

class superdjango.ui.options.utils.Aggregate(field, callback=None, criteria=None, formatter=None, label=None)[source]¶

Bases: object

Specify options for loading aggregate data.

__init__(field, callback=None, criteria=None, formatter=None, label=None)[source]¶

Initialize an aggregate option.

Parameters

field (str) – The name of the field to be aggregated.
callback (callable | str) – The callback to use for aggregation. This may be a built-in name (str) or a callable. See notes.
criteria (dict) – Optional criteria for filtering aggregate data.
formatter (callable) – A callable that may be used to format the aggregate result. If should accept a single parameter, which is the return value of query, and return a str. Note that the value may be None. If omitted, a default formatter is applied.
label (str) – Optional label for the aggregated data.

The built-in callbacks are:

avg
count
max
min
stddev
sum
variance

When providing a callback, it should exhibit the following signature:

callback(field, queryset, request, ui, criteria=None)

load(queryset, request, ui)[source]¶

Load the aggregate data. Sets the value attribute of the Aggregate instance.

Parameters

queryset (QuerySet) – The queryset to use for aggregation.
request – The current HTTP request instance. This is not used by default.
ui (ModelUI) – The current model UI instance.

Return type

bool

Returns

True if a value was acquired. If False, check the logs.

class superdjango.ui.options.utils.BaseUtil(**kwargs)[source]¶

Bases: object

Base for utility classes, the primary purpose of which is to capture any additional kwargs and assign them to the attributes attribute. These may be

flattened in templates to assign attributes to the element, or
used programmatically using the getter.

__init__(**kwargs)[source]¶: Initialize dynamic attributes.

class superdjango.ui.options.utils.BlankFooter[source]¶

Bases: object

A blank footer that simulates the DBC for Aggregate. See FooterRow.

load(queryset, request, ui)[source]¶: Does nothing. Maintains the DBC for Aggregate.

class superdjango.ui.options.utils.ChainedLookup(source_field, target_field, empty_value=None, pattern_name=None)[source]¶

Bases: object

Connects the possible values of a reference field to the value of another field.

__init__(source_field, target_field, empty_value=None, pattern_name=None)[source]¶

Initialize the chained lookup.

Parameters

source_field (str) – The field name whose value is used to filter the possible values of the target field.
target_field (str) – The field name whose values depend upon the selected value of the source field.
empty_value (str) – The value to display when no source_field value is selected. Defaults to “Select a <source_field>”
pattern_name (str) – The pattern name of the UIAjaxChainedLookupView (or compatible view) that is used for acquiring the target_field values. In most cases, automatic resolution does not require this parameter to be specified.

get_form_js(ui, record=None)[source]¶

Get the JavaScript to be used in the form.

Parameters

ui (ModelUI) – The current model UI instance that is utilizing the lookup.
record – The record (model instance), if any.

Return type

JavaScript | None

get_url(ui)[source]¶

Get the AJAX URL that provides the lookup.

Parameters: ui (ModelUI) – The current model UI instance that is utilizing the lookup.
Return type: str | None

class superdjango.ui.options.utils.Choice(label, value, abbr=None, description=None, icon=None, is_enabled=True, url=None, **kwargs)[source]¶

Bases: superdjango.ui.options.utils.BaseUtil

A user choice.

__init__(label, value, abbr=None, description=None, icon=None, is_enabled=True, url=None, **kwargs)[source]¶: Initialize dynamic attributes.

property url¶

Get the encoded URL.

Return type: str

class superdjango.ui.options.utils.ContextMenu(*items, base_url=None, selector='.ui-record')[source]¶

Bases: object

Actions to be displayed with a context (right-click) menu for a record.

__init__(*items, base_url=None, selector='.ui-record')[source]¶

Initialize a context menu.

Parameters

items – The actions (verbs) to be included in the menu. These must be converted into an Action instance prior to template rendering. See the get_context_menu() of t he UIListView for an example.
base_url (str) – The base URL of the actions. Defaults to the list view of the model.
selector (str) – The CSS selector that identifiers record. The default is used across all UI list types, so don’t override it unless you are prepared for the additional work involved.

get_css()[source]¶

Get the CSS for the context menu.

Return type: StyleSheet

get_js()[source]¶

Get the JavaScript for the context menu.

Return type: JavaScript

class superdjango.ui.options.utils.DateIncrement(source_field, always=False, days=None, target_field=None)[source]¶

Bases: object

Automatically increment a date field based upon the value entered in another date field.

from superdjango import ui

class ProjectUI(ui.ModelUI):
    # ...
    controls = {
        'end_date': ui.controls.DateControl(increment=ui.DateIncrement(source_field="start_date", days=60)),
    }
    # ...

JavaScript is produced to perform the increment as soon as the source field is changed.

__init__(source_field, always=False, days=None, target_field=None)[source]¶

Initialize an increment.

Parameters

source_field (str) – The field whose value is used to set the value of the target field.
always (bool) – Indicates the target field should always be updated, even if it already has a value.
days (int) – The number of days by which the source field value should be incremented. Default: 30.
target_field (str) – The target field to be updated. This defaults to the field name to which the DateIncrement is attached.

property source_selector¶

The jQuery selector for the source field.

Return type: str

property target_selector¶

The jQuery selector for the target field.

Return type: str

class superdjango.ui.options.utils.Default(callback=None, takes_request=False, value=None)[source]¶

Bases: object

Programmatically define a default value.

__init__(callback=None, takes_request=False, value=None)[source]¶

Initialize the default.

Parameters

callback – A function used to acquire the value.
takes_request (bool) – Indicates the callback utilizes the current request.
value – The default value.

The callback signature should be callback(record=None). However, when takes_request is True, the callback signature should be: callback(request, record=None)

Additionally, the callback is expected to return the correct Python data type for the intended use of the default value.

get(request, record=None)[source]¶

Get the default value.

Parameters

request – The current HTTP request instance.
record – The record (model instance), if any, with which the default is associated.

class superdjango.ui.options.utils.FieldGroup(*fields, label=None, size=None)[source]¶

Bases: object

A grouping of fields.

__init__(*fields, label=None, size=None)[source]¶

Initialize a field group.

Parameters

fields – List of field names to include in the group.
label (str) – A label for the group.
size (int) – The size of the group’s columns.

class superdjango.ui.options.utils.Fieldset(*fields, classes=None, description=None, legend=None, **kwargs)[source]¶

Bases: superdjango.ui.options.utils.BaseUtil

A field set within a form.

__init__(*fields, classes=None, description=None, legend=None, **kwargs)[source]¶

Initialize a fieldset.

Parameters

fields – A list of field names to include in the fieldset.
classes (str) – The CSS classes to be applied to the fieldset element.
description (str) – The description appears before fields.
legend (str) – The fieldset legend.

class superdjango.ui.options.utils.Filtering(*fields, default=None, location='default', orientation=None, template=None)[source]¶

Bases: object

A utility class for holding filters and filter options.

__init__(*fields, default=None, location='default', orientation=None, template=None)[source]¶

Initialize filtering options for a list.

Parameters

fields – A list of field names to be included as filters.
default (dict) – Establish the default filtering of the list. The criteria included here need not be related to filter fields. Any request made to the list that does not include filtering will use this criteria instead.
location (str) – The location of the filter on the page.
orientation (str) – The orientation of the filter; ORIENTATION.HORIZONTAL or ORIENTATION.VERTICAL. By default, the orientation is selected based on the location.
template (str) – The template to use for the filters. By default, the template is based upon the location and orientation of the filters.

class superdjango.ui.options.utils.FooterRow(*data, label=None)[source]¶

Bases: object

A collection of footer data to be displayed with a table.

from superdjango import ui

class TodoUI(ui.ModelUI):
    # ...
    list_options = ui.ListOptions(
        ui.lists.Table(
            "title",
            "priority",
            "stage",
            "estimated_cost",
            "estimated_hours",
            "is_complete",
            footers=[
                ui.lists.FooterRow(
                    ui.lists.BlankFooter(),
                    ui.lists.BlankFooter(),
                    ui.lists.BlankFooter(),
                    ui.Aggregate("estimated_cost", callback="sum"),
                    ui.Aggregate("estimated_hours", callback="sum"),
                    ui.lists.BlankFooter(),
                    label=_("Totals")
                ),
                ui.lists.FooterRow(
                    ui.lists.BlankFooter(),
                    ui.lists.BlankFooter(),
                    ui.lists.BlankFooter(),
                    ui.Aggregate("estimated_cost", callback="avg"),
                    ui.Aggregate("estimated_hours", callback="avg"),
                    ui.lists.BlankFooter(),
                    label=_("Average")
                ),
            ],
            link_field="title"
        )
    )
    # ...

__init__(*data, label=None)[source]¶

Initialize the footer row.

Parameters

data – A list of :py:class`Aggregate` instances.
label (str) – Optional label for the row.

class superdjango.ui.options.utils.FormStep(*fields, callback=None, description=None, form_class=None, label=None)[source]¶

Bases: object

Define a step within multi-step form, e.g. a form wizard.

__init__(*fields, callback=None, description=None, form_class=None, label=None)[source]¶: Initialize self. See help(type(self)) for accurate signature.

class superdjango.ui.options.utils.Help(articles=None, icon='fas fa-life-ring', include_titles=True, path=None, snippets=None, terms=None, title=None)[source]¶

Bases: object

Encapsulate help resources.

__init__(articles=None, icon='fas fa-life-ring', include_titles=True, path=None, snippets=None, terms=None, title=None)[source]¶: Initialize self. See help(type(self)) for accurate signature.

property articles¶

Get the article instances included in the help.

Return type: list[superdjango.contrib.support.library.Article]

class superdjango.ui.options.utils.HelpText(form_text, detail_text=None, list_text=None)[source]¶

Bases: object

Manage help text programmatically.

from django.utils.translation import ugettext_lazy as _
from superdjango import ui
from .models import MemberApplication

class MemberApplicationUI(ui.ModelUI):
    model = MemberApplication

    controls = {
        'name': ui.controls.CharControl(
            help_text={
                ui.USER.NORMAL: ui.HelpText(_("Please enter your full name.")),
                ui.USER.ROOT: ui.HelpText(_("The user's full name.")),
            }
        ),
    }

__init__(form_text, detail_text=None, list_text=None)[source]¶

Initialize help text.

Parameters

form_text (str) – The text to display with form elements. Used for all other text when no other options are provided.
list_text (str) – The text to use for list display.
detail_text (str) – The text to use for detail display.

property column_text¶: An alias for list_text.

property help_text¶: An alias for form_text.

class superdjango.ui.options.utils.Limit(increments=None, label=None, location='default', value=25, widget='links')[source]¶

Bases: object

A utility for capturing options for results per page. Used by Pagination, but may also be used to exercise programmatic control over limit and limit display.

__init__(increments=None, label=None, location='default', value=25, widget='links')[source]¶

Initialize pagination limit configuration.

Parameters

increments (list[int]) – A list of integers the user may select for results per page. Default: [10, 25, 50, 100]
label (str) – The label for the widget. Default: _("Results Per Page"). Different widgets use the label in different ways.
location (str) – The desired location of the widget.
value (int) – The initial results per page.
widget (str | None) – The widget to use that allows the user to change the limit. Set to Limit.WIDGET_DISABLED (None) to disallow this feature.

class superdjango.ui.options.utils.ListTypes(*items, label=None, location='default')[source]¶

Bases: object

Manage list type options.

__init__(*items, label=None, location='default')[source]¶

Initialize list type options.

Parameters

items – A list of instances that extend superdjango.ui.options.lists.BaseList.
label (str) – The label for the list type switcher. Default: _("View As").
location (str) – The desired location of the list type switcher.

class superdjango.ui.options.utils.Ordering(direction='asc', fields=None, initial_field=None)[source]¶

Bases: object

Encapsulates ordering options for a list.

__init__(direction='asc', fields=None, initial_field=None)[source]¶

Initialize ordering options.

Parameters

direction (str) – The default ordering direction; asc or desc.
fields (list[str]) – A list of field names that may be used for ordering a list.
initial_field (str) – The name of the field to by which ordering should be initially provided.

get_keyword(field)[source]¶

Get the GET keyword and value for the field.

Return type: str

class superdjango.ui.options.utils.Pagination(enabled=True, invalid_page_message=None, keyword='page', limit=25, location='default', page_unknown_message=None, show_all_enabled=False, show_all_limit=200, style='previous-next')[source]¶

Bases: object

Encapsulates pagination options for a list.

__init__(enabled=True, invalid_page_message=None, keyword='page', limit=25, location='default', page_unknown_message=None, show_all_enabled=False, show_all_limit=200, style='previous-next')[source]¶

Initialize pagination options.

Parameters

enabled (bool) – Indicates pagination is enabled.
invalid_page_message (str) – The message to display when an invalid (typically non-existent) page number has been requested. Default: _("Invalid page (%(number)s): %(error)s")
keyword (str) – The GET keyword used to identify the page number in the URL.
limit (Limit | int) – The results to display per page.
location (str) – The desired location of the pagination controls.
page_unknown_message (str) – The message to display when the page number cannot be determined. Default: _("The page number could not be determined.")
show_all_enabled (bool) – Indicates the “show all” link should be displayed.
show_all_limit (int) – The results to display per page when show_all_enabled is True.
style (str) – The style of pagination controls.

property limit¶

Get the number of records to display per page.

Return type: int

class superdjango.ui.options.utils.Tab(*fields, classes=None, description=None, icon=None, identifier=None, label=None, **kwargs)[source]¶

Bases: superdjango.ui.options.utils.BaseUtil

Create tabbed interface for controls.

__init__(*fields, classes=None, description=None, icon=None, identifier=None, label=None, **kwargs)[source]¶

Initialize a tab interface.

Parameters

fields – A list of field names to include in the tab.
classes (str) – The CSS classes to be applied to the fieldset element.
description (str) – The description appears before fields.
icon (str) – An icon to display with the tab.
identifier (str) – The unique identifier for the tab. If omitted, it is derived from the label.
label (str) – The label of the tab.

Tip

You may supply an class extending InlineModelUI as the only field. This will cause the inline formset to display as tabbed content. The identifier is used to match against the formset’s prefix, so you may need to specify this manually if the formset is not displayed.

class superdjango.ui.options.utils.Toggle(target_field, control_field=None, default_value=None, inverse=False, required=None, visible=None)[source]¶

Bases: object

Toggle the attributes of another field based on the value of a checkbox.

For example, imagine a to-do has a notes field that may be populated when is complete is checked:

class TodoUI(ui.ModelUI):
    # ...
    controls = {
        'is_complete': ui.controls.BooleanControl(toggle=ui.Toggle("close_notes", visible=True)),
    }
    # ...

__init__(target_field, control_field=None, default_value=None, inverse=False, required=None, visible=None)[source]¶

Initialize a toggle.

Parameters

target_field – The field that is controlled by the toggle.
control_field (str) – The name of the checkbox field that controls the toggle. This is assigned automatically when using ModelUI.
default_value – Set a default value on the target field.
inverse (bool) – For checkboxes that are checked by default, toggle target fields when the box is unchecked.
required (bool) – Indicates the target field should be required when the checkbox is checked.
visible (bool | str) – Indicates the target field should be displayed when the checkbox is checked. This attribute may also be given as a string; either “disabled” or “readonly”. For the difference between these two, see: https://stackoverflow.com/a/7730719/241720

views¶

Runtime¶

UI resources, once configured, may be transferred or output as runtime instances.

Component Reference: Runtime

actions¶

class superdjango.ui.runtime.actions.Action(label, url, verb, icon=None, is_ajax=None, is_divider=None, is_primary=False, modal=False, target=None)[source]¶

Bases: object

Represents a specific instance of an action definition.

__init__(label, url, verb, icon=None, is_ajax=None, is_divider=None, is_primary=False, modal=False, target=None)[source]¶

Initialize an action.

Parameters

label (str) – The label of the action to be displayed to users.
url (str) – The URL of the action.
verb (str) – The verb which the action represents.
icon (str) – The icon to use for the action.
is_ajax (bool) – Indicates the action is handled via an AJAX call.
is_divider (bool) – Indicates the action is a divider.
is_primary (bool) – Indicates this is the primary action when included in a group of actions.
modal (bool) – Indicates the action triggers a modal window.
target (str) – The link target of the action.

data¶

class superdjango.ui.runtime.data.Datum(name, value, default=None, display_value=None, field_type=None, help_text=None, label=None, preview_value=None, **kwargs)[source]¶

Bases: object

A specific piece of information to be displayed to a user.

Tip

This is equivalent to a td in an HTML table.

__init__(name, value, default=None, display_value=None, field_type=None, help_text=None, label=None, preview_value=None, **kwargs)[source]¶

Initialize a datum instance.

Parameters

name (str) – The name of the field.
value – The “raw” value of the field from the database.
default – The default value if any.
display_value (str) – The human-friendly value to be displayed to users.
field_type (str) – The type of field.
help_text (str | HelpText) – The field’s help text.
label (str) – The field’s label, e.g. verbose name.
preview_value (str) – The preview value of the field, if any.

Note

Additional keyword arguments are available as dynamic attributes.

to_string()[source]¶

Get the datum as a string.

Return type: str

property type¶: Alias for field_type.

class superdjango.ui.runtime.data.Record(identifier, instance, actions=None, attributes=None, css=None, data=None, dictionary=None, display_name=None, meta=None, record_type=None, url=None, **kwargs)[source]¶

Bases: object

A collection of data (Datum) instances, e.g. a row.

Tip

This is equivalent to a tr in an HTML table.

__init__(identifier, instance, actions=None, attributes=None, css=None, data=None, dictionary=None, display_name=None, meta=None, record_type=None, url=None, **kwargs)[source]¶

Initialize a record instance.

Parameters

identifier (int | str) – The unique record identifier, e.g. the primary key of the model.
actions (list[Action]) – Row-level actions that may be performed on the record.
attributes (dict) – Record attributes that may be flattened as part of the HTMl output.
css (list | str) – CSS classes to be applied to the output.
data – A list of datum instances included in the record. See also add() and append().
display_name (str) – The human-friendly name of the record.
record_type (str) – The type of record, e.g. record._meta.model_name.

Note

Additional keyword arguments are available as properties of the record.

add(name, value, default=None, display_value=None, field_type=None, help_text=None, label=None, preview_value=None, **kwargs)[source]¶

Add datum to the record’s data by creating a new Datum instance.

See Datum.

Return type: Datum

append(datum)[source]¶

Add a datum instance to the record’s data.

Parameters: datum (Datum) – The instance to be added.
Raise: TypeError

get_absolute_url()[source]¶

Get the url attribute. Simulates a model instance.

Return type: str

to_string()[source]¶

Get the display name of the record or the string value of the first Datum instannce in the list.

Return type: str

filters¶

class superdjango.ui.runtime.filters.Choice(label, value, count=None, is_active=None)[source]¶

Bases: object

An individual choice within a filter.

__init__(label, value, count=None, is_active=None)[source]¶

Initialize a choice.

Parameters

label (str) – The choice label that is shown to users.
value – The value of the choice. Used for filtering.
count (int) – The total number of records matching the choice value.
is_active (bool) – Indicates the choice is active.

class superdjango.ui.runtime.filters.Filter(label, name, choices=None, keyword=None, location=None, orientation=None, template=None)[source]¶

Bases: object

A filter for a model list.

__init__(label, name, choices=None, keyword=None, location=None, orientation=None, template=None)[source]¶

Initialize the filter.

Parameters

label (str) – The label of the filter that is show to users.
name (str) – The programmatic name of the filter.
choices (list | QuerySet) – The filter choices.
keyword (str) – The GET keyword used to identify the filter. Defaults to the filter name.
location (str) – The location of the filter on the page.
orientation (str) – The orientation of the filter.
template (str) – The template to use for rendering the filter.

property is_bottom¶

Indicates the intended location for the filter is at the bottom of the output.

Return type: bool

property is_default¶

Indicates the intended location for the filter is the default location.

Return type: bool

property is_horizontal¶

Indicates the intended orientation for the filter is horizontal.

Return type: bool

property is_left¶

Indicates the intended location for the filter is left of the output.

Return type: bool

property is_right¶

Indicates the intended location for the filter is right of the output.

Return type: bool

property is_sidebar¶

Indicates the intended location for the filter is in the sidebar (left or right).

Return type: bool

property is_top¶

Indicates the intended location for the filter is at the top of the output.

Return type: bool

property is_vertical¶

Indicates the intended orientation for the filter is vertical.

Return type: bool

lists¶

class superdjango.ui.runtime.lists.CurrentOrdering(request, direction='asc', fields=None, initial_field=None)[source]¶

Bases: object

Represents the current ordering of a list based on field keywords and values in GET.

__init__(request, direction='asc', fields=None, initial_field=None)[source]¶

Initialize the current ordering.

Parameters

direction (str) – The default ordering direction for the initial field; asc or desc.
request – The current request instance.
fields (list[str]) – A list of fields by which the list may be ordered. See Ordering.
initial_field (str) – The name of the field to by which ordering should be initially provided.

Important

The initial_field must be part of fields.

property exists¶

Determine if an ordering keywords exist in request.GET.

Return type: bool

get_icon(field)[source]¶

Get the FontAwesome icon classes for the given field based on its current status in ordering.

Return type: str

get_keyword(field)[source]¶

Get the GET keyword and value for the field based on its current status in ordering.

Return type: str

class superdjango.ui.runtime.lists.CurrentPagination(page, request, current_limit=None, keyword='page', limit=None, location='default', paginator=None, style='previous-next', widget=None)[source]¶

Bases: object

Contains the current pagination options for a list.

__init__(page, request, current_limit=None, keyword='page', limit=None, location='default', paginator=None, style='previous-next', widget=None)[source]¶

Initialize current pagination.

Parameters

page (Page) – The page instance.
request – The current HTTP request instance. This is not assigned as an attribute, but is used to establish the current pagination fragments from GET.
current_limit (int | Limit) – The current limit.
keyword (str) – The GET keyword used to identify paged results.
limit (Limit) – The limit instance provided by pagination options. See get() UIListView` for its usage.
location (str) – The location of the navigation.
paginator (Paginator) – The paginator instance.
style (str) – The style of the navigation.
widget – NOT IMPLEMENTED

class superdjango.ui.runtime.lists.ListObject(records, list_type, template, attributes=None, empty_message=None, properties=None)[source]¶

Bases: object

Serves as a container of records to be displayed in a list of any type or output format.

__init__(records, list_type, template, attributes=None, empty_message=None, properties=None)[source]¶

Initialize the list object.

Parameters

records (list | QuerySet) – The records included in the list.
list_type (str) – The type of list that is currently being displayed.
template (str) – The template to use for rendering the list.
attributes (dict) – Additional attributes that may be included or used when rendering the list.
empty_message (str) – The message to display if the list contains no records.
properties (dict) – Additional properties to be accessible as attributes of the list object instance.

get_context_name()[source]¶

Get the type of list. Used in the template context to potentially determine how the list is to be displayed.

Return type: str

menus¶

class superdjango.ui.runtime.menus.Item(label, name, icon=None, sort_order=1, url=None, **kwargs)[source]¶

Bases: object

An individual menu item.

Note

This class is typically used in situations where a registered menu item contains only one model.

__init__(label, name, icon=None, sort_order=1, url=None, **kwargs)[source]¶

Initialize an item.

Parameters

label (str) – The label of the menu item as shown to users.
name (str) – The programmatic name of the item.
icon (str) – The icon to display as part of the item label.
sort_order (int) – The sort order of the item within a menu.
url (str) – The URL of the item.

Additional kwargs are available as properties of the item instance.

property is_separator¶

Runtime item instances are never used as separators.

Return type: bool

class superdjango.ui.runtime.menus.Location(name, sort_order=1)[source]¶

Bases: object

A location of menus and their items for use in templates.

__init__(name, sort_order=1)[source]¶

Initialize a menu location.

Parameters

name (str) – The location name.
sort_order (str) – The order in which the location appears next to other locations.

append(item)[source]¶

Add a menu or item to the location.

Parameters: item (Item | Menu) – The item to be added.

class superdjango.ui.runtime.menus.Menu(label, name, flat=False, icon=None, sort_order=1, url=None, **kwargs)[source]¶

Bases: object

A collection of menu items for use in templates.

__init__(label, name, flat=False, icon=None, sort_order=1, url=None, **kwargs)[source]¶

Initialize a menu.

Parameters

label (str) – The label of the menu shown to users.
name (str) – The programmatic name of the menu.
flat (bool) – Indicates the menu should be flattened, e.g. all items are display horizontally or at least using no sub-menu structure.
icon (str) – The icon to use for the menu.
sort_order (int) – The order of the menu in a list of menus.
url (str) – The URL of the menu.

Additional kwargs are available as properties of the menu instance.

property is_separator¶

Runtime menu instances are never used as separators.

Return type: bool

panels¶

class superdjango.ui.runtime.panels.Panel(content, **kwargs)[source]¶

Bases: object

Panel output.

__init__(content, **kwargs)[source]¶

Initialize panel output.

Parameters: content – The (parsed) panel content to be displayed.
Type: str

Note

Additional keyword arguments are available as attributes of the panel instance.

tools¶

class superdjango.ui.runtime.tools.Tool(name, enabled=True, location=None, sort_order=1, template=None)[source]¶

Bases: object

Placeholder for any tool.

__init__(name, enabled=True, location=None, sort_order=1, template=None)[source]¶

Initialize a tool instance.

Parameters

name (str) – The name of the tool.
enabled (bool) – Indicates the tool is enabled.
location (str) – The intended location of the tool on the page.
sort_order (int) – The order in which the tool appears with other tools in the same tool set.
template (str) – The template to use for the tool. Defaults to the name of the tool.

class superdjango.ui.runtime.tools.Tools(items=None)[source]¶

Bases: object

A collection of tools used to manage models, usually from a change list.

__init__(items=None)[source]¶

Initialize a tools instance.

Parameters: items (list[Tool]) – The tools to be included.

add(name, enabled=True, location=None, sort_order=1, template=None)[source]¶

Add a tool to the set.

See Tool.

Return type: Tool

property bottom¶

Indicates there are tools with location of LOCATION.BOTTOM.

Return type: bool

property left¶

Indicates there are tools with location of LOCATION.LEFT.

Return type: bool

property right¶

Indicates there are tools with location of LOCATION.RIGHT.

Return type: bool

sort()[source]¶: Sort tool instances by the sort_order attribute.

property top¶

Indicates there are tools with location of LOCATION.TOP.

Return type: bool

Views¶

Class-based views initialized for the UI

Component Reference: Views

access¶

class superdjango.ui.views.access.UIAccessMixin[source]¶

Bases: object

A UI-enabled mixin for checking user access to a view.

The primary difference between this mixin and superdjango.views.AccessMixin is that access options are defined using the access_policy attribute of the ModelUI.

dispatch(request, *args, **kwargs)[source]¶

Dispatch with access checks.

Parameters: request (django.http.request.HttpRequest) – The current request object.

Access is checked in the following order:

Check for SSL.
Check for an authenticated user.
Check for group membership.
Check for specific permissions.
Call self.ui.access_policy.check_other(). See dispatch_other().

dispatch_access_denied(request, reason='access_denied', redirect_url=None)[source]¶

Handle authentication or permission issues during dispatch.

Parameters

request (django.http.request.HttpRequest) – The current request object.
reason (str) – A reason for the permission failure.
redirect_url (str) – The URL to which the user should be directed.

dispatch_insecure(request, reason='ssl_required')[source]¶

Handle failed SSL connections.

Parameters

request (django.http.request.HttpRequest) – The current request object.
reason (str) – A reason for the permission failure.

dispatch_other(request, reason='access_denied', redirect_url=None)[source]¶

Responds to failed check_other(). Override this method to provide your own handling.

Parameters

reason (str) – A reason for the permission failure.
request (django.http.request.HttpRequest) – The current request object.
redirect_url (str) – The URL to which the user should be directed.

Note

By default, this method simply calls dispatch_access_denied().

get_https_url(request)[source]¶

Get the current URL with the HTTPS protocol.

Parameters: request (django.http.request.HttpRequest) – The current request object.

redirect_to_login(path)[source]¶

Redirect to the login view using the given path as the next URL.

Parameters: path (str) – The next URL after logging in.

ajax¶

class superdjango.ui.views.ajax.UIAjaxAutoCompleteView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

Facilitate AJAX lookups for foreign keys and many to many fields.

Note

This differs from UIAjaxSearchView in that the format of the search results is provided for use with select2.

To invoke auto-complete, use the auto_complete_fields on the form options for the model that refers to remote fields.

case_sensitive = False¶: Indicates whether the search will be case sensitive.

criteria = None¶: Additional criteria by which the results should be filtered.

exact_matching = False¶: When True, exact matching is required.

fields = None¶: A list of field names on the model to be searched for results.

get_criteria(request)[source]¶

Get any additional criteria.

Parameters: request – The current request instance.
Return type: dict

get_queryset(request, term)[source]¶

Get the records matching the given search term.

Return type: django.db.models.QuerySet

label_field = None¶: The field to use for the label of each result. If omitted, get_choice_name() will be called. Failing that, the string representation of the result is used.

term_keyword = 'term'¶: The GET keyword used to identify the search term.

ui = None¶: The current ModelUI instance.

class superdjango.ui.views.ajax.UIAjaxChainedLookupView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

Provide results for a reference field (foreign key or many to many) based on the value of another selected field.

The following steps are required to set up a chain:

For This Example*

Imagine you have three models; Book, Part, and Chapter. A chapter is associated with both Book and Part. We want the part drop-down to populate based on the selected book.

Add Chain Options to Dependent Model

Define ajax_chained_options for Part:

class PartUI(ui.ModelUI):
    model = Part
    ajax_chained_lookup_options = ui.AjaxChainedLookupOptions("book", identifier="pk")
    # ...

This sets up the AJAX view that responds to the chain request.

Tell the Chapter Form to Use Chaining

Next define the chain on form_options (or create_options and update_options):

class ChapterUI(ui.ModelUI):
    model = Chapter
    form_options = ui.FormOptions(
        "book",
        "part",
        "title",
        "body",
        "description",
        chained_fields=[ui.ChainedLookup("book", "part")],
    )

The first field of ChainedLookup (book) is the field used to filter the dropdown. The second field is the name of the dropdown field (part).

criteria = None¶: Additional criteria, if any, to be applied to the lookup.

remote_field_identifier = None¶: Used when the remote field is also a reference field.

remote_field_name = None¶: The name of the field that provides the key to chained results.

class superdjango.ui.views.ajax.UIAjaxChooserView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

A view for selecting a foreign key via a modal.

criteria = None¶: Additional criteria by which results should be filtered.

fields = None¶: The fields to be included in the output. Note: pk is always included.

get_controls()[source]¶

Get the controls used to display fields/columns.

Return type: list[BaseControl]

render_to_response(context, template)[source]¶

Render the current context.

Parameters

context (dict) – The context variables to use for rendering.
template (str) – The template to use for rendering.

Return type

TemplateResponse

template = None¶: The template to use when html is the requested output_format.

class superdjango.ui.views.ajax.UIAjaxCreateView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxFormMixin, django.views.generic.base.View

A view for creating a record via AJAX.

display_name = None¶: The field on the record to use as the human-friendly name in the form control for the created record.

identifier = 'pk'¶: The unique identifier of the record to be passed back as the value for the form control for the created record.

template_name_suffix = '_ajax_create'¶: The suffix of the template used to display the creation form.

class superdjango.ui.views.ajax.UIAjaxDetailView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

Display model detail via AJAX.

get_controls()[source]¶

Get the controls used to display fields/columns.

Return type: list[BaseControl]

get_object()[source]¶: Get the object (model instance) that may be used in CreateView, DetailView, DeleteView, and UpdateView.

render_to_response(context, template)[source]¶

Render the current context.

Parameters

context (dict) – The context variables to use for rendering.
template (str) – The template to use for rendering.

Return type

TemplateResponse

class superdjango.ui.views.ajax.UIAjaxDragAndDropView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

Support for AJAX drag and drop.

The hook_ajax_drag_and_drop is called after the column change and (optionally) sort order is applied to the record, the function signature is hook(column_value, record, sort_order=sort_order).

column_field = 'stage'¶: “The name of the field used to define Kanban columns. This may be a foreign key or a field with choices defined.

column_model = None¶: The model class of the foreign key field used to identify columns.

sort_order_field = 'sort_order'¶: The field to use for sorting a record within the column_field.

class superdjango.ui.views.ajax.UIAjaxFormMixin[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin

Base class for AJAX forms.

cancel_text = 'Close'¶: The text to display as part of the cancel URL.

fields = None¶: A list of field names that may be used during record creation.

fields_from_get = None¶: A list of field names whose initial value may be acquired from GET. This functionality is NOT provided by the mixin and must be implemented (if desired) in child classes.

fieldsets = None¶: A list of Fieldset instances into which form fields should be divided.

form_class = None¶: The class to use for rendering forms.

get(request, *args, **kwargs)[source]¶: Handle GET requests.

get_template_names()[source]¶

Get the templates that may be used to render the form.

Return type: list[str]

post(request, *args, **kwargs)[source]¶: Handle POST requests, i.e form submission.

render_to_response(context)[source]¶

Render the current context.

Parameters: context – The context variables to use for rendering.
Return type: TemplateResponse

selector = None¶: The selector used to live update page content after successful form submission.

submit_text = 'Submit'¶: The text to display for the submit button.

template_name = None¶: The template to use for rendering the form.

template_name_suffix = '_ajax_form'¶: The suffix for the form template.

class superdjango.ui.views.ajax.UIAjaxListView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

AJAX list of records.

Note

This is currently only supporting the DataTable list type and is very specific to the output format required by the JavaScript implementation.

get_controls()[source]¶

Get the controls used to display fields/columns.

Return type: list[BaseControl]

get_queryset()[source]¶

Get the queryset used by the view. This will either be a list or individual instance.

Return type: django.db.models.QuerySet

class superdjango.ui.views.ajax.UIAjaxMarkCompleteView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

Mark a record complete.

callback = None¶

A callable that overrides all processing. It must accept the model instance and request as arguments and return the data (dict) to be processed through get_json_response(). Data includes:

heading: Optional. The heading, if any, for the toast displayed to the user.
hideAfter: Required. The number of milliseconds to display the toast, or False to disable automatic fade out.
position: Optional. The position of the toast.
text: Required. The message to display.

Additionally (and obviously), the callback is expected to mark the record as complete.

class superdjango.ui.views.ajax.UIAjaxMixin[source]¶

Bases: superdjango.ui.views.access.UIAccessMixin, superdjango.views.ajax.mixins.JSONMixin

Base class for UI classes implementing AJAX functionality.

The JSONMixin provides the following attributes:

ajax_required
content_type
decoder_class
encoder_class
json_required

This mixin provides the following attributes:

logging_enabled
pattern
ui

get_display_name(record)[source]¶

Get the human-friendly name of a model instance.

Parameters: record – The model instance.
Return type: str

get_object()[source]¶

Get the record for the current request. Applies only to views that deal with one record at a time.

Return type: BaseType[django.db.models.Model] | None

logging_enabled = False¶: Indicates logging is enabled for view activities.

object = None¶: For views that operate on a single record, this is the record (model instance). See get_object().

pattern_name = None¶: The pattern name of the view. Overrides the default.

ui = None¶: The current ModelUI instance.

class superdjango.ui.views.ajax.UIAjaxReorderView(**kwargs)[source]¶: Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

class superdjango.ui.views.ajax.UIAjaxSearchView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxMixin, django.views.generic.base.View

Facilitates model search via AJAX.

case_sensitive = False¶: Indicates whether the search will be case sensitive.

criteria = None¶: Additional criteria by which results should be filtered.

exact_matching = False¶: When True, exact matching is required.

fields = None¶: A list of field names on the model to be searched for results.

get(request, *args, **kwargs)[source]¶: Get the search results.

get_queryset(term)[source]¶

Get the records matching the given search term.

Return type: django.db.models.QuerySet

label_field = None¶: The field to use for the label of each result. If omitted, get_display_name() will be called. Failing that, the string representation of the result is used.

link_to = 'detail'¶: The name of the view (verb) to which search results should be linked.

minimum_length = 3¶: The minimum number of characters required to generate a queryset.

term_keyword = 'term'¶: The GET keyword used to identify the search term.

class superdjango.ui.views.ajax.UIAjaxUpdateView(**kwargs)[source]¶

Bases: superdjango.ui.views.ajax.UIAjaxFormMixin, django.views.generic.base.View

A view for updating a record via AJAX.

display_name = None¶: The field on the record to use as the human-friendly name in the form control for the updated record.

fields = None¶: A list of field names that may be used during record update.

get(request, *args, **kwargs)[source]¶: Get the HTML form for the modal.

get_object()[source]¶

Get the record for the current request. Applies only to views that deal with one record at a time.

Return type: BaseType[django.db.models.Model] | None

identifier = 'pk'¶: The unique identifier of the record to be passed back as the value for the form control for the updated record.

post(request, *args, **kwargs)[source]¶: Get the current model instance.

template_name_suffix = '_ajax_update'¶: The suffix of the template used to display the update form.

base¶

class superdjango.ui.views.base.UIBaseMixin[source]¶

Bases: superdjango.ui.views.access.UIAccessMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.messages.MessageMixin

Base class for UI views (except AJAX).

actions = None¶: An instance of superdjango.options.utils.Actions containing the view-level actions for the current view.

active_page = None¶: The name of the active page that may be used to identify the current view within a menu.

active_subpage = None¶: The name of the active subpage that may be used to identify the current view within a submenu.

base_template = None¶: The base template used to render the view.

dispatch_not_found(message=None)[source]¶

Dispatch a 404 (page not found) error. By default, this just raises an Http404.

Parameters: message – The 404 message.

get_base_template()[source]¶

Get the name of the base template to use for rendering the view.

Return type: str

get_breadcrumbs()[source]¶: Get breadcrumbs for the model view.

get_context_data(*args, **kwargs)[source]¶: Add breadcrumbs to the context.

get_css()[source]¶

Get the URLs or markup of any CSS to be included in the view.

Return type: StyleSheet

get_js()[source]¶

Get the URLs or markup of any JavaScript to be included in the view.

Return type: JavaScript

get_subtitle()[source]¶

Get the page subtitle.

Return type: str

get_template_name_suffix()[source]¶

Get the suffix for the current view template.

Return type: str

Tip

Extending classes should define the template_name_suffix. The suffix should include an underscore for separation. For example, the suffix for a view for creating a new record would be _add.

The default behavior here is to return an empty string if template_name_suffix is not defined.

get_template_names()[source]¶

Get the template names that may be used for rendering the response.

Return type: list[str]

The possible names are generated like so:

If the child class defines a template_name, this is always returned as the first element of the list.
This method first defines templates that may be defined by the local project in the form of {app_label}/{model_name_lower}{template_name_suffix}.html.
Finally, the generic template is supplied for SuperDjango UI.

get_title()[source]¶

Get the page title.

Return type: str

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

raise_exception = True¶: Indicates whether a processing exceptions should be raised or only logged.

subtitle = None¶: The subtitle of the view page.

template_name = None¶: The name of the template (which extends the base_template) that is used to render the view. It omitted, an attempt is made to determine the template name automatically. See get_template_names().

template_name_suffix = None¶: The template suffix used to automatically determine the template name. See get_template_names().

title = None¶: The title of the view page.

ui = None¶: The ModelUI instance that generated the view.

crud¶

class superdjango.ui.views.crud.UICreateView(**kwargs)[source]¶

Bases: superdjango.ui.views.forms.UIFormMixin, superdjango.ui.views.crud.UIModelView

A model create view.

get_subtitle()[source]¶: Return “Create” by default.

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

class superdjango.ui.views.crud.UIDeleteView(**kwargs)[source]¶

Bases: superdjango.ui.views.forms.UIFormMixin, superdjango.ui.views.crud.UIModelView

A model delete view.

get(request, *args, **kwargs)[source]¶: Display the delete confirmation page.

get_css()[source]¶

Delete views do not incorporate standard CSS by default.

Return type: StyleSheet

get_js()[source]¶

Delete views do not incorporate standard JavaScript by default.

Return type: JavaScript

get_subtitle()[source]¶: Return “Delete” by default.

get_success_message()[source]¶: Get the post-delete message to display to a user.

get_verb()[source]¶: Returns delete.

get_warning_message()[source]¶: Get the warning to display to the user on the delete confirmation page.

post(request, *args, **kwargs)[source]¶: Delete the object and redirect using the success URL.

save_url_history(context)[source]¶: A delete page in history is okay, but will result in a 404 unless the user canceled. So it’s safer to exclude delete from history.

class superdjango.ui.views.crud.UIDetailView(**kwargs)[source]¶

Bases: superdjango.ui.views.crud.UIModelView

A model detail view.

get_inlines(request)[source]¶: Get inlines for the detail view.

get_verb()[source]¶: Returns detail.

class superdjango.ui.views.crud.UIListView(**kwargs)[source]¶

Bases: superdjango.ui.views.crud.UIModelView

Model list view.

allow_empty = True¶: Indicates whether an empty queryset is allowed. When False an empty queryset will raise an Http404.

auto_refresh = None¶: Indicates whether auto-refresh is enabled on the output. May be given as True, the number of seconds between refresh (int), or the JavaScript to use for the refresh (str).

bulk_actions = None¶: A list of standard (global) action names or action classes that may be used for bulk actions.

context_menu = None¶: The context menu instance.

default_list_type = None¶: The name of the default list type.

empty_message = None¶: The message to display when there are no results.

filtering = None¶: The filtering instance used to provide filter controls.

get(request, *args, **kwargs)[source]¶

Get the queryset and optionally apply pagination.

The context includes empty_message when allow_empty is True and no results are found.

is_paginated is also included and is either True or False.

If pagination is enabled, additional variables are also added to the context:

current_page: The same as page_object.
page_keyword: The GET keyword used to indicate the current page number.
page_obj: The current page object from get_paginated_queryset().
pagination_style: The preferred output of pagination links.
paginator: The paginator instance from get_paginator().

get_bulk_actions()[source]¶

Get the bulk actions for the list.

Return type: list[Action] | None

get_context_menu()[source]¶

Get the context menu to display for the list.

Return type: Actions | None

get_css()[source]¶

Get the URLs or markup of any CSS to be included in the view.

Return type: StyleSheet

get_empty_message()[source]¶

Get the message to be displayed for an empty queryset.

Return type: str

get_filters()[source]¶

Get the available filters for display.

Return type: list[BaseType[BaseFilter]] | None

get_js()[source]¶: Get the JavaScript for bulk-actions and filters.

get_limit(pagination)[source]¶

Get the number of records to display per page.

Parameters: pagination (Pagination) – Pagination options.
Return type: int | None

get_list_object(queryset)[source]¶: Get the list class instance.

get_list_type()[source]¶

Get the list type instance.

Return type: BaseType[BaseList]

get_ordered_queryset(queryset)[source]¶

Get the ordered/sorted queryset based on list ordering options and the current request.

Parameters: queryset – django.db.models.QuerySet
Return type: django.db.models.QuerySet

get_page_keyword()[source]¶

Get the keyword used to identify the page number in GET.

Return type: str | None

get_paginated_queryset(limit, queryset)[source]¶

Paginate the given queryset.

Parameters

limit (int) – The number of objects per page.
queryset (django.db.Queryset) – The query set to be paginated.

Return type

Page

get_pagination()[source]¶

Get the pagination instance.

Return type: Pagination | None

get_paginator(queryset, per_page)[source]¶

Get a paginator instance.

Return type: Paginator

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

has_bulk_actions()[source]¶

Indicates whether bulk actions have been defined.

Return type: bool

has_filters()[source]¶

Indicates whether filtering has been defined.

Return type: bool

limit = None¶: The total records to be displayed on a page. Setting this value will invoke pagination.

link_field = None¶: The field, if any, upon which a link will be enabled for further action.

link_to = None¶: The action (verb) to use for the link_field.

list_types = None¶: A dictionary of instances extending BaseList that may be used to render lists.

list_types_label = None¶: The label to use for switching list types.

ordering = None¶: The ordering instance used to sort/re-order the list.

page_keyword = 'page'¶: The GET key used to indicate the pagination page number. Defaults to page.

pagination = None¶: The Pagination instance used to control list pagination.

record_actions = None¶: A list of action names or action instances that may be added to individual roles.

record_actions_label = 'Actions'¶: The name of actions as displayed to users.

save_url_history(context)[source]¶: Add list/filter info.

total_count_enabled = False¶: Indicates whether a total count display should be enabled.

class superdjango.ui.views.crud.UIModelView(**kwargs)[source]¶

Bases: superdjango.ui.views.base.UIBaseMixin, django.views.generic.base.View

context_object_name = None¶: The name of the model object (or objects) when used in a template.

fields = None¶: The fields to be displayed in form, list, and detail views.

get_breadcrumbs()[source]¶: Get breadcrumbs for the model view.

get_context_data(**kwargs)[source]¶: Add breadcrumbs to the context.

get_context_object_name()[source]¶

Get the name of the model (or models) used in templates.

Return type: str | None

get_controls()[source]¶

Get the controls used to display fields/columns.

Return type: list[BaseControl]

get_css()[source]¶

Get the URLs or markup of any CSS to be included in the view.

Return type: StyleSheet

get_display_name(record)[source]¶

Get the human-friendly name of a model instance.

Parameters: record – The model instance.
Return type: str

get_inlines(request)[source]¶

Get the inline instances associated with the model.

Parameters: request – The current HTTP request instance.
Return type: list[InlineModelUI] | None

get_js()[source]¶

Get the URLs or markup of any JavaScript to be included in the view.

Return type: JavaScript

get_object()[source]¶: Get the object (model instance) that may be used in CreateView, DetailView, DeleteView, and UpdateView.

get_object_list()[source]¶

Get the objects to be displayed by list views. Used by ListView.

Return type: django.db.models.QuerySet

get_queryset()[source]¶

Get the queryset used by the view. This will either be a list or individual instance.

Return type: django.db.models.QuerySet

get_title()[source]¶

Get the page title.

Return type: str

inlines = None¶: The inline models, if any, to be displayed with a record.

object = None¶: The record (instance) of a model for create, detail, delete, and update views. This is not used by list views.

object_list = None¶: The record instances of a model for list views.

prefetch_related = None¶: A list of foreign key or many to many fields that should be called using Django’s prefetch_related.

queryset = None¶: The queryset used to acquire the object or object list. See get_queryset().

render_to_response(context)[source]¶

Render the current context.

Parameters: context – The context variables to use for rendering.
Return type: TemplateResponse

save_url_history(context)[source]¶

Call the underlying method on ModelUI. Called from render_to_response().

Parameters: context (dict) – The current context.

By default, title and subtitle are passed to history. Child views may override to add their own info.

select_related = None¶: A list of foreign key fields that should be called using Django’s select_related.

class superdjango.ui.views.crud.UIUpdateView(**kwargs)[source]¶

Bases: superdjango.ui.views.forms.UIFormMixin, superdjango.ui.views.crud.UIModelView

Update model view.

get(request, *args, **kwargs)[source]¶: Get the current model instance.

get_subtitle()[source]¶: Return “Update” by default.

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

post(request, *args, **kwargs)[source]¶: Get the current model instance.

extended¶

class superdjango.ui.views.extended.UIChooserView(**kwargs)[source]¶

Bases: superdjango.ui.views.templates.UITemplateView

Select a record before continuing to the next view.

criteria = None¶: Additional criteria to apply when getting the queryset.

description_field = 'description'¶: The field to use for the choice description.

display_choices_as = 'ul'¶: The desired output of the choices; cards, (list) group, ol, or ul.

get_context_data(*args, **kwargs)[source]¶: Add breadcrumbs to the context.

get_verb()[source]¶

Return the verb attribute.

Return type: str
Raise: IMustBeMissingSomething

link_field = None¶: The field on the queryset’s model to use as the name of the link.

link_to = None¶: The verb to which the choice is linked.

parameter_prefix = 'i_'¶: The prefix used to identify the choice in GET. f_, i_, or anything recognized by the next view.

class superdjango.ui.views.extended.UIDashboardView(**kwargs)[source]¶

Bases: superdjango.ui.views.templates.UITemplateView

get_breadcrumbs()[source]¶: Get breadcrumbs for the model view.

get_context_data(**kwargs)[source]¶: Add breadcrumbs to the context.

get_title()[source]¶: Get title or plural verbose name.

class superdjango.ui.views.extended.UIDuplicateView(**kwargs)[source]¶

Bases: superdjango.ui.views.crud.UIUpdateView

Provides a means to duplicate a record using GET to make the initial identification. This differs from UISaveAsView in that it may be called directly, whereas save as requires that a new record has already been created.

copy_field = 'title'¶: The name of the field to which the copy_text will be appended.

copy_text = '(Copy)'¶: Text used to indicate that the record is a duplicate.

form_valid(form, formsets=None)[source]¶: Duplicate the current instance.

get(request, *args, **kwargs)[source]¶: Get the current model instance and rename the copy_field.

get_save_as_message()[source]¶: Get the message to display for duplication.

get_save_as_text()[source]¶: The duplicate view cannot be used with the save_as option.

save_as_message = None¶: The message to display which indicates the record is a duplicate. This is displayed before the form is submitted.

class superdjango.ui.views.extended.UIHistoryView(**kwargs)[source]¶

Bases: superdjango.ui.views.crud.UIListView

View record history.

get_object_list()[source]¶: Get the current record and ask the history class for the history records to be displayed.

history_class = None¶: The model class used to store historical activity.

class superdjango.ui.views.extended.UIIntermediateChoiceView(**kwargs)[source]¶

Bases: superdjango.ui.views.templates.UITemplateView

An intermediate view prompts the user one (and only one) choice before moving to the next view.

choices = None¶: The choices to be presented. These may be provided as a list of Choice instances or a callable. The callable must accept args for request and ui and return a list of Choice instances.

display_choices_as = 'ul'¶: The desired output of the choices; cards, (list) group, ol, or ul.

get_context_data(*args, **kwargs)[source]¶: Add breadcrumbs to the context.

get_verb()[source]¶

Return the verb attribute.

Return type: str
Raise: IMustBeMissingSomething

class superdjango.ui.views.extended.UIIntermediateFormView(**kwargs)[source]¶

Bases: superdjango.ui.views.forms.UIFormMixin, superdjango.ui.views.crud.UIModelView

An intermediate view prompts the user for input before moving to the next view.

callback = None¶: A callback which accepts form, request, and ui parameters and returns the success_url. If provided, no other processing occurs in form_valid().

form_valid(form, formsets=None)[source]¶

Save the object and redirect.

Parameters

form – The valid form instance.
formsets – A list of (valid) formset instances.

Return type

HttpResponseRedirect

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

parameter_prefix = 'i_'¶: The prefix used to identify the choice in GET. f_, i_, or anything recognized by the next view.

class superdjango.ui.views.extended.UIMarkArchivedRedirect(**kwargs)[source]¶

Bases: superdjango.views.redirects.RedirectView, superdjango.ui.views.crud.UIModelView

Mark a record as archived, then redirect.

get_redirect_url(*args, **kwargs)[source]¶: Return the URL redirect to. Keyword arguments from the URL pattern match generating the redirect request are provided as kwargs to this method.

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

class superdjango.ui.views.extended.UIMarkCompleteRedirect(**kwargs)[source]¶

Bases: superdjango.views.redirects.RedirectView, superdjango.ui.views.crud.UIModelView

Mark a record as complete, then redirect.

get_redirect_url(*args, **kwargs)[source]¶: Return the URL redirect to. Keyword arguments from the URL pattern match generating the redirect request are provided as kwargs to this method.

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

class superdjango.ui.views.extended.UIMarkPublishedRedirect(**kwargs)[source]¶

Bases: superdjango.views.redirects.RedirectView, superdjango.ui.views.crud.UIModelView

Mark a record as published, then redirect.

get_redirect_url(*args, **kwargs)[source]¶: Return the URL redirect to. Keyword arguments from the URL pattern match generating the redirect request are provided as kwargs to this method.

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

class superdjango.ui.views.extended.UIMarkResolvedRedirect(**kwargs)[source]¶

Bases: superdjango.views.redirects.RedirectView, superdjango.ui.views.crud.UIModelView

Mark a record as resolved, then redirect.

get_redirect_url(*args, **kwargs)[source]¶: Return the URL redirect to. Keyword arguments from the URL pattern match generating the redirect request are provided as kwargs to this method.

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

class superdjango.ui.views.extended.UIMarkReviewedRedirect(**kwargs)[source]¶

Bases: superdjango.views.redirects.RedirectView, superdjango.ui.views.crud.UIModelView

Mark a record as reviewed, then redirect.

get_redirect_url(*args, **kwargs)[source]¶: Return the URL redirect to. Keyword arguments from the URL pattern match generating the redirect request are provided as kwargs to this method.

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

class superdjango.ui.views.extended.UISaveAsView(**kwargs)[source]¶

Bases: superdjango.ui.views.crud.UIUpdateView

Provide a means to save a record as a different record. The objective given to the view must already be a new record. See UIFormMixin for how this is implemented.

copy_field = 'title'¶: The name of the field to which the copy_text will be appended.

copy_text = '(Copy)'¶: Text used to indicate that the record is a duplicate.

get(request, *args, **kwargs)[source]¶: Get the current model instance.

get_save_as_message()[source]¶: Get the message to display for duplication.

get_save_as_text()[source]¶: The save as view cannot itself be used with the save_as option.

save_as_message = None¶: The message to display which indicates the record is a duplicate. This is displayed before the form is submitted.

class superdjango.ui.views.extended.UISearchView(**kwargs)[source]¶

Bases: superdjango.ui.views.crud.UIModelView

Search results for a specific model.

get(request, *args, **kwargs)[source]¶: The search view does not fetch the object list immediate, but instead displays the search form.

get_results(term, case_sensitive=False, exact_matching=False)[source]¶

Get the records matching the given search term.

Return type: django.db.models.QuerySet

Note

SQLite does not support case sensitive matching. See https://docs.djangoproject.com/en/stable/ref/models/querysets/#contains

get_verb()[source]¶

Get the verb/action associated with the view.

Return type: str

Important

Child classes must implement this method.

post(request, *args, **kwargs)[source]¶: Search for the terms submitted with the form.

forms¶

class superdjango.ui.views.forms.UIFormMixin[source]¶

Bases: object

Provides form-related methods and attributes.

auto_complete_fields = None¶: A list of fields that should be filled using auto-complete.

cancel_text = None¶: The text to display as part of the cancel URL.

cancel_url = None¶: The URL to which the user should be sent when canceling the confirmation.

chained_fields = None¶: A list of superdjango.ui.options.utils.ChainedLookup instances.

error_message = None¶: The message to be displayed for an invalid (failed) form submission.

exit_warning = None¶: The message to display if the user has made changes to the form, but clicks something other than submit.

fields_from_get = None¶: A list of field names whose initial value may be acquired from GET. This functionality is NOT provided by the mixin and must be implemented (if desired) in child classes.

fieldsets = None¶: A list of Fieldset instances into which form fields should be divided.

form_class = None¶: The class to use for rendering forms.

form_invalid(form, formsets=None)[source]¶: Handle invalid form submission.

form_valid(form, formsets=None)[source]¶

Save the object and redirect.

Parameters

form – The valid form instance.
formsets – A list of (valid) formset instances.

Return type

HttpResponseRedirect

get(request, *args, **kwargs)[source]¶: Handle GET requests.

get_cancel_text()[source]¶

Get the text to display for the cancel link or button.

Return type: str

get_cancel_url()[source]¶

Get the URL for canceling the form.

Return type: str | None

get_context_data(**kwargs)[source]¶

Add form-specific values to the context.

cancel_text
cancel_url
form
submit_text

get_css()[source]¶

Get any CSS included in the form.

Return type: StyleSheet

get_error_message()[source]¶

Get the error message for an invalid form submission.

Return type: str | None

get_js()[source]¶

Get JavaScript to be used in the form.

Return type: JavaScript

get_save_and_add_text()[source]¶

Get the text to display for the “save and add another” button.

Return type: str | None

get_save_and_continue_text()[source]¶

Get the text to display for the “save and continue editing” button.

Return type: str | None

get_save_as_text()[source]¶

Get the text to display for the “save as” button.

Return type: str | None

Note

Unlike save/add and save/continue, save as is only enabled when save_as_options have been defined on the model UI.

get_submit_text()[source]¶

Get the text to display for the submit button.

Return type: str

get_success_message()[source]¶

Get the message to be displayed after a successful form submision.

Return type: str | None

get_success_url()[source]¶

Get the URL to which the user should be sent on successful form submit.

Return type: str

post(request, *args, **kwargs)[source]¶: Handle POST requests, i.e form submission.

save_and_add = None¶: Indicates “Save and Add Another” functionality should be supported. Set to True or to the text to be displayed on the button.

save_and_continue = None¶: Indicates “Save and Continue Editing” functionality should be supported. Set to True or to the text to be displayed on the button.

save_as = None¶: Indicates “Save As” (duplicate) functionality should supported. Set True or to the text to be displayed on the button. Note that save_as_options must also be defined on the model UI.

submit_text = None¶: The text to display for the submit button.

success_message = None¶: The message to be displayed after a valid (successful) form submission.

success_url = None¶: The URL to which a user is sent after a successful (valid) form submission.

tabs = None¶: A list of Tab instances into which form fields should be organized.

class superdjango.ui.views.forms.UIFormWizardView(**kwargs)[source]¶

Bases: superdjango.ui.views.base.UIBaseMixin, formtools.wizard.views.SessionWizardView

Create a form wizard.

callback = None¶: The function to be called when the last form is submitted. See done(). This function should accept the form list, current request instance, current ModelUI instance, and keyword arguments.

done(form_list, **kwargs)[source]¶: Call the callback function and redirect to the success URL.

fields = None¶: A list of field names to be included across all forms.

form_steps = None¶: A list for superdjango.ui.options.FormStep instances.

get_controls()[source]¶

Get the controls used to display fields/columns.

Return type: list[BaseType[BaseControl]]

get_css()[source]¶

Get any CSS to be included in the form.

Return type: StyleSheet

get_form_prefix(step=None, form=None)[source]¶: There is no need to prefix forms for the model UI.

get_js()[source]¶

Get any JavaScript to be included in the form.

Return type: JavaScript

get_success_url()[source]¶

Get the URL to which the user is redirected after successfully submitting the last form.

Return type: str

get_verb()[source]¶: Always returns VERB.WIZARD.

success_url = None¶: The URL to which the user is redirected after successfully submitting the last form.

template_name_suffix = '_form_wizard'¶: The suffix for templates using this view.

ui = None¶: The current ModelUI instance.

templates¶

class superdjango.ui.views.templates.UITemplateView(**kwargs)[source]¶

Bases: superdjango.ui.views.base.UIBaseMixin, django.views.generic.base.View

get_verb()[source]¶

Return the verb attribute.

Return type: str
Raise: IMustBeMissingSomething

render_to_response(context)[source]¶

Render the current context.

Parameters: context – The context variables to use for rendering.
Return type: TemplateResponse

verb = None¶: Set this to the action represented by your view. Returned by get_verb(), but will raise an error if left as None.