Misago brings its own admin site just like Django does. This means you have to make a decision which one your app will use for it's administration.
If you intend to be sole user of your app, Django admin will propably be faster to get going. However if you plan for your app to be available to wider audience, its good for your admin interface to be part of Misago admin site. This will require you to write more code than in case you've went Django way, but will give your users more consistent experience and, in case for some languages, save them of quirkyness that comes with Django admin automatically created messages.
Unlike Django, Misago admin is not "automagical". This means you will not get complete admin from nowhere by just creating one file and writing 3 lines of code in it. However Misago provides set of basic classes defined in in
misago.admin.views.generic module that can offload most of burden of writing views handling items lists and forms from you.
Workflow with those classes is fast and easy to master. First, you define your own mixin (propably extending
AdminBaseMixin). This mixin will define common properties and behaviours of all admin views, like which model are admin views focused on, how to fetch its instances from database as well as where to seek templates and which message should be used when model could not be found.
Next you define your own views inheriting from your mixin and base views. Misago provides basic views for each of most common scenarios in admin:
ListView for items lists. Supports pagination, sorting, filtering and mass actions.
ModelFormView for displaying and handling forms submissions.
ButtonView for handling state-changing button presses like "delete item" actions.
Base class for admin mixins that contain properties and behaviours shared between admin views. While you are allowed to set any properties and function on your own mixins to dry your admin views more, bare minimum expected from you is following:
model property or
get_model(self) method to get model type.
root_link property that is string with link name for "index" view for admin actions (usually link to items list).
templates_dir property being string with name of directory with admin templates used by mixin views.
Optionally if you don't plan to set up action-specific item not found messages, you may set
message_404 property on mixin to make all your views use same message when requested model could not be found.
Base class for lists if items. Supports following properties:
template - name of template file located in
templates_dir used to render this view. Defaults to
items_per_page - integer controlling number of items displayed on single page. Defaults to 0 which means no pagination
search_form - Form type used to construct form for filtering this list. Either this field or
get_search_form method is required to make list searchable.
ordering - list of supported sorting methods. List of tuples. Each tuple should countain two items: name of ordering method (eg. "Usernames, descending") and
order_by argument (
-username). Defaults to none which means queryset will not be ordered. If contains only one element, queryset is ordered, but option for changing ordering method is not displayed.
mass_actions - list of dicts defining list's mass actions. Each dict should have
action key that will be used to identify method to call,
name for displayed name,
icon for icon and optional
confirmation message. Actions can define optional "is_atomic" key to control if they should be wrapped in transaction or not. This is default behaviour for mass actions.
selection_label - Label displayed on mass action button if there are items selected.
0 will be replaced with number of selected items automatically.
empty_selection_label - Label displayed on mass action button if there are no items selected.
In addition to this, ListView defines following methods that you may be interested in:
This function is expected to return queryset of items that will be displayed. If filters, sorting or pagination is defined, this queryset will be further sliced and filtered.
Class method that allows you to add custom links to item actions. Link should be a string with link name, not complete link. It should also accept same kwargs as other item actions links.
This function is used to get search form class that will be used to construct form for searching list items.
If you decide to make your list searchable, remember that your Form must meet following requirements:
filter_queryset(self, search_criteria, queryset) method that will be passed unfiltered queryset, which it should modify using filter/exclude clauses and data from
Must return queryset.
Must not define fields that use models for values.
If you add custom mass action to view, besides adding new entry to
mass_actions list, you have to define custom method following this definition:
ACTION will be replaced with action dict
action value. Request is
HttpRequest instance used to call view and
items is queryset with items selected for this action. This method should return nothing or
HttpResponse. If you need to, you can raise
MassActionError with error message as its first argument to interrupt mass action handler.
Base class for forms views.
template - name of template file located in
templates_dir used to render this view. Defaults to
form property or create_form_type method -
create_form method is called with
request as its argument and is expected to return form type that will be used by view. If you need to build form type dynamically, instead of defining
form property, define your own
Returns form type that will be used to create form instance. By default returns value of
Initializes either bound or unbound form using request and
If form validated successfully, this method is called to perform action. Here you should place code that will read data from form, perform actions on models and set result message. Optionally you may return
HttpResponse from this function. If nothing is returned, view returns redirect to
Optionally your form template may have button with
name="stay" attribute defined, pressing which will cause view to redirect you to clean form instead.
Base class for targetted forms views. Its API is largery identic to
FormView, except it's tailored at handling
ModelForm and modifying model states. All methos documented for
FormView are present in
ModelformView, but they accept one more argument named "target", containing model instance to which model form will be tied.
In addition, this view comes with basic definition for form handler that calls
save() on model instance and (if defined) sets success message using value of objects
Base class for handling non-form based
Do control this view behaviour, define your own
This function is expected to perform requested action on target provided and set result message on
It may return nothing or
HttpResponse. If nothing is returned, view returns redirect to
ButtonView are called "targeted views", because they are expected to manipulate model instances. They both inherit from
TargetedView view, implements simple API that is used for associating request with corresponding model instance:
Function expected return valid model instance or None. If None is returned, this makes view set error message using
message_404 attribute and returns redirect to
kwargs len is 1, its assumed to be value of seeked model pk value. This makes function call model manager
get() method to fetch model instance from database. Otherwhise "empty" instance is created and returned instead. Eventual
DoesNotExist errors are handled by
Once model instance is obtained either from database or empty instance is created, this function is called to see intended action is allowed for this request and target. This function is expected to return
None if no issues are found or string containing error message. If string is returned, its set as error messages, and view interrupts its execution by returning redirect to
While target argument value is always present, you don't have to do anything with it if its not making any sense for your view.
In addition, views are wrapped in database transaction. To turn this behaviour off, define
is_atomic attribute with value
Each view calls its
process_context method before rendering template to response. This method accepts two arguments:
request - HttpRequest instance received by view.
context - Dict that is going to be used to render template.
It's required to return dict that will be then used as one of arguments to call
Misago Admin Site is just an hierarchy of pages, made of two parts:
site that contains tree of links and
urlpatterns that is included in
When Misago is started, it scans registered apps for
admin module, just like Django admin does. If module is found, Misago checks if it defines
MisagoAdminExtension class. If such class is found, its instantiated with no arguments, and two of its methods are called:
This function allows apps to register new urlpatterns under
This function allows apps to register new links in admin site navigation.
misago.admin.urlpatterns.URLPatterns available as
urlpatterns argument passed to
register_urlpatterns method. This object exposes two methods as public api:
Registers new namespace in admin links hierarchy.
path - Path prefix for links within this namespace. For example
namespace - Non-prefixed (eg. without
misago:admin part) namespace name.
parent - Optional. Name of parent namespace (eg.
Registers urlpatterns under defined namespace. Expects first argument to be name of namespace that defined links belong to (eg.
users:accounts). Every next argument is expected to be valid Django link created with
url function from
misago:admin prefix of namespaces is implicit. Do not prefix namespaces passed as arguments to those functions with it.
Your urls have to be discoverable by your users. Easiest way is to do this is to display primary link to your admin action in admin site navigation.
misago.admin.hierarchy.AdminHierarchyBuilder class available as
site argument passed to
register_navigation_nodes method of your
MisagoAdminExtension class. It has plenty of functions, but it's public api consists of one method:
add_node(name=None, icon=None, parent='misago:admin', after=None, before=None, namespace=None, link=None)
This method accepts following named arguments:
parent - name of parent namespace under which this action link is displayed.
after - link before which one this one should be displayed.
before - link after which one this one should be displayed.
namespace - this link namespace.
link - link name.
name - link title.
Only last three arguments are required.
before arguments are exclusive. If you specify both, this will result in an error.
Misago Admin supports three levels of hierarchy. Each level should corelate to new namespace nested under
misago:admin. Depending on complexity of your app's admin, it can define links that are one level deep, or three levels deep.
Other way to make your views reachable is to include links to them on items lists. To do this, you may use
add_item_action classmethod of
ListView class that is documented above.