wagtail_showables
=================
An application to easily toggle types of blocks on your frontend from being seen.
It can also be used to limit admins in what they can see and edit - though there is no validation for this due to limitations with wagtail.
Quick start
-----------
1. Add 'wagtail_showables' to your `INSTALLED_APPS` setting like this:
```
INSTALLED_APPS = [
...,
'wagtail_showables',
]
```
2. Add the middleware to your `MIDDLEWARE` to allow for high-performance operations.
```python
MIDDLEWARE = [
"wagtail_showables.middleware.ShowablePerformanceDataMiddleware",
]
```
3. Set the default backend setting `WAGTAIL_SHOWABLES_DEFAULT_BACKEND`
```python
WAGTAIL_SHOWABLES_DEFAULT_BACKEND = "performance_db"
```
4. Run `python manage.py migrate` to create the wagtail_showables models.
5. Run `python manage.py collectstatic` to collect the wagtail_showables static files.
## Options
### WAGTAIL_SHOWABLES_ADMIN_INTERACTION_LEVEL
The level of which the editor can interact with the block.
Options are:
```python
0 # Completely disabled and blurred out from viewing.
1 # Disabled from editing.
2 # Fully enabled
```
Example:
```python
WAGTAIL_SHOWABLES_ADMIN_INTERACTION_LEVEL = 2 # Admins can edit this block.
```
### WAGTAIL_SHOWABLES_DISABLED_DISPLAY_TEXT
The text to display when the block is disabled.
This only has an effect with `ADMIN_INTERACTION_LEVEL` set to 0.
Example:
```python
WAGTAIL_SHOWABLES_DISABLED_DISPLAY_TEXT = "This block is currently disabled."
```
### WAGTAIL_SHOWABLES_DEFAULT_BACKEND
The default backend to use for the showables.
Options are:
```python
"default" # Uses the default backend (caches, but refreshes way more often than the other backends.)
"performance_db" # Uses the database to store the showable data.
"performance_cache" # Uses the cache to store the showable data.
```
## Registering blocks with Wagtail Showables
To register a block with Wagtail Showables, you simply import the register function:
```python
from wagtail_showables.registry import register_block
```
Then, you can use the function to register your block:
```python
# def register_block(block: Type[blocks.StructBlock] = None, label: str = None, help_text: # str = None):
class MyBlock(blocks.StructBlock):
title = blocks.CharBlock()
content = blocks.RichTextBlock()
register_block(MyBlock, label="My Block", help_text="This block gets used in application X and does Y.")
```
It can also be used as a decorator:
```python
@register_block(label="My Block", help_text="This block gets used in application X and does Y.")
class MyBlock(blocks.StructBlock):
title = blocks.CharBlock()
content = blocks.RichTextBlock()
```
You are now set to enable and disable blocks from the admin and users.
Simply head to the admin area, open the settings menu and go to the Showable Blocks menu.
## I want something more.
Do you need something more? Do you need permissions? It gets a little more complex from here.
You will need to implement your own custom backend - we provide a basic backend for is_authenticated.
The backend for pages is relatively easy to implement, this is how we implemented the `requires_authentication` field.
1. Implementing the backend.
```python
from django import forms
from django.http import HttpRequest
from django.utils.translation import gettext_lazy as _
from wagtail_showables.backends import (
BaseShowablePageBackend,
ShowableField,
)
class ShowablePageBackend(BaseShowablePageBackend):
def get_form_fields(self):
"""
Allow for additional logic based on the request and page.
"""
return super().get_form_fields() + [
ShowableField(
name="requires_authentication",
label=_("Requires Authentication"),
field_type=forms.BooleanField,
field_widget=forms.CheckboxInput,
get_initial="requires_authentication",
default_initial=False,
),
]
def check_requires_authentication(self, registry_data: dict, request: HttpRequest, page: "Page", data_key: str) -> bool:
"""
Checks if the user is authenticated.
If not - the block will be hidden.
"""
return request.user.is_authenticated
```
2. Adding the middleware
Add the following middleware to your `settings.py` to allow for proper garbage collection of the showable data
and to allow for the showable blocks to get access to the request and page inside the Wagtail admin.
```python
MIDDLEWARE = [
"wagtail_showables.middleware.ShowablePageAdminMiddleware",
]
```
3. Implementing your page model.
We require you to use a custom page model to use the backend to properly set the data in thread locals.
```python
from wagtail_showables.models import ShowablesPage
class BlogPage(ShowablesPage, Page):
...
```
4. Registering the backend.
Add the import path to your custom backend in your `settings.py` file.
```python
SHOWABLES_DEFAULT_BACKEND = "my_backend"
WAGTAIL_SHOWABLES_BACKEND = {
"my_backend": {
"CLASS": "myapp.backends.MyCustomBackend",
"OPTIONS": {
"my_option": "my_value",
},
}
}
```
You are now set to use your custom backend to control the showable blocks from the wagtailadmin.
Now you will also see your defined field in the wagtailadmin to give you more granular control over the showable blocks.
Raw data
{
"_id": null,
"home_page": "https://github.com/Nigel2392/wagtail_showables",
"name": "wagtail-showables",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Nigel",
"author_email": "nigel@goodadvice.it",
"download_url": "https://files.pythonhosted.org/packages/d0/a7/37463f3df84deb6705266e526c13910401286568501b7a0baa5e39af3c8b/wagtail_showables-1.1.5.tar.gz",
"platform": null,
"description": "wagtail_showables\r\n=================\r\n\r\nAn application to easily toggle types of blocks on your frontend from being seen.\r\n\r\nIt can also be used to limit admins in what they can see and edit - though there is no validation for this due to limitations with wagtail.\r\n\r\nQuick start\r\n-----------\r\n\r\n1. Add 'wagtail_showables' to your `INSTALLED_APPS` setting like this:\r\n\r\n ```\r\n INSTALLED_APPS = [\r\n ...,\r\n 'wagtail_showables',\r\n ]\r\n ```\r\n2. Add the middleware to your `MIDDLEWARE` to allow for high-performance operations.\r\n\r\n ```python\r\n MIDDLEWARE = [\r\n \"wagtail_showables.middleware.ShowablePerformanceDataMiddleware\",\r\n ]\r\n\r\n ```\r\n3. Set the default backend setting `WAGTAIL_SHOWABLES_DEFAULT_BACKEND`\r\n\r\n ```python\r\n WAGTAIL_SHOWABLES_DEFAULT_BACKEND = \"performance_db\"\r\n ```\r\n4. Run `python manage.py migrate` to create the wagtail_showables models.\r\n5. Run `python manage.py collectstatic` to collect the wagtail_showables static files.\r\n\r\n## Options\r\n\r\n### WAGTAIL_SHOWABLES_ADMIN_INTERACTION_LEVEL\r\n\r\nThe level of which the editor can interact with the block.\r\nOptions are:\r\n\r\n```python\r\n0 # Completely disabled and blurred out from viewing.\r\n1 # Disabled from editing.\r\n2 # Fully enabled\r\n```\r\n\r\nExample:\r\n\r\n```python\r\nWAGTAIL_SHOWABLES_ADMIN_INTERACTION_LEVEL = 2 # Admins can edit this block.\r\n```\r\n\r\n### WAGTAIL_SHOWABLES_DISABLED_DISPLAY_TEXT\r\n\r\nThe text to display when the block is disabled.\r\nThis only has an effect with `ADMIN_INTERACTION_LEVEL` set to 0.\r\nExample:\r\n\r\n```python\r\nWAGTAIL_SHOWABLES_DISABLED_DISPLAY_TEXT = \"This block is currently disabled.\"\r\n```\r\n\r\n### WAGTAIL_SHOWABLES_DEFAULT_BACKEND\r\n\r\nThe default backend to use for the showables.\r\nOptions are:\r\n\r\n```python\r\n\"default\" # Uses the default backend (caches, but refreshes way more often than the other backends.)\r\n\"performance_db\" # Uses the database to store the showable data.\r\n\"performance_cache\" # Uses the cache to store the showable data.\r\n```\r\n\r\n## Registering blocks with Wagtail Showables\r\n\r\nTo register a block with Wagtail Showables, you simply import the register function:\r\n\r\n```python\r\nfrom wagtail_showables.registry import register_block\r\n```\r\n\r\nThen, you can use the function to register your block:\r\n\r\n```python\r\n# def register_block(block: Type[blocks.StructBlock] = None, label: str = None, help_text: # str = None):\r\n\r\nclass MyBlock(blocks.StructBlock):\r\n title = blocks.CharBlock()\r\n content = blocks.RichTextBlock()\r\n\r\nregister_block(MyBlock, label=\"My Block\", help_text=\"This block gets used in application X and does Y.\")\r\n```\r\n\r\nIt can also be used as a decorator:\r\n\r\n```python\r\n@register_block(label=\"My Block\", help_text=\"This block gets used in application X and does Y.\")\r\nclass MyBlock(blocks.StructBlock):\r\n title = blocks.CharBlock()\r\n content = blocks.RichTextBlock()\r\n```\r\n\r\nYou are now set to enable and disable blocks from the admin and users.\r\n\r\nSimply head to the admin area, open the settings menu and go to the Showable Blocks menu.\r\n\r\n## I want something more.\r\n\r\nDo you need something more? Do you need permissions? It gets a little more complex from here.\r\n\r\nYou will need to implement your own custom backend - we provide a basic backend for is_authenticated.\r\n\r\nThe backend for pages is relatively easy to implement, this is how we implemented the `requires_authentication` field.\r\n\r\n1. Implementing the backend.\r\n\r\n```python\r\nfrom django import forms\r\nfrom django.http import HttpRequest\r\nfrom django.utils.translation import gettext_lazy as _\r\nfrom wagtail_showables.backends import (\r\n BaseShowablePageBackend,\r\n ShowableField,\r\n)\r\n\r\nclass ShowablePageBackend(BaseShowablePageBackend):\r\n def get_form_fields(self):\r\n \"\"\"\r\n Allow for additional logic based on the request and page.\r\n \"\"\"\r\n return super().get_form_fields() + [\r\n ShowableField(\r\n name=\"requires_authentication\",\r\n label=_(\"Requires Authentication\"),\r\n field_type=forms.BooleanField,\r\n field_widget=forms.CheckboxInput,\r\n get_initial=\"requires_authentication\",\r\n default_initial=False,\r\n ),\r\n ]\r\n \r\n def check_requires_authentication(self, registry_data: dict, request: HttpRequest, page: \"Page\", data_key: str) -> bool:\r\n \"\"\"\r\n Checks if the user is authenticated.\r\n If not - the block will be hidden.\r\n \"\"\"\r\n return request.user.is_authenticated\r\n```\r\n\r\n2. Adding the middleware\r\n\r\nAdd the following middleware to your `settings.py` to allow for proper garbage collection of the showable data \r\nand to allow for the showable blocks to get access to the request and page inside the Wagtail admin.\r\n\r\n```python\r\nMIDDLEWARE = [\r\n \"wagtail_showables.middleware.ShowablePageAdminMiddleware\",\r\n]\r\n```\r\n\r\n3. Implementing your page model.\r\n\r\nWe require you to use a custom page model to use the backend to properly set the data in thread locals.\r\n\r\n```python\r\nfrom wagtail_showables.models import ShowablesPage\r\nclass BlogPage(ShowablesPage, Page):\r\n ...\r\n```\r\n\r\n4. Registering the backend.\r\n\r\nAdd the import path to your custom backend in your `settings.py` file.\r\n\r\n```python\r\nSHOWABLES_DEFAULT_BACKEND = \"my_backend\"\r\nWAGTAIL_SHOWABLES_BACKEND = {\r\n \"my_backend\": {\r\n \"CLASS\": \"myapp.backends.MyCustomBackend\",\r\n \"OPTIONS\": {\r\n \"my_option\": \"my_value\",\r\n },\r\n }\r\n}\r\n```\r\n\r\nYou are now set to use your custom backend to control the showable blocks from the wagtailadmin.\r\nNow you will also see your defined field in the wagtailadmin to give you more granular control over the showable blocks.\r\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "A Wagtail application to disable and enable blocks.",
"version": "1.1.5",
"project_urls": {
"Bug Tracker": "https://github.com/Nigel2392/wagtail_showables/issues",
"Homepage": "https://github.com/Nigel2392/wagtail_showables",
"Source": "https://github.com/Nigel2392/wagtail_showables"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d0a737463f3df84deb6705266e526c13910401286568501b7a0baa5e39af3c8b",
"md5": "0b5ea6fe23eed7a3b2a16152104800b6",
"sha256": "49e22bf500d191bd4e2e5c49bf57237fcf8812082b17b99081460d33b60beef0"
},
"downloads": -1,
"filename": "wagtail_showables-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "0b5ea6fe23eed7a3b2a16152104800b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25734,
"upload_time": "2024-02-20T12:39:00",
"upload_time_iso_8601": "2024-02-20T12:39:00.719360Z",
"url": "https://files.pythonhosted.org/packages/d0/a7/37463f3df84deb6705266e526c13910401286568501b7a0baa5e39af3c8b/wagtail_showables-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-20 12:39:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Nigel2392",
"github_project": "wagtail_showables",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wagtail-showables"
}
JSON
