Update README

README.md

@@ -2,6 +2,11 @@
 
 Django Modal Actions is a reusable Django app that provides a convenient way to add modal-based actions to your Django admin interface. It allows you to create custom actions that open in a modal dialog, enhancing the user experience and functionality of your Django admin.
 
+<p float="left">
+  <img src="screenshots/modal_action_example1.png" width="49%" />
+  <img src="screenshots/modal_action_example2.png" width="49%" /> 
+</p>
+
 ## Features
 
 - Easy integration with Django admin
@@ -23,7 +28,6 @@ Django Modal Actions is a reusable Django app that provides a convenient way to
    ```
 
 2. Add `'django_modal_actions'` to your `INSTALLED_APPS` setting:
-
    ```python
    INSTALLED_APPS = [
        ...
@@ -46,44 +50,107 @@ Django Modal Actions is a reusable Django app that provides a convenient way to
    ```python
    @admin.register(YourModel)
    class YourModelAdmin(ModalActionMixin, admin.ModelAdmin):
-       modal_actions = ["your_object_action"]
-       list_modal_actions = ["your_list_action"]
-
-       @modal_action(modal_header="Object Action")
-       def your_object_action(self, request, obj, form_data=None):
-           # Your object action logic here
-           return "Action completed successfully"
-
-       @modal_action(modal_header="List Action")
-       def your_list_action(self, request, queryset, form_data=None):
-           # Your list action logic here
-           return f"Action completed on {queryset.count()} items"
+       list_display = ['name', 'status']
+       modal_actions = ["approve"]
+       list_modal_actions = ["bulk_approve"]
+
+       @modal_action(
+           modal_header="Approve Item",
+           modal_description="Are you sure you want to approve this item?"
+       )
+       def approve(self, request, obj, form_data=None):
+           obj.status = 'approved'
+           obj.save()
+           return f"{obj} has been approved."
+
+       @modal_action(
+           modal_header="Bulk Approve",
+           modal_description="Are you sure you want to approve the selected items?"
+       )
+       def bulk_approve(self, request, queryset, form_data=None):
+           count = queryset.update(status='approved')
+           return f"{count} items have been approved."
    ```
 
 3. If you need a custom form for your action, create a form class:
 
    ```python
    from django import forms
 
-   class CustomForm(forms.Form):
-       name = forms.CharField(label="Name", required=True)
+   class ApprovalForm(forms.Form):
+       reason = forms.CharField(label="Approval Reason", required=True, widget=forms.Textarea)
 
-       def clean_name(self):
-           name = self.cleaned_data["name"]
-           if name == "bad":
-               raise forms.ValidationError("Name cannot be 'bad'")
-           return name
+       def clean_reason(self):
+           reason = self.cleaned_data["reason"]
+           if len(reason) < 10:
+               raise forms.ValidationError("Reason must be at least 10 characters long")
+           return reason
    ```
 
    Then, use it in your action:
 
    ```python
-   @modal_action(modal_header="Action with Form", form_class=CustomForm)
-   def your_action_with_form(self, request, obj, form_data=None):
-       # Your action logic here
-       return f"Action completed with name: {form_data['name']}"
+   @modal_action(
+       modal_header="Approve with Reason",
+       modal_description="Please provide a reason for approval",
+       form_class=ApprovalForm
+   )
+   def approve_with_reason(self, request, obj, form_data=None):
+       obj.status = 'approved'
+       obj.approval_reason = form_data['reason']
+       obj.save()
+       return f"{obj} has been approved with reason: {form_data['reason']}"
    ```
 
+## Permissions Example
+
+You can add custom permission checks to your modal actions using the `permissions` parameter of the `modal_action` decorator. Here's an example:
+
+```python
+from django.contrib import admin
+from django_modal_actions import ModalActionMixin, modal_action
+from .models import YourModel
+
+def can_approve(request, obj=None):
+    return request.user.has_perm('yourapp.can_approve_items')
+
+@admin.register(YourModel)
+class YourModelAdmin(ModalActionMixin, admin.ModelAdmin):
+    list_display = ['name', 'status']
+    modal_actions = ['approve']
+
+    @modal_action(
+        modal_header="Approve Item",
+        modal_description="Are you sure you want to approve this item?",
+        permissions=can_approve
+    )
+    def approve(self, request, obj, form_data=None):
+        obj.status = 'approved'
+        obj.save()
+        return f"{obj} has been approved."
+```
+
+In this example, the `can_approve` function checks if the user has the `can_approve_items` permission. The `approve` action will only be available to users who have this permission.
+
+You can also use multiple permission checks by passing a list of functions:
+
+```python
+def is_staff(request, obj=None):
+    return request.user.is_staff
+
+@modal_action(
+    modal_header="Approve Item",
+    modal_description="Are you sure you want to approve this item?",
+    permissions=[can_approve, is_staff]
+)
+def approve(self, request, obj, form_data=None):
+    obj.status = 'approved'
+    obj.save()
+    return f"{obj} has been approved."
+```
+
+In this case, the user must both have the `can_approve_items` permission and be a staff member to see and use the approve action.
+
 ## Testing
 
 To run the tests, execute: