Package: django-easy-admin-object-actions
Django easy admin object actionsDjango easy admin object actions is a Django app that allows you easily to add buttons to an object's admin change form page, to perform certain actions on the object.In this documentation, we use the term "object" to refer to the model instance that is being edited in the admin change form.
As an example, we will consider an invoice model that has a status field, and we try to add a button to the change form page that allows us to send the invoice. There are, of course, many other use cases for this app.InstallationInstall using pip:pipinstalldjango-easy-admin-object-actionsAdddjango_easy_admin_object_actionsto yourINSTALLED_APPS:INSTALLED_APPS=[...'django_easy_admin_object_actions',...]Use theObjectActionsMixinin your admin classes:fromdjango.contribimportadminfromdjango_easy_admin_object_actions.adminimportObjectActionsMixinclassMyModelAdmin(ObjectActionsMixin,admin.ModelAdmin):...Implement object actions in your admin classes:fromdjango_easy_admin_object_actions.decoratorsimportobject_actionclassMyModelAdmin(ObjectActionsMixin,admin.ModelAdmin):...@object_action(label="Send invoice",parameter_name="_sendinvoice",)defsend_invoice(self,request,obj):obj.send_invoice()Add the object action to theobject_actions_before_fieldsets,object_actions_after_fieldsets, orobject_actions_after_related_objectsattributes of your admin, depending on where you want the action to appear:classMyModelAdmin(ObjectActionsMixin,admin.ModelAdmin):object_actions_before_fieldsets=["send_invoice"]# Displayed at the top of the page before the change form's fieldsetsobject_actions_after_fieldsets=["send_invoice"]# Displayed at the bottom of the page after the change form's fieldsets, but before any inlines (related objects)object_actions_after_related_objects=["send_invoice"]# Displayed at the bottom of the page after the change form's fieldsets and inlines (related objects), right above the submit rowUsageThere are numerous ways to use this package. Here are some examples:Some models try to emulate some kind of state machine. For example, an invoice model might have astatefield with valuesdraft,sent, andpaid. You can use object actions to implement the transitions between these states. For example, you can add an object action to send an invoice, which will change the status fromdrafttosentand send out an email. You can also add an object action to mark an invoice as paid, which will change the status fromsenttopaid. Here, theconditonargument could be extra useful.You can use object actions to implement a more explicit user interface to perform actions, similar to the functionality Django's default adminactionsalready provides for querysets. Normally these actions are only available in thechangelistview via a dropdown box. With object actions, you can add them to thechangeformview as well.Theconfirmationargument can be used to add an extra confirmation step to an object action. This can be useful if the action is destructive or irreversible.Object actions can be used to easily redirect users to different pages. For example, you could add an object action to redirect users viewing the details of an invoice to a page where they can pay the invoice or view the customer's details in an external CRM:return HttpResponseRedirect('https://crm.example.com/customer/{}'.format(obj.customer.id))Available arguments forobject_actionlabel: The label of the action button.parameter_name: The name of the parameter that is used in the POST body to perform the action. Must be unique. Defaults to the name of the function, for examplesend_invoicewill result in a parameter name of_send_invoice.confirmation: A confirmation message that is alerted to the user when the action is performed. IfNone, no confirmation is required.permission: A permission string that the user should have in order to perform the action. This check is done viarequest.user.has_perm(permission). Note that this doesnotuse the adminhas_<perm>_permission(request, obj)methods that might have been overwritten for your admin.extra_classes: A list of extra classes that are added to the action button. For example,defaultwill make the button appear as a primary button.condition: A function that determines whether the action should be shown. It should take the object and the request as an argument and should return a boolean. If the function returnsFalse, the action cannot be used. For example, you can use this to only show the action if the object is in a certain state:condition=lambda obj, request: obj.state == "draft".display_as_disabled_if_condition_not_met: IfTrue, the action button will be displayed as disabled if the condition is not met. IfFalse, the action button will not be displayed at all if the condition is not met. Defaults toTrue.log_message: A message that is logged when the action is performed. IfNone, no message is logged. For example, you can use this to log the action to the object's history:log_message="Invoice sent".perform_after_saving: IfTrue, the action is performed after any changes made in the object's form are saved. IfFalse, the action is performed before the object is saved. Defaults toFalse.include_in_queryset_actions: IfTrue, the action is also available in thechangelistview via the dropdown box. The action will run on all objects from the selected queryset and report how many were successful (returned a value that evaluates toTrue). IfFalse, the action is only available in thechangeformview. Defaults toTrue.after_queryset_action_callable: A function that is called after the action has been performed on a queryset. It should take the request, the initial selected queryset, and the number of successful actions as arguments. For example, you can use this to redirect the user to a page that shows the results of the action:after_queryset_action_callable=lambda request, queryset, num_successful: HttpResponseRedirect('https://crm.example.com/invoices/?ids={}'.format(','.join([str(obj.id) for obj in queryset]))). Use this callable to report success messages to the user too. Note that this function is only called if the action was performed on a queryset, not if it was performed on a single object. Defaults to a method that shows a simple success message:msg=gettext("Applied '%(action_message)s' on%(count)s%(name)s.")%{"action_message":action.label,"count":count,"name":model_ngettext(self.opts,count),}self.message_user(request,msg,messages.SUCCESS)Return values for object actionsThe actual action should return eitherNone(or not return anything), or aHttpResponseobject. If the action returns aHttpResponseobject, the response is returned to the user instead of the default behavior of redirecting to the object's change page.
This has the following implications:Ifperform_after_savingis set toFalseand your action returns aHttpResponseobject, only the action will be executed, but any changes made in the form willnotbe processed.Ifperform_after_savingis set toFalseand your action returns noHttpResponseobject (likeNoneorFalse), the action will be executed and afterwards, the form data will be processed. This means that the action will be executed even if the form data is invalid. This can result in unexpected behaviour if the action changes the object in a way that is not compatible with the form data.Ifperform_after_savingis set toTrue, first any changes made in the form will be processed and then the action will be executed. Depending on the action's return value, the user will either be redirected to the object's change page or the response returned by the action will be returned to the user. Note that theconditionwill be re-evaluated after the form data is processed, so the action might not actually be performed if the condition is not met anymore!The action's return value is also used to determine whether running the action was successful or not, when the action is performed on a queryset. If the action returns anything else that evaluates toTrue, the action is considered successful. If the action returnsNoneor anything that evaluates toFalse, the action is considered unsuccessful.A good practice would thus be:defreject(self,request,obj):ifnotobj.accepted==False:obj.accepted=Falseobj.save()returnredirect('some_url')returnFalseThis return value will evaluate toTrueif the object was rejected, andFalseif it was already rejected. Moreover, it will redirect if the object was rejected, and not redirect (so stay on the page) if it was already rejected. This way, the user will be redirected to the new page if the action was successful, and will stay on the current page if the action was unsuccessful.