# Django Published [](https://pypi.org/project/django-published/)
Published allows you to control the public visibility of model instances.
Useful in situations like below!
You have a model where some number of instances of the model should
be "live". A good example of this would be an Article model, where
you've written some articles that are "live", some that might've
been taken down, some that are still "in progress", and others that
are ready to "go live", but have a "go live" date that's in the
future.
This project is based on [django-model-gatekeeper](https://github.com/WGBH/django-model-gatekeeper) by
[WGBH](https://github.com/WGBH/).
# Getting Started
## Installation
1. Add "published" to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
...
'published',
]
```
## Setting Up Models
The main use for *django-published* is where you have a model with many
instances, but you only want some to be "live" on the site.
A good example is a generic "Article" model:
> - Some articles are ready-to-go and you want them live to the
> public;
> - Other articles are still being worked on - you want to be able to
> preview them, but not take them live JUST yet;
> - Some articles might be pulled (and re-published later)
> - Some articles are ready to be published, but you want them to only
> go live at a later date.
To start using this, all you need to do is subclass the
`PublishedModel` abstract model,
e.g:
```python
from published.models import PublishedModel
class Article(PublishedModel):
...
```
The superclass creates two fields:
1. `publish_status` - this has 3 possible values:
- **NEVER_AVAILABLE** = "permanently off" - hard-wired to NEVER be available to
the public
- **AVAILABLE_AFTER** = "use live_as_of" date to determine if the object is
available to the public
- **AVAILABLE** = "always on" - hard-wired to be always available to the
public
2. `live_as_of` - this is the timestamp of when the object should go live, if publish_status
is **AVAILABLE_AFTER**
You set the `publish_status` and `live_as_of` values through the admin.
# The Frontend
## Generic Model Views
Setting up _django-published_ for generic models views is easy!
Using the Article model as an example, here is the corresponding
view code for listing and detail views.
```python
from django.views.generic import DetailView, ListView
from .models import Article
from published.mixins import PublishedListMixin, PublishedDetailMixin
class ArticleListView(PublishedListMixin, ListView):
model = Article
template_name = 'article/article_list.html'
context_object_name = 'articles'
class ArticleDetailView(PublishedDetailMixin, DetailView):
model = Article
template_name = 'article/article_detail.html'
context_object_name = 'article'
```
What's happening behind the scenes:
1. In the ListView, *django-published* is filtering the model with the
following rules:
1. If the current user has admin access, always include the model instance.
2. If `publish_status = AVAILABLE`, include the model instance.
3. If `publish_status = NEVER_AVAILABLE`, DO NOT the model instance.
4. If `publish_status = AVAILABLE_AFTER`, *and* the current date/time is after
`live_as_of`, include the model instance.
4. Return the filtered list of model instances.
2. In the DetailView, *django-published* follows the same rules but will
throw a 404 error if the model instance is not available.
## Custom Code
Say there's a section on your homepage that gives a list of the three
most recent articles. If you just create a queryset along the lines of:
most_recent_articles = Article.objects.order_by(-date_created)[:3]
it will include articles regardless of what their gatekeeping situation
is.
So there is a helper function to apply the gatekeeping rules to any
queryset you generate.
#### queryset_filter
This takes a queryset, applies the rules and returns a filtered queryset.
```python
from published.utils import queryset_filter
...
recent_articles = Article.objects.order_by('-date_created')
recent_articles = queryset_filter(recent_articles, is_auth)
...
```
By default, `queryset_filter` does not apply the same exceptions as the view
mixins above. This means that unpublished model instances will be *not* displayed
if the current user has admin access.
The optional `user` parameter allows you to enable this special case, as seen below.
```python
queryset_filter(queryset, user=self.request.user)
```
#### available_to_public
**Note**: This should only be used in templates
If you need to check if an object is considered "available" in a Django template, you can use the
`available_to_public` model attribute, as below.
```djangotemplate
{% for article in article_list %}
{% if article.available_to_public %}
I'm published!
{% endif %}
{% endfor %}
```
# The Admin Interface
*django-published* has several helper functions to make adding admin controls easier.
All of them can be found in the `django-published.admin` module.
## Setting Up
All of the below functions require the use of the `PublishedAdmin` abstract class instead
of the default `ModelAdmin` class. You can see examples of this in all of the code below.
Additionally, `add_to_readonly_fields` also needs to be added to `readonly_fields` to provide some of
the fields needed later on.
```python
from published.admin import PublishedAdmin
class ArticleAdmin(PublishedAdmin):
readonly_fields = ['my_field_1', 'my_field_2'] + add_to_readonly_fields()
...
```
## Adding to List View
To show the status in an admin list view, `show_publish_status` needs to be added to
`list_display`
This can be added automatically with the `add_to_list_display` method, e.g.:
```python
from published.admin import PublishedAdmin, add_to_list_display
class ArticleAdmin(PublishedAdmin):
list_display = ['pk', 'title', ] + add_to_list_display()
```
## Adding to Edit View
To add the admin controls to your model, use `add_to_fieldsets`. The `collapse` attribute can be used
to make the controls hidden by default.
```python
from published.admin import PublishedAdmin, add_to_fieldsets
class MyModelAdmin(PublishedAdmin):
fieldsets = (
(None, ...),
add_to_fieldsets(section=True, collapse=False)
)
```
If you don't want to use `add-to_fieldsets`, you can also add the fields manually, with the editable `live_as_of`, `publish_status` fields and the readonly
`show_publish_status` field.
## License
This software is released under the MIT license.
```
Copyright (c) 2019 WGBH Educational Foundation
Copyright (c) 2019-2023 Luke Rogers
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
```
Raw data
{
"_id": null,
"home_page": "https://github.com/dmptrluke/django-published",
"name": "django-published",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Luke Rogers",
"author_email": "luke@dmptr.com",
"download_url": "https://files.pythonhosted.org/packages/85/32/c7984f0ec47f8c05332928dc68ec61162e60a992f31af2a0ab97f7129453/django_published-0.8.0.tar.gz",
"platform": null,
"description": "# Django Published [](https://pypi.org/project/django-published/)\n\nPublished allows you to control the public visibility of model instances.\nUseful in situations like below!\n\n You have a model where some number of instances of the model should\n be \"live\". A good example of this would be an Article model, where\n you've written some articles that are \"live\", some that might've\n been taken down, some that are still \"in progress\", and others that\n are ready to \"go live\", but have a \"go live\" date that's in the\n future.\n\n\nThis project is based on [django-model-gatekeeper](https://github.com/WGBH/django-model-gatekeeper) by\n[WGBH](https://github.com/WGBH/).\n\n# Getting Started\n\n## Installation\n\n1. Add \"published\" to your `INSTALLED_APPS`:\n```python\nINSTALLED_APPS = [\n ...\n 'published',\n]\n```\n\n## Setting Up Models\n\nThe main use for *django-published* is where you have a model with many\ninstances, but you only want some to be \"live\" on the site.\n\nA good example is a generic \"Article\" model:\n\n> - Some articles are ready-to-go and you want them live to the\n> public;\n> - Other articles are still being worked on - you want to be able to\n> preview them, but not take them live JUST yet;\n> - Some articles might be pulled (and re-published later)\n> - Some articles are ready to be published, but you want them to only\n> go live at a later date.\n\nTo start using this, all you need to do is subclass the\n`PublishedModel` abstract model,\ne.g:\n\n```python\nfrom published.models import PublishedModel\n\nclass Article(PublishedModel):\n ...\n```\n\nThe superclass creates two fields:\n\n1. `publish_status` - this has 3 possible values:\n - **NEVER_AVAILABLE** = \"permanently off\" - hard-wired to NEVER be available to\n the public\n - **AVAILABLE_AFTER** = \"use live_as_of\" date to determine if the object is\n available to the public\n - **AVAILABLE** = \"always on\" - hard-wired to be always available to the\n public\n\n\n2. `live_as_of` - this is the timestamp of when the object should go live, if publish_status\n is **AVAILABLE_AFTER**\n\n\n\nYou set the `publish_status` and `live_as_of` values through the admin.\n\n# The Frontend\n\n## Generic Model Views\n\nSetting up _django-published_ for generic models views is easy!\n\nUsing the Article model as an example, here is the corresponding\nview code for listing and detail views.\n\n```python\nfrom django.views.generic import DetailView, ListView\nfrom .models import Article\nfrom published.mixins import PublishedListMixin, PublishedDetailMixin\n\nclass ArticleListView(PublishedListMixin, ListView):\n model = Article\n template_name = 'article/article_list.html'\n context_object_name = 'articles'\n\nclass ArticleDetailView(PublishedDetailMixin, DetailView):\n model = Article\n template_name = 'article/article_detail.html'\n context_object_name = 'article'\n```\n\n\nWhat's happening behind the scenes:\n\n1. In the ListView, *django-published* is filtering the model with the\n following rules:\n\n 1. If the current user has admin access, always include the model instance.\n 2. If `publish_status = AVAILABLE`, include the model instance.\n 3. If `publish_status = NEVER_AVAILABLE`, DO NOT the model instance.\n 4. If `publish_status = AVAILABLE_AFTER`, *and* the current date/time is after\n `live_as_of`, include the model instance.\n 4. Return the filtered list of model instances.\n\n2. In the DetailView, *django-published* follows the same rules but will\n throw a 404 error if the model instance is not available.\n\n## Custom Code\n\nSay there's a section on your homepage that gives a list of the three\nmost recent articles. If you just create a queryset along the lines of:\n\n most_recent_articles = Article.objects.order_by(-date_created)[:3]\n\nit will include articles regardless of what their gatekeeping situation\nis.\n\nSo there is a helper function to apply the gatekeeping rules to any\nqueryset you generate.\n\n#### queryset_filter\nThis takes a queryset, applies the rules and returns a filtered queryset.\n\n```python\nfrom published.utils import queryset_filter\n...\nrecent_articles = Article.objects.order_by('-date_created')\nrecent_articles = queryset_filter(recent_articles, is_auth)\n...\n```\n\n\nBy default, `queryset_filter` does not apply the same exceptions as the view\nmixins above. This means that unpublished model instances will be *not* displayed\nif the current user has admin access.\n\nThe optional `user` parameter allows you to enable this special case, as seen below.\n```python\nqueryset_filter(queryset, user=self.request.user)\n```\n\n#### available_to_public\n\n**Note**: This should only be used in templates\n\nIf you need to check if an object is considered \"available\" in a Django template, you can use the\n`available_to_public` model attribute, as below.\n\n```djangotemplate\n{% for article in article_list %}\n {% if article.available_to_public %}\n I'm published!\n {% endif %}\n{% endfor %}\n```\n\n# The Admin Interface\n\n*django-published* has several helper functions to make adding admin controls easier.\nAll of them can be found in the `django-published.admin` module.\n\n\n\n## Setting Up\nAll of the below functions require the use of the `PublishedAdmin` abstract class instead\nof the default `ModelAdmin` class. You can see examples of this in all of the code below.\n\nAdditionally, `add_to_readonly_fields` also needs to be added to `readonly_fields` to provide some of \nthe fields needed later on.\n\n```python\nfrom published.admin import PublishedAdmin\n\nclass ArticleAdmin(PublishedAdmin):\n readonly_fields = ['my_field_1', 'my_field_2'] + add_to_readonly_fields()\n ...\n```\n\n## Adding to List View\n\nTo show the status in an admin list view, `show_publish_status` needs to be added to\n`list_display`\n\nThis can be added automatically with the `add_to_list_display` method, e.g.:\n\n```python\nfrom published.admin import PublishedAdmin, add_to_list_display\n\nclass ArticleAdmin(PublishedAdmin):\n list_display = ['pk', 'title', ] + add_to_list_display()\n```\n\n## Adding to Edit View\n\nTo add the admin controls to your model, use `add_to_fieldsets`. The `collapse` attribute can be used \nto make the controls hidden by default.\n\n```python\nfrom published.admin import PublishedAdmin, add_to_fieldsets\n\nclass MyModelAdmin(PublishedAdmin):\n fieldsets = (\n (None, ...),\n add_to_fieldsets(section=True, collapse=False)\n )\n```\n\nIf you don't want to use `add-to_fieldsets`, you can also add the fields manually, with the editable `live_as_of`, `publish_status` fields and the readonly\n`show_publish_status` field.\n\n## License\n\nThis software is released under the MIT license.\n```\nCopyright (c) 2019 WGBH Educational Foundation\nCopyright (c) 2019-2023 Luke Rogers\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Control public visibility of model instances.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/dmptrluke/django-published"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d4a3aca4e18214071088b02562451aebd76cdc569f1073d4da14a9672aa33c04",
"md5": "798c61906af6e1b66738db75fdd4b553",
"sha256": "cee160af42925d81048206bd7cf586a8c1e5bb66a36151bff2e0d8baf341e769"
},
"downloads": -1,
"filename": "django_published-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "798c61906af6e1b66738db75fdd4b553",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13458,
"upload_time": "2023-08-31T01:39:17",
"upload_time_iso_8601": "2023-08-31T01:39:17.802149Z",
"url": "https://files.pythonhosted.org/packages/d4/a3/aca4e18214071088b02562451aebd76cdc569f1073d4da14a9672aa33c04/django_published-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8532c7984f0ec47f8c05332928dc68ec61162e60a992f31af2a0ab97f7129453",
"md5": "ad1bf6c5dc947f5d2a9ddabfeb3ad306",
"sha256": "bd0d00fa8c47e763b0a12225cdedbce52cf6ccb25ae98e8f8c4c1582c1e52ff7"
},
"downloads": -1,
"filename": "django_published-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "ad1bf6c5dc947f5d2a9ddabfeb3ad306",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29748,
"upload_time": "2023-08-31T01:39:22",
"upload_time_iso_8601": "2023-08-31T01:39:22.248925Z",
"url": "https://files.pythonhosted.org/packages/85/32/c7984f0ec47f8c05332928dc68ec61162e60a992f31af2a0ab97f7129453/django_published-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-31 01:39:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dmptrluke",
"github_project": "django-published",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-published"
}
JSON
