## Django Admin Page Lock
Page Lock for Django Admin allows developers to implement customizable locking of pages.
With Admin Page Locking, only the designated (typically first) user receives their regular
permissions assigned, including edit permissions (if available for the user).
Subsequent users only get limited permissions compared to those assigned to the first user, making
sure that user will not be granted permission to edit that object while the lock is
active and owned by another user. You can store page lock data in your application's
defined database.
Read more on [our blog](https://tech.showmax.com/2018/02/django-admin-page-lock/).
## Use Case:
1. `FirstUser` lands on a page. `FirstUser` has now full rights (editing), and
it's the owner of the lock.
2. `AnyOtherUser` can view the page, but cannot use full rights (no editing).
3. `FirstUser` leaves the page.
4. Whoever next enters, or refreshes, has now full rights (editing) and is the
owner of the lock.
## Features
* Two models for data storage: `redis` or `database`.
* The developer can disable whole locking functionality.
* Url of a page being locked can be composed with or without url parameters.
* History of locks can be kept (i.e. time, username).
* Very customizable.
## Requirements
* Django 1.8, 1.9, 1.11, 2.0, 2.1, 2.2;
* Python 2.7, 3.6, 3.7, 3.8, 3.9.
## Installation
Each of the following steps needs to be configured for the package to be fully functional.
### Getting the code
The source code is currently hosted on GitHub at: https://github.com/Showmax/django-admin-page-lock
Binary installers for the latest released version are available at the [Python Package Index (PyPI)](https://pypi.org/project/django-admin-page-lock/).
To install it using pip, just run the following:
```bash
pip install django-admin-page-lock
```
### Prerequisites
Make sure to add `'admin_page_lock'` to your `INSTALLED_APPS` setting:
```python
INSTALLED_APPS = [
# ...
'admin_page_lock',
]
```
Don't forget to run `./manage.py migrate` or `./manage.py syncdb` after this change.
## Usage
### Templates
To enable the Admin Page Lock you need to update the template where do you want to
have it working. The templates `base.html`, `change_form.html` and `change_list.html`
should cover most of the use cases.
On the chosen template, you have two options:
1. Add the code bellow to the template, which gives you more freedom to customize it.
```html
{% load static %}
<html>
<head>
<!-- Add the page_lock.js to the template -->
<script src="{% static 'js/page_lock.js' %}"></script>
</head>
<body>
<!-- ... -->
<div id="page_lock_bar">
<div id="page_lock_message_display"></div>
<div id="page_lock_counter_display"></div>
<button type="button" id="page_lock_refresh_button">{% trans "REFRESH" %}</button>
<button type="button" id="page_lock_reload_button">{% trans "RELOAD" %}</button>
<input type="hidden" id="page_lock_template_data" value="{{ page_lock_template_data }}">
<input type="hidden" id="page_lock_api_interval" value="{{ page_lock_api_interval }}">
<!-- ... -->
</body>
</html>
```
2. Use the template tags `page_lock_bar_bootstrap` or `page_lock_bar_plain`.
The javascript is added automatically when using this method.
```html
{% load page_lock_bar_bootstrap %}
...
{% page_lock_bar_bootstrap %}
```
#### Disabling the locking logic
To hide locking buttons for pages where locking logic is not needed,
update the needed templates by adding the javascript block below.
```html
<script type="text/javascript">
$(document).ready(function() {
var api_interval = parseInt($('#page_lock_api_interval').val());
if (!api_interval) {
$('.page_lock_bar').hide();
}
});
</script>
```
#### Hiding specific html items
Add the class `page_lock_block` to any html tag you want to hide from users that are not
currently holding the lock. One common usage for this feature is to hide submit
buttons for users that are not holding the lock, for example:
```html
<div class="page_lock_block">
<input type="submit" value="Submit" />
</div>
```
### Views
Views where you want to apply the locking logic must be inherited, use:
* `PageLockAdminMixin` for Django Admin Views;
* `PageLockViewMixin` for Django Views.
```python
# example/models.py
from django.db import models
from admin_page_lock.mixins import PageLockViewMixin
class Example(PageLockViewMixin, models.Model):
...
# example/admin.py
from admin_page_lock.mixins import PageLockAdminMixin
from django.contrib import admin
from .models import Example
class ExampleAdmin(PageLockAdminMixin, admin.ModelAdmin):
...
```
### Settings parameters
Re-define parameters in your settings if you don't want to use default ones:
| Name | Type | Description |
| ---------------------- | ---------- | -------------------------------------------------- |
| API_INTERVAL | integer | interval between API calls from `js` |
| CAN_OPEN_MORE_TABS | boolean | whether user can open one page in more tabs |
| DISABLE_CRSF_TOKEN | boolean | whether app uses `CSRF` protection |
| DISABLE | boolean | switching off/on locking logic |
| HANDLER_CLASS | string | in case you want to define your handler |
| HOMEPAGE | string | page to redirect user if something goes wrong |
| KEEP_DB_LOCKS | boolean | keep locking history (only for DB model) |
| MESSAGES | dictionary | for customizing messages (not implemented yet) |
| TIMEOUT | integer | interval user stays on the page without refreshing |
| MODEL | string | where data is stored (`redis` or `database`) |
| REDIS_SETTINGS | dictionary | settings of app `redis` |
| URL_IGNORE_PARAMETERS | boolean | whether url parameters are taken into account |
## APIs
Several `APIs` are listed below. These are implemented so that they can be used by both frontend (`js`)
and backend (`python`). The logic is implemented in `handlers.py` and depends on chosen model as well.
At a first glance, one could think that `GetPageInfo` and `OpenPageConnection` are the same, but
the functionality of the first one doesn't change anything while the second one does.
### 1. ClosePageConnection
| Method |Name | Type | Description |
|---------- |------------------- | --------- | ------------------------------------------------- |
| POST | url | string | url of the page |
| POST | user_reference | string | reference of user (`id` or `current section` ) |
| POST | csrf_token | string | generated `csfr` protection token |
| GET | is_locked | boolean | whether the page is locked |
### 2. GetPageInfo
| Method |Name | Type | Description |
|---------- |------------------- | --------- | ------------------------------------------------- |
| POST | url | string | url of the page |
| POST | user_reference | string | reference of user (`id` or `current section` ) |
| POST | csrf_token | string | generated `csfr` protection token |
| GET | is_locked | boolean | whether the page is locked |
| GET | locked_by | string | user_reference of user locking current page |
| GET | page_lock_settings | dictionary| various parameters of settings |
| GET | reconnected | boolean | whether user is reconnected (not implemented yet) |
### 3. OpenPageConnection
| Method |Name | Type | Description |
|---------- |------------------- | --------- | ------------------------------------------------- |
| POST | url | string | url of the page |
| POST | user_reference | string | reference of user (`id` or `current section` ) |
| POST | csrf_token | string | generated `csfr` protection token |
| GET | is_locked | boolean | whether the page is locked |
| GET | locked_by | string | user_reference of user locking current page |
| GET | page_lock_settings | dictionary| various parameters of settings |
| GET | reconnected | boolean | whether user is reconnected (not implemented yet) |
## TODO
There are still several functionalities missing. I would appreciate any contribution.
* writing unit tests;
* finish using `CAN_OPEN_MORE_TABS` settings parameter;
* migrating logic related to reopening from `OpenPageConnection` to new API `ReopenPageConnection`;
## To be implemented soon:
1. User A lands on a page. The page is locked for this user.
2. User B attempts to open the page.
3. User B gets redirected to landing page (homepage, create new, and so on).
## Uses
* At [Showmax](https://tech.showmax.com/), we use this package as part of our Content Management System.
Raw data
{
"_id": null,
"home_page": "https://github.com/ShowMax/django-admin-page-lock",
"name": "django-admin-page-lock",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django,admin,locking,concurrency",
"author": "Vojtech Stefka",
"author_email": "oss+djangopage@showmax.com",
"download_url": "https://files.pythonhosted.org/packages/42/7e/a54d32f3926541f8d9de413f0ffb4ae030ae67fa72ebcf6ef714ca80a057/django-admin-page-lock-2.1.6.tar.gz",
"platform": "any",
"description": "## Django Admin Page Lock\n\nPage Lock for Django Admin allows developers to implement customizable locking of pages.\nWith Admin Page Locking, only the designated (typically first) user receives their regular\npermissions assigned, including edit permissions (if available for the user).\nSubsequent users only get limited permissions compared to those assigned to the first user, making\nsure that user will not be granted permission to edit that object while the lock is\nactive and owned by another user. You can store page lock data in your application's\ndefined database.\n\nRead more on [our blog](https://tech.showmax.com/2018/02/django-admin-page-lock/).\n\n## Use Case:\n1. `FirstUser` lands on a page. `FirstUser` has now full rights (editing), and\n it's the owner of the lock.\n2. `AnyOtherUser` can view the page, but cannot use full rights (no editing).\n3. `FirstUser` leaves the page.\n4. Whoever next enters, or refreshes, has now full rights (editing) and is the\n owner of the lock.\n\n## Features\n* Two models for data storage: `redis` or `database`.\n* The developer can disable whole locking functionality.\n* Url of a page being locked can be composed with or without url parameters.\n* History of locks can be kept (i.e. time, username).\n* Very customizable.\n\n## Requirements\n* Django 1.8, 1.9, 1.11, 2.0, 2.1, 2.2;\n* Python 2.7, 3.6, 3.7, 3.8, 3.9.\n\n## Installation\nEach of the following steps needs to be configured for the package to be fully functional.\n\n### Getting the code\nThe source code is currently hosted on GitHub at: https://github.com/Showmax/django-admin-page-lock\n\nBinary installers for the latest released version are available at the [Python Package Index (PyPI)](https://pypi.org/project/django-admin-page-lock/).\n\nTo install it using pip, just run the following:\n```bash\npip install django-admin-page-lock\n```\n\n\n### Prerequisites\nMake sure to add `'admin_page_lock'` to your `INSTALLED_APPS` setting:\n```python\nINSTALLED_APPS = [\n # ...\n 'admin_page_lock',\n]\n```\nDon't forget to run `./manage.py migrate` or `./manage.py syncdb` after this change.\n\n## Usage\n\n### Templates\nTo enable the Admin Page Lock you need to update the template where do you want to\nhave it working. The templates `base.html`, `change_form.html` and `change_list.html`\nshould cover most of the use cases.\n\nOn the chosen template, you have two options:\n1. Add the code bellow to the template, which gives you more freedom to customize it.\n```html\n{% load static %}\n<html>\n <head>\n <!-- Add the page_lock.js to the template -->\n <script src=\"{% static 'js/page_lock.js' %}\"></script>\n </head>\n <body>\n <!-- ... -->\n <div id=\"page_lock_bar\">\n <div id=\"page_lock_message_display\"></div>\n <div id=\"page_lock_counter_display\"></div>\n <button type=\"button\" id=\"page_lock_refresh_button\">{% trans \"REFRESH\" %}</button>\n <button type=\"button\" id=\"page_lock_reload_button\">{% trans \"RELOAD\" %}</button>\n <input type=\"hidden\" id=\"page_lock_template_data\" value=\"{{ page_lock_template_data }}\">\n <input type=\"hidden\" id=\"page_lock_api_interval\" value=\"{{ page_lock_api_interval }}\">\n <!-- ... -->\n </body>\n</html>\n```\n2. Use the template tags `page_lock_bar_bootstrap` or `page_lock_bar_plain`.\nThe javascript is added automatically when using this method.\n```html\n{% load page_lock_bar_bootstrap %}\n...\n{% page_lock_bar_bootstrap %}\n```\n\n#### Disabling the locking logic\nTo hide locking buttons for pages where locking logic is not needed,\nupdate the needed templates by adding the javascript block below.\n```html\n<script type=\"text/javascript\">\n $(document).ready(function() {\n var api_interval = parseInt($('#page_lock_api_interval').val());\n if (!api_interval) {\n $('.page_lock_bar').hide();\n }\n });\n</script>\n```\n\n#### Hiding specific html items\nAdd the class `page_lock_block` to any html tag you want to hide from users that are not\ncurrently holding the lock. One common usage for this feature is to hide submit\nbuttons for users that are not holding the lock, for example:\n```html\n<div class=\"page_lock_block\">\n <input type=\"submit\" value=\"Submit\" />\n</div>\n```\n\n### Views\nViews where you want to apply the locking logic must be inherited, use:\n* `PageLockAdminMixin` for Django Admin Views;\n* `PageLockViewMixin` for Django Views.\n\n```python\n# example/models.py\nfrom django.db import models\nfrom admin_page_lock.mixins import PageLockViewMixin\n\n\nclass Example(PageLockViewMixin, models.Model):\n ...\n\n# example/admin.py\nfrom admin_page_lock.mixins import PageLockAdminMixin\nfrom django.contrib import admin\nfrom .models import Example\n\n\nclass ExampleAdmin(PageLockAdminMixin, admin.ModelAdmin):\n ...\n```\n \n### Settings parameters\nRe-define parameters in your settings if you don't want to use default ones:\n\n| Name | Type | Description |\n| ---------------------- | ---------- | -------------------------------------------------- |\n| API_INTERVAL | integer | interval between API calls from `js` |\n| CAN_OPEN_MORE_TABS | boolean | whether user can open one page in more tabs |\n| DISABLE_CRSF_TOKEN | boolean | whether app uses `CSRF` protection |\n| DISABLE | boolean | switching off/on locking logic |\n| HANDLER_CLASS | string | in case you want to define your handler |\n| HOMEPAGE | string | page to redirect user if something goes wrong |\n| KEEP_DB_LOCKS | boolean | keep locking history (only for DB model) |\n| MESSAGES | dictionary | for customizing messages (not implemented yet) |\n| TIMEOUT | integer | interval user stays on the page without refreshing |\n| MODEL | string | where data is stored (`redis` or `database`) |\n| REDIS_SETTINGS | dictionary | settings of app `redis` |\n| URL_IGNORE_PARAMETERS | boolean | whether url parameters are taken into account |\n\n## APIs\n\nSeveral `APIs` are listed below. These are implemented so that they can be used by both frontend (`js`)\nand backend (`python`). The logic is implemented in `handlers.py` and depends on chosen model as well.\n\nAt a first glance, one could think that `GetPageInfo` and `OpenPageConnection` are the same, but\nthe functionality of the first one doesn't change anything while the second one does.\n\n### 1. ClosePageConnection\n\n| Method |Name | Type | Description |\n|---------- |------------------- | --------- | ------------------------------------------------- |\n| POST | url | string | url of the page |\n| POST | user_reference | string | reference of user (`id` or `current section` ) |\n| POST | csrf_token | string | generated `csfr` protection token |\n| GET | is_locked | boolean | whether the page is locked |\n\n### 2. GetPageInfo\n\n| Method |Name | Type | Description |\n|---------- |------------------- | --------- | ------------------------------------------------- |\n| POST | url | string | url of the page |\n| POST | user_reference | string | reference of user (`id` or `current section` ) |\n| POST | csrf_token | string | generated `csfr` protection token |\n| GET | is_locked | boolean | whether the page is locked |\n| GET | locked_by | string | user_reference of user locking current page |\n| GET | page_lock_settings | dictionary| various parameters of settings |\n| GET | reconnected | boolean | whether user is reconnected (not implemented yet) |\n\n### 3. OpenPageConnection\n\n| Method |Name | Type | Description |\n|---------- |------------------- | --------- | ------------------------------------------------- |\n| POST | url | string | url of the page |\n| POST | user_reference | string | reference of user (`id` or `current section` ) |\n| POST | csrf_token | string | generated `csfr` protection token |\n| GET | is_locked | boolean | whether the page is locked |\n| GET | locked_by | string | user_reference of user locking current page |\n| GET | page_lock_settings | dictionary| various parameters of settings |\n| GET | reconnected | boolean | whether user is reconnected (not implemented yet) |\n\n\n## TODO\nThere are still several functionalities missing. I would appreciate any contribution.\n* writing unit tests;\n* finish using `CAN_OPEN_MORE_TABS` settings parameter;\n* migrating logic related to reopening from `OpenPageConnection` to new API `ReopenPageConnection`;\n\n## To be implemented soon:\n1. User A lands on a page. The page is locked for this user.\n2. User B attempts to open the page.\n3. User B gets redirected to landing page (homepage, create new, and so on).\n\n## Uses\n* At [Showmax](https://tech.showmax.com/), we use this package as part of our Content Management System.\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Page Lock application prevents users from editing a page while it is being edited by someone else. The application is tailored to django admin implementation.",
"version": "2.1.6",
"split_keywords": [
"django",
"admin",
"locking",
"concurrency"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "427ea54d32f3926541f8d9de413f0ffb4ae030ae67fa72ebcf6ef714ca80a057",
"md5": "fc954bb4aaf43c716541e5fa2da68f12",
"sha256": "9fea3ee4a92272169e906071bd30154fe07d0a209b5e183331d12805365c0fc3"
},
"downloads": -1,
"filename": "django-admin-page-lock-2.1.6.tar.gz",
"has_sig": false,
"md5_digest": "fc954bb4aaf43c716541e5fa2da68f12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22269,
"upload_time": "2023-01-17T08:50:55",
"upload_time_iso_8601": "2023-01-17T08:50:55.685581Z",
"url": "https://files.pythonhosted.org/packages/42/7e/a54d32f3926541f8d9de413f0ffb4ae030ae67fa72ebcf6ef714ca80a057/django-admin-page-lock-2.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-17 08:50:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ShowMax",
"github_project": "django-admin-page-lock",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-admin-page-lock"
}
JSON
