Source

Django-monitor / docs / source / dev_howto.rst

How to use (for developers)

Registration (Enqueue)

Register the model for moderation using monitor.nq.

Example

import monitor
# Your model here
monitor.nq(YOUR_MODEL)

The full signature is...

monitor.nq(
    model, [rel_fields=[], can_delete_approved=True, manager_name='objects',
    status_name='status', monitor_name='monitor_entry', base_manager=None]
)

model is the only required argument. Other optional arguments follow:

  • rel_fields: List of related fields to be moderated along with this. Read more details below at :ref:`dev_howto_rel_moderation`.
  • can_delete_approved: To prevent admin-users from deleting approved objects, set this to False. Default is True. Read more details below at :ref:`dev_howto_data_protect`.
  • manager_name: We assume that objects is the name of the manager instance of your model. If you want to use a different name for the instance, specify the name with manager_name parameter.
  • status_name: By default, the moderation status field is named as status. If you prefer some other name, specify it.
  • monitor_name: A MonitorEntry object will be created to monitor each object of moderated model. By default, it is referred as monitor_entry. If you prefer some other name, specify it.
  • base_manager: Django-monitor replaces the manager of moderated model with a special manager class derived from the original. Leave this as None if you want to use the default manager class. If you have written a custom manager for the model, you may specify it here.

Special model-admin class

We build admin classes for moderated models using MonitorAdmin instead of django's built-in ModelAdmin. Always remember to inherit from MonitorAdmin when you define model-admin class for your moderated model.

# in your admin.py
from monitor.admin import MonitorAdmin
class YourModelAdmin(MonitorAdmin):
    pass

Data-protection

Business organizations may require their applications to prevent admin users from modifying or deleting approved objects. We allow developers to enable that using two parameters, protected_fields and can_delete_approved.

MonitorAdmin.protected_fields can be used to prevent users from changing values of certain fields in approved objects. Specify the field names as you would do with readonly_fields. See the example below:

# in your admin.py
class YourModelAdmin(MonitorAdmin):
    protected_fields = ['field1', 'field2']

can_delete_approved is an optional parameter you pass to monitor.nq. Its default value is True which allows users to delete all objects. If this is set to False, admin-user can not delete an object once it is approved. Deleting either un-moderated or pending/challenged objects can be done as usual. You still can delete approved objects by code or from the django-shell.

Creation of objects by code

The above sections shared tips on how to prepare your application for moderation by admin-users. What about the objects you create by code? All objects created by code will be in pending status by default. You can moderate them by code using the following public methods of the moderated model:

Note

user is an optional parameter in all those methods described below. Please pass the current user to the methods in all possible cases. request.user can be used for this whenever request is available. Otherwise, you can use get_current_user from monitor.middleware.

  1. approve:
    approve([user = None, notes = ''])
    
  2. challenge:
    challenge([user = None, notes = ''])
    
  3. reset_to_pending:
    reset_to_pending([user = None, notes = ''])
    
  4. moderate (to use when status is available during runtime only):
    moderate(status, [user = None, notes = ''])
    

An example usage

>>> my_inst = MyModel.objects.create(arg1 = 1)
>>> my_inst.approve()

In addition, there are 3 public boolean properties also to let you know which moderation status a particular object is in.

  1. is_approved
  2. is_challenged
  3. is_pending

An example usage

>>> my_inst = MyModel.objects.create()
>>> # Will be in pending status by default.
>>> my_inst.is_approved
... False
>>> my_inst.is_pending
... True
>>> my_inst.approve()
>>> my_inst.is_approved
... True

Post-moderation hook

If you want to perform something after an object is moderated, you can make use of the post_moderation signal as in the below example:

from monitor import post_moderation

# handler_func: function to handle your post moderation activities.
def handler_func(sender, instance, **kwargs):
    # sender: MyModel
    # instance: my_model instance that was just moderated
    pass

# MyModel: The model whose moderation you are watching.
class MyModel(models.Model):
    pass

post_moderation.connect(handler_func, sender = MyModel)

Note that the moderated object will be passed as the instance and its model as the sender. This will help you to write separate handlers for each model.