wagtail_alerts
==============
Simple wagtail alerts and toasts to programatically display or to create via settings inside of the wagtail admin.
Quick start
-----------
1. Add 'wagtail_alerts' and it's dependency' to your INSTALLED_APPS setting like this:
```
INSTALLED_APPS = [
...,
'wagtail_alerts',
'globlocks',
]
```
2. Run `py ./manage.py collectstatic`
3. Run `py ./manage.py makemigrations` (We did not do this to prevent the wagtail 5/6 migration errors which might occur.)
4. Run `py ./manage.py migrate`
5. Add the template tags and scripts to your ``<body>``
```
{% load wagtail_alerts_tags %}
<link rel="stylesheet" href="{% url 'wagtail_alerts:css' %}"/>
<script src="{% static 'wagtail_alerts/js/wagtail_alerts.js' %}"></script>
{% wagtail_alerts container_class="fixed fixed-top" %}
{% wagtail_alerts alert_type="TOAST" %}
```
## Custom Alert Types/Templates
You can add your own custom alert types by defining them in settings with `WAGTAIL_ALERTS_TYPES = [...]`
### Example settings
```
# settings.py
WAGTAIL_ALERTS_TYPES = [
("CUSTOM", _("Custom"), "myapp/blocks/my_alert_template.html", "myapp/templatetags/my_custom_list_template.html"),
]
```
### **Example list template**
We must then provide the HTML template to display the list of alerts.
```html
<!-- myapp/templatetags/my_custom_list_template.html -->
<div class="wagtail-alerts {{ CSS_VARIABLE_PREFIX }}custom-container {{ container_class }}">
<div class="{{ CSS_VARIABLE_PREFIX }}custom-wrapper">
{% for alert in alerts %}
{% include_block alert with index=forloop.counter0 %}
{% endfor %}
</div>
</div>
```
#### List Template Context
We provide the following context for your custom alert type list template.
```
{{ alerts }}
{{ settings }}
{{ container_class }}
{{ CSS_VARIABLE_PREFIX }}
```
### Example Alert Template
Following that we can provide the alert template to render the individual alerts which have `alert_type="CUSTOM"`.
```
<!-- myapp/blocks/my_alert_template.html -->
<div class="{{CSS_VARIABLE_PREFIX}}custom-alert {{CSS_VARIABLE_PREFIX}}{{self.settings.alert_theme}}" id="alert-{{ index }}" data-duration="{{ self.settings.duration|default:0 }}" data-cookie-key="{{self.cookie_key}}"{% if self.once_per_session %} data-once{%endif%}{% if self.permanent_dismiss %} data-permanent-dismiss{%endif%}>
<!-- Do something with these attributes! We do not implement this for you. -->
<div class="custom-alert-content">
{% if self.title %}
<div class="alert-title">
{{ self.get_title|safe }}:
</div>
{% endif %}
<div class="alert-text">
{{ self.get_body|safe }}
</div>
</div>
<div class="dismissible-wrapper">
{% if self.settings.dismissible %}
<button type="button" class="alert-dismissible" aria-label="{% translate "Close" %}">×</button>
{% endif %}
</div>
</div>
{% endlocalize %}
```
#### Alert template context
For the full context of your alert template see `blocks.py`.
## Hooks
### Example usage of registering a custom alert from code
We provide hooks to allow you to add your own alerts to the alerts list.
This is useful if you want to add alerts based on some condition in your code.
```python
from wagtail_alerts.alert import Alert
@hooks.register('wagtail_alerts.construct_alerts')
def construct_alerts(request, base_list, settings):
"""
Construct the alerts for the request.
"""
...
if some_condition:
base_list.append(Alert(
title="This is a test alert",
body="This is the test alert body",
alert_theme="primary",
dismissible=True,
duration=5000,
alert_type="TOAST",
))
```
### Example of changing the alert styles
We provide hooks to let you change the styles of the alerts.
This is useful if you want to change the colors of the alerts based on your theme.
```python
from wagtail import hooks
@hooks.register("wagtail_alerts.construct_styles")
def construct_styles(request, styles, settings):
styles.change_color("primary", "#ff0000")
styles.change_theme("dark", "#000000")
styles.PRIMARY.text_color = "#ff0000"
styles.PRIMARY.theme_color = "rgba(0, 0, 0, 0.5)"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Nigel2392/wagtail_alerts",
"name": "wagtail-alerts",
"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/c4/f4/2fa9c72234602b12497e2285fa0dd3fba8e92b54c894245cb43e3e99b8b1/wagtail_alerts-1.0.7.tar.gz",
"platform": null,
"description": "wagtail_alerts\r\n==============\r\n\r\nSimple wagtail alerts and toasts to programatically display or to create via settings inside of the wagtail admin.\r\n\r\nQuick start\r\n-----------\r\n\r\n1. Add 'wagtail_alerts' and it's dependency' to your INSTALLED_APPS setting like this:\r\n\r\n ```\r\n INSTALLED_APPS = [\r\n ...,\r\n 'wagtail_alerts',\r\n 'globlocks',\r\n ]\r\n ```\r\n2. Run `py ./manage.py collectstatic`\r\n3. Run `py ./manage.py makemigrations` (We did not do this to prevent the wagtail 5/6 migration errors which might occur.)\r\n4. Run `py ./manage.py migrate`\r\n5. Add the template tags and scripts to your ``<body>``\r\n\r\n ```\r\n {% load wagtail_alerts_tags %}\r\n <link rel=\"stylesheet\" href=\"{% url 'wagtail_alerts:css' %}\"/>\r\n <script src=\"{% static 'wagtail_alerts/js/wagtail_alerts.js' %}\"></script>\r\n {% wagtail_alerts container_class=\"fixed fixed-top\" %}\r\n {% wagtail_alerts alert_type=\"TOAST\" %}\r\n ```\r\n\r\n## Custom Alert Types/Templates\r\n\r\nYou can add your own custom alert types by defining them in settings with `WAGTAIL_ALERTS_TYPES = [...]`\r\n\r\n### Example settings\r\n\r\n```\r\n# settings.py\r\nWAGTAIL_ALERTS_TYPES = [\r\n (\"CUSTOM\", _(\"Custom\"), \"myapp/blocks/my_alert_template.html\", \"myapp/templatetags/my_custom_list_template.html\"),\r\n]\r\n```\r\n\r\n### **Example list template**\r\n\r\nWe must then provide the HTML template to display the list of alerts.\r\n\r\n```html\r\n<!-- myapp/templatetags/my_custom_list_template.html -->\r\n<div class=\"wagtail-alerts {{ CSS_VARIABLE_PREFIX }}custom-container {{ container_class }}\">\r\n <div class=\"{{ CSS_VARIABLE_PREFIX }}custom-wrapper\">\r\n {% for alert in alerts %}\r\n {% include_block alert with index=forloop.counter0 %}\r\n {% endfor %}\r\n </div>\r\n</div>\r\n\r\n```\r\n\r\n#### List Template Context\r\n\r\nWe provide the following context for your custom alert type list template.\r\n\r\n```\r\n{{ alerts }}\r\n{{ settings }}\r\n{{ container_class }}\r\n{{ CSS_VARIABLE_PREFIX }}\r\n```\r\n\r\n### Example Alert Template\r\n\r\nFollowing that we can provide the alert template to render the individual alerts which have `alert_type=\"CUSTOM\"`.\r\n\r\n```\r\n<!-- myapp/blocks/my_alert_template.html -->\r\n<div class=\"{{CSS_VARIABLE_PREFIX}}custom-alert {{CSS_VARIABLE_PREFIX}}{{self.settings.alert_theme}}\" id=\"alert-{{ index }}\" data-duration=\"{{ self.settings.duration|default:0 }}\" data-cookie-key=\"{{self.cookie_key}}\"{% if self.once_per_session %} data-once{%endif%}{% if self.permanent_dismiss %} data-permanent-dismiss{%endif%}>\r\n <!-- Do something with these attributes! We do not implement this for you. -->\r\n <div class=\"custom-alert-content\">\r\n {% if self.title %}\r\n <div class=\"alert-title\">\r\n {{ self.get_title|safe }}:\r\n </div>\r\n {% endif %}\r\n <div class=\"alert-text\">\r\n {{ self.get_body|safe }}\r\n </div>\r\n </div>\r\n \r\n <div class=\"dismissible-wrapper\">\r\n {% if self.settings.dismissible %}\r\n <button type=\"button\" class=\"alert-dismissible\" aria-label=\"{% translate \"Close\" %}\">\u00d7</button>\r\n {% endif %}\r\n </div>\r\n</div>\r\n{% endlocalize %}\r\n```\r\n\r\n#### Alert template context\r\n\r\nFor the full context of your alert template see `blocks.py`.\r\n\r\n## Hooks\r\n\r\n### Example usage of registering a custom alert from code\r\n\r\nWe provide hooks to allow you to add your own alerts to the alerts list.\r\n\r\nThis is useful if you want to add alerts based on some condition in your code.\r\n\r\n```python\r\nfrom wagtail_alerts.alert import Alert\r\n\r\n@hooks.register('wagtail_alerts.construct_alerts')\r\ndef construct_alerts(request, base_list, settings):\r\n \"\"\"\r\n Construct the alerts for the request.\r\n \"\"\"\r\n\r\n ...\r\n\r\n if some_condition:\r\n base_list.append(Alert(\r\n title=\"This is a test alert\",\r\n body=\"This is the test alert body\",\r\n alert_theme=\"primary\",\r\n dismissible=True,\r\n duration=5000,\r\n alert_type=\"TOAST\",\r\n ))\r\n\r\n\r\n```\r\n\r\n### Example of changing the alert styles\r\n\r\nWe provide hooks to let you change the styles of the alerts.\r\n\r\nThis is useful if you want to change the colors of the alerts based on your theme.\r\n\r\n```python\r\nfrom wagtail import hooks\r\n\r\n\r\n@hooks.register(\"wagtail_alerts.construct_styles\")\r\ndef construct_styles(request, styles, settings):\r\n styles.change_color(\"primary\", \"#ff0000\")\r\n styles.change_theme(\"dark\", \"#000000\")\r\n styles.PRIMARY.text_color = \"#ff0000\"\r\n styles.PRIMARY.theme_color = \"rgba(0, 0, 0, 0.5)\"\r\n\r\n```\r\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "A simple alerts framework for your Wagtail website",
"version": "1.0.7",
"project_urls": {
"Homepage": "https://github.com/Nigel2392/wagtail_alerts"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c4f42fa9c72234602b12497e2285fa0dd3fba8e92b54c894245cb43e3e99b8b1",
"md5": "35a3ac8e09a976b672424487569be114",
"sha256": "dbc9f64c1eab665b68c191ebe8fcdaf2e059244b157e4aea69b7675139d3883e"
},
"downloads": -1,
"filename": "wagtail_alerts-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "35a3ac8e09a976b672424487569be114",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36654,
"upload_time": "2024-03-12T14:29:17",
"upload_time_iso_8601": "2024-03-12T14:29:17.428944Z",
"url": "https://files.pythonhosted.org/packages/c4/f4/2fa9c72234602b12497e2285fa0dd3fba8e92b54c894245cb43e3e99b8b1/wagtail_alerts-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-12 14:29:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Nigel2392",
"github_project": "wagtail_alerts",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wagtail-alerts"
}
JSON
