https://github.com/brktrlw/django-admin-collaborator
Real-time collaborative editing for Django admin with WebSockets
https://github.com/brktrlw/django-admin-collaborator
admin-interface asgi channels collaboration collaborative-editing concurrent-editing django django-admin exclusive-locking presence presence-indicator python realtime redis websocket websockets
Last synced: 2 months ago
JSON representation
Real-time collaborative editing for Django admin with WebSockets
- Host: GitHub
- URL: https://github.com/brktrlw/django-admin-collaborator
- Owner: Brktrlw
- License: mit
- Created: 2025-04-08T09:37:39.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-05-22T17:24:40.000Z (6 months ago)
- Last Synced: 2025-07-09T01:58:15.804Z (4 months ago)
- Topics: admin-interface, asgi, channels, collaboration, collaborative-editing, concurrent-editing, django, django-admin, exclusive-locking, presence, presence-indicator, python, realtime, redis, websocket, websockets
- Language: JavaScript
- Homepage: https://pypi.org/project/django-admin-collaborator/
- Size: 3.7 MB
- Stars: 51
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-django - django-admin-collaborator - Add real-time user presence, edit locks, and chat to Django admin with Channels and Redis. (Third-Party Packages / Admin)
README
# Django Admin Collaborator
[](https://www.buymeacoffee.com/brktrl)
[](https://badge.fury.io/py/django-admin-collaborator)
[](https://pypi.org/project/django-admin-collaborator/)
[](https://www.djangoproject.com/)
[](https://django-admin-collaborator.readthedocs.io/en/latest/?badge=latest)
[](https://opensource.org/licenses/MIT)
A Django application that enables real-time collaborative editing in the Django admin interface. This package allows multiple admin users to work together while preventing concurrent edits to the same object.
## Features
- ✨ **Real-time Collaborative Editing** - One user can edit while others view in real-time, preventing conflicts
- 🔒 **Edit Lock Management** - Prevents concurrent edits to the same object
- 👥 **User Presence Detection** - See who else is viewing the same object
- 🔔 **Editor Attention System** - Request attention from the current editor
- 💬 **Real-time Chat** - Chat with other users viewing the same page
- 🗣️ **Individual Conversations** - Open separate chat windows for each user
- 👤 **Avatar Support** - Visual user identification with customizable avatars
- 🔌 **Redis Integration** - Reliable lock management and message distribution
- 🔄 **Django Channels** - WebSocket-based real-time communication
- 🛡️ **Connection Resilience** - Automatic retry mechanism for Redis operations with exponential backoff
## Overview
## Requirements
- Django 3.2+
- Django Channels 3.0+
- Redis server
- Python 3.8+
## Installation
1. Install the package using pip:
```bash
pip install django-admin-collaborator
```
2. Add 'django_admin_collaborator' to your INSTALLED_APPS in settings.py:
```python
INSTALLED_APPS = [
...
'channels',
'django_admin_collaborator',
...
]
```
3. Configure your Django Channels layer in settings.py:
```python
CHANNEL_LAYERS = {
'default': {
'BACKEND': 'channels_redis.core.RedisChannelLayer',
'CONFIG': {
'hosts': [('127.0.0.1', 6379)],
},
},
}
```
4. Add the WebSocket routing to your asgi.py:
```python
django_asgi_app = get_asgi_application()
from django_admin_collaborator.routing import websocket_urlpatterns
application = ProtocolTypeRouter({
'http': get_asgi_application(),
'websocket': AuthMiddlewareStack(
URLRouter(
websocket_urlpatterns
)
),
})
```
## Configuration
You can customize the behavior of django-admin-collaborator by adding the following settings to your settings.py:
```python
ADMIN_COLLABORATOR_OPTIONS = {
'editor_mode_text': 'You are in editor mode.',
'viewer_mode_text': 'This page is being edited by {editor_name}. You cannot make changes until they leave.',
'claiming_editor_text': 'The editor has left. The page will refresh shortly to allow editing.',
'avatar_field': None, # Set to a field name in your User model to display avatars
'notification_request_interval': 15, # Seconds between notification requests
'notification_message': 'User {username} is requesting the editors attention.',
'notification_button_text': 'Request Editor Attention',
'notification_request_sent_text': 'Request sent.',
# Chat settings
'enable_chat': True, # Enable/disable the chat feature
'chat_user_list_title': 'Online Users', # Title for the user list panel
'chat_empty_state_text': 'No other users online', # Text when no users are online
'chat_start_conversation_text': 'No messages yet. Start the conversation!', # Text for empty chat
'chat_input_placeholder': 'Type a message...', # Placeholder text for chat input field
'chat_online_status_text': 'Online', # Text for online status indicator
}
ADMIN_COLLABORATOR_ADMIN_URL = 'admin' # Your admin URL prefix
ADMIN_COLLABORATOR_REDIS_URL = 'redis://localhost:6379/0' # Redis connection URL
ADMIN_COLLABORATOR_WEBSOCKET_CONNECTION_PREFIX_URL = 'admin/collaboration' # WebSocket connection URL prefix
# Redis connection resilience settings
ADMIN_COLLABORATOR_REDIS_MAX_RETRIES = 3 # Maximum retry attempts for Redis operations
ADMIN_COLLABORATOR_REDIS_RETRY_DELAY = 0.5 # Delay between retries in seconds (uses exponential backoff)
ADMIN_COLLABORATOR_REDIS_SOCKET_TIMEOUT = 5 # Redis connection timeout in seconds
ADMIN_COLLABORATOR_REDIS_MAX_CONNECTIONS = 10 # Maximum connections in the Redis connection pool
```
## Usage
1. Add the CollaborativeAdminMixin to your ModelAdmin classes:
```python
from django_admin_collaborator.utils import CollaborativeAdminMixin
class YourModelAdmin(CollaborativeAdminMixin, admin.ModelAdmin):
...
```
## Features in Detail
### Edit Lock Management
- Only one user can edit an object at a time
- Automatic lock release when user disconnects
- Visual indication of edit status
- Automatic page refresh when edit lock is released
### Real-time Communication
- WebSocket-based communication for instant updates
- User presence detection
- Editor status broadcasting
- Content update notifications
### Editor Attention System
- Users can request editor's attention
- Configurable notification intervals
- Customizable notification messages
- Visual indicators for attention requests
### Customization Options
- Customizable text messages
- Avatar support for user identification
- Configurable notification intervals
- Customizable admin URL prefix
- Redis connection configuration
## Security
- WebSocket connections are authenticated using Django's authentication system
- Only staff users can access collaborative features
- Redis-based lock management ensures data consistency
- Secure WebSocket communication
## Deployment
### Heroku Deployment
If you're deploying this application on Heroku, ensure that you configure the database connection settings appropriately to optimize performance:
```python
# settings.py
if not DEBUG:
import django_heroku
django_heroku.settings(locals())
DATABASES['default']['CONN_MAX_AGE'] = 0
```
These settings enable automatic retries with exponential backoff when Redis connection errors occur.
## Documentation
For complete documentation, please visit:
- [Read the Docs](https://django-admin-collaborator.readthedocs.io/)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- Django team for their amazing framework
- Channels team for WebSocket support
- All contributors who have helped improve this package
## Support
If you encounter any issues or have questions, please open an issue on the GitHub repository.