# Wagtail Terms
A Wagtail package to add support for a glossary terms entity to Draftail
## Installation
```bash
pip install wagtailterms
```
Add `wagtailterms` to your `INSTALLED_APPS` in your Django settings file.
Make sure you have rest_framework in your installed apps as well.
Migrate the database
```bash
python manage.py migrate
```
Add `wagtailterms.urls` to your `urlpatterns` in your Django urls file.
the url should look like this:
```python
path('api/terms/', include('wagtailterms.urls')),
```
---
#### ⚠️ Note
The url path can be anything you want. This is the url that will be used to access the terms on the frontend
---
## Settings
All configurations for wagtailterms are done in the settings.py file in a dictionary called WAGTAILTERMS.
- icon - The icon for the terms. It is used in the draftail editor and for the viewset. All the icons available for [wagtail](https://docs.wagtail.org/en/latest/advanced_topics/icons.html) are valid options
- menu_order - Change the position of the terms snippet in the menu.
```python
WAGTAILTERMS = {
'icon': 'snippet',
'menu_order': 200
}
```
## Usage
This wagtail package adds a Draftail entity to create a term that is mapped to a definition. The most common use case would be for the user to hover over a word/phrase on a page and a definition would appear next to the word/phrase.
It allows you to Highlight a word/phrase in the Draftail/richtext editor and search for a definition that was created as a TermSnippet. In the editor the term name and definition will appear on top of the phrase when hovering over the phrase.
### Creating new terms
Click in the admin side bar Terms -> Add New
<p align="center" width="100%">
<img width="50%" src="./example/images/create_term_1.png">
</p>
<p align="center" width="100%">
<img width="50%" src="./example/images/create_term_2.png">
</p>
### Use term entity in editor
<p align="center" width="100%">
<img width="50%" src="./example/images/add_term_1.png">
</p>
Search for term
<p align="center" width="100%">
<img width="50%" src="./example/images/add_term_2.png">
</p>
<p align="center" width="100%">
<img width="50%" src="./example/images/search_term.png">
</p>
Select term
<p align="center" width="100%">
<img width="50%" src="./example/images/add_term_3.png">
</p>
Entity displayed in editor
<p align="center" width="100%">
<img width="50%" src="./example/images/add_term_4.png">
</p>
<p align="center" width="100%">
<img width="50%" src="./example/images/basic_term_editor_1.png">
</p>
<p align="center" width="100%">
<img width="50%" src="./example/images/basic_term_editor_2.png">
</p>
### Display in template
To display the terms on the frontend the term shows up as a `<span>` element
tag with a green underline and green text. In a future update this will be customizable.
The element has a data-term attribute that contains the term id. It is up to the developer to fetch
the term and definition to display it. To get the term by id fetch the term by id using the term API.
Rendered HTML of the term in the frontend:
```html
<span style="text-decoration-line: underline; text-decoration-color: green;text-decoration-thickness: 3px;color:green;" data-term="1">term 1</span>
```
The most basic implementation: ([See full example](./example/home/templates/home/basic_page.html))
```javascript
function showterm(e){
const termid = e.target.dataset.term
fetch(`/api/terms/${termid}/`)
.then(response=> response.json())
.then(data => {
alert(`term = ${data.term} \ndefinition = ${data.definition}`)
})
}
for(const term of document.querySelectorAll('[data-term]')){
term.onmouseover=showterm;
}
```
The page would look like this:
<p align="center" width="100%">
<img width="50%" src="./example/images/view_basic_1.png">
</p>
On hover
<p align="center" width="100%">
<img width="50%" src="./example/images/view_basic_2.png">
</p>
A more advanced way would be to use a library like [tippy.js](https://atomiks.github.io/tippyjs/) to
create a tooltip that appears when hovering over the term. ([See full example](./example/home/templates/home/advanced_page.html))
```javascript
function add_tooltips(){
const tips = tippy('[data-term]', {
content: 'Loading...',
allowHTML:true,
interactive:true,
theme:'light',
animation: 'scale-subtle',
onCreate(instance) {
// Setup our own custom state properties
// set if was loaded
instance._fetchInitualized = false;
instance._error = null;
},
onShow(instance) {
if (instance._fetchInitualized || instance._error) {
return;
}
instance._fetchInitualized = true;
fetch(`/api/terms/${instance.reference.dataset.term}/`)
.then(response => response.json())
.then(data => {
if (data.term){
instance.setContent(`<h4>${data.term}</h4><p>${data.definition}</p>`);
}else{
instance.setContent("<p style='color: red'>Could not find definition</p>");
}
})
.catch(error => {
instance._error = error;
instance.setContent(`Request failed. ${error}`);
});
},
});
}
add_tooltips();
```
The page would look like this:
<p align="center" width="100%">
<img width="50%" src="./example/images/view_advanced_1.png">
</p>
On hover
<p align="center" width="100%">
<img width="50%" src="./example/images/view_advanced_2.png">
</p>
## REST API
`/api/terms/` will return:
[
{
"term": "term 1",
"definition": "<p data-block-key=\"51h82\">this is term 1</p>",
"id": 1
},
{
"term": "example 2",
"definition": "<p data-block-key=\"83b17\">this is another example</p>",
"id": 2
}
]
/api/terms/1/ will return:
{
"term": "term 1",
"definition": "<p data-block-key=\"51h82\">this is term 1</p>",
"id": 1
}
## Changelog
### 0.1.1
- added settings to change the icon and menu order.
### 0.1.2
- fixed term search form wider than modal
- Add dark mode support
## To Do
- Allow frontend styles to be changed
- Include a default javascript implementation for frontend
Raw data
{
"_id": null,
"home_page": "https://github.com/smark-1/wagtailterms/",
"name": "wagtailterms",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "wagtail, draftjs, Draftail, picker, term, definition, glossary",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/09/b9/578309fa51397554edce31104c2d11e2f21435de4f7563ec4f6e654fea02/wagtailterms-0.1.2.tar.gz",
"platform": null,
"description": "# Wagtail Terms\nA Wagtail package to add support for a glossary terms entity to Draftail\n\n## Installation\n```bash\npip install wagtailterms\n```\nAdd `wagtailterms` to your `INSTALLED_APPS` in your Django settings file.\nMake sure you have rest_framework in your installed apps as well.\n\nMigrate the database\n```bash\npython manage.py migrate\n```\n\n\nAdd `wagtailterms.urls` to your `urlpatterns` in your Django urls file.\nthe url should look like this:\n```python\npath('api/terms/', include('wagtailterms.urls')),\n```\n\n---\n#### \u26a0\ufe0f Note\n\nThe url path can be anything you want. This is the url that will be used to access the terms on the frontend\n\n---\n\n## Settings\nAll configurations for wagtailterms are done in the settings.py file in a dictionary called WAGTAILTERMS.\n\n- icon - The icon for the terms. It is used in the draftail editor and for the viewset. All the icons available for [wagtail](https://docs.wagtail.org/en/latest/advanced_topics/icons.html) are valid options\n- menu_order - Change the position of the terms snippet in the menu.\n```python\n WAGTAILTERMS = {\n 'icon': 'snippet',\n 'menu_order': 200\n }\n```\n\n## Usage\nThis wagtail package adds a Draftail entity to create a term that is mapped to a definition. The most common use case would be for the user to hover over a word/phrase on a page and a definition would appear next to the word/phrase.\nIt allows you to Highlight a word/phrase in the Draftail/richtext editor and search for a definition that was created as a TermSnippet. In the editor the term name and definition will appear on top of the phrase when hovering over the phrase.\n\n### Creating new terms\nClick in the admin side bar Terms -> Add New\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/create_term_1.png\">\n</p>\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/create_term_2.png\">\n</p>\n\n### Use term entity in editor\n\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/add_term_1.png\">\n</p>\n\nSearch for term\n\n\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/add_term_2.png\">\n</p>\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/search_term.png\">\n</p>\n\nSelect term\n\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/add_term_3.png\">\n</p>\n\nEntity displayed in editor\n\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/add_term_4.png\">\n</p>\n\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/basic_term_editor_1.png\">\n</p>\n\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/basic_term_editor_2.png\">\n</p>\n\n\n### Display in template\nTo display the terms on the frontend the term shows up as a `<span>` element \ntag with a green underline and green text. In a future update this will be customizable. \nThe element has a data-term attribute that contains the term id. It is up to the developer to fetch\nthe term and definition to display it. To get the term by id fetch the term by id using the term API.\n\nRendered HTML of the term in the frontend:\n```html\n<span style=\"text-decoration-line: underline; text-decoration-color: green;text-decoration-thickness: 3px;color:green;\" data-term=\"1\">term 1</span>\n```\n\nThe most basic implementation: ([See full example](./example/home/templates/home/basic_page.html))\n```javascript\nfunction showterm(e){\n const termid = e.target.dataset.term\n fetch(`/api/terms/${termid}/`)\n .then(response=> response.json())\n .then(data => {\n alert(`term = ${data.term} \\ndefinition = ${data.definition}`)\n })\n}\n\nfor(const term of document.querySelectorAll('[data-term]')){\n term.onmouseover=showterm;\n}\n```\nThe page would look like this:\n\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/view_basic_1.png\">\n</p>\n\nOn hover\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/view_basic_2.png\">\n</p>\n\nA more advanced way would be to use a library like [tippy.js](https://atomiks.github.io/tippyjs/) to \ncreate a tooltip that appears when hovering over the term. ([See full example](./example/home/templates/home/advanced_page.html))\n```javascript\nfunction add_tooltips(){\n const tips = tippy('[data-term]', {\n content: 'Loading...',\n allowHTML:true,\n interactive:true,\n theme:'light',\n animation: 'scale-subtle',\n onCreate(instance) {\n // Setup our own custom state properties\n // set if was loaded\n instance._fetchInitualized = false;\n instance._error = null;\n },\n onShow(instance) {\n if (instance._fetchInitualized || instance._error) {\n return;\n }\n\n instance._fetchInitualized = true;\n fetch(`/api/terms/${instance.reference.dataset.term}/`)\n .then(response => response.json())\n .then(data => {\n if (data.term){\n instance.setContent(`<h4>${data.term}</h4><p>${data.definition}</p>`);\n }else{\n instance.setContent(\"<p style='color: red'>Could not find definition</p>\");\n }\n })\n .catch(error => {\n instance._error = error;\n instance.setContent(`Request failed. ${error}`);\n });\n },\n });\n}\nadd_tooltips();\n```\nThe page would look like this:\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/view_advanced_1.png\">\n</p>\n\nOn hover\n<p align=\"center\" width=\"100%\">\n<img width=\"50%\" src=\"./example/images/view_advanced_2.png\">\n</p>\n\n\n## REST API\n`/api/terms/` will return:\n\n [\n {\n \"term\": \"term 1\",\n \"definition\": \"<p data-block-key=\\\"51h82\\\">this is term 1</p>\",\n \"id\": 1\n },\n {\n \"term\": \"example 2\",\n \"definition\": \"<p data-block-key=\\\"83b17\\\">this is another example</p>\",\n \"id\": 2\n }\n ]\n\n/api/terms/1/ will return:\n\n {\n \"term\": \"term 1\",\n \"definition\": \"<p data-block-key=\\\"51h82\\\">this is term 1</p>\",\n \"id\": 1\n }\n\n## Changelog\n### 0.1.1\n- added settings to change the icon and menu order.\n\n### 0.1.2\n- fixed term search form wider than modal\n- Add dark mode support\n\n## To Do\n- Allow frontend styles to be changed\n- Include a default javascript implementation for frontend\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Wagtail plugin to add support for glossary terms entity to Draftail",
"version": "0.1.2",
"project_urls": {
"Download": "https://pypi.python.org/pypi/wagtailterms",
"Homepage": "https://github.com/smark-1/wagtailterms/"
},
"split_keywords": [
"wagtail",
" draftjs",
" draftail",
" picker",
" term",
" definition",
" glossary"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "74f40ff0d7703f23acaa96e857bea8e4b54d5ccecd87f1ed96bb201789bc538d",
"md5": "fd0072d588005a4c19835356372dd11c",
"sha256": "5c3eb9b1fb9e4af5eb9d620b3f307364fccbf686d42cbb086a776987045142eb"
},
"downloads": -1,
"filename": "wagtailterms-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd0072d588005a4c19835356372dd11c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 31960,
"upload_time": "2024-04-12T17:14:34",
"upload_time_iso_8601": "2024-04-12T17:14:34.841483Z",
"url": "https://files.pythonhosted.org/packages/74/f4/0ff0d7703f23acaa96e857bea8e4b54d5ccecd87f1ed96bb201789bc538d/wagtailterms-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "09b9578309fa51397554edce31104c2d11e2f21435de4f7563ec4f6e654fea02",
"md5": "c8be05f80f45af28e50ca62b291d2e6c",
"sha256": "f1bae1f0f1b3195608e5d911d0cfb6de271e1870a0b4a027b92bf189521a50ee"
},
"downloads": -1,
"filename": "wagtailterms-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c8be05f80f45af28e50ca62b291d2e6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31314,
"upload_time": "2024-04-12T17:14:44",
"upload_time_iso_8601": "2024-04-12T17:14:44.325189Z",
"url": "https://files.pythonhosted.org/packages/09/b9/578309fa51397554edce31104c2d11e2f21435de4f7563ec4f6e654fea02/wagtailterms-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 17:14:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smark-1",
"github_project": "wagtailterms",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wagtailterms"
}
JSON
