# django-jsonsuit
![image][1] ![image][2] ![image][3]
Django goodies to dress JSON data in a suit.
## Documentation
The full documentation is at <https://tooreht.github.io/django-jsonsuit>.
An example project can be found at <https://github.com/tooreht/django-jsonsuit-example>.
## Features
- Editable and readonly widget
- Change JSON syntax highlighter themes
- Set custom widget media (JS & CSS) files
- Use custom HTML templates
## Quickstart
Install django-jsonsuit:
pip install django-jsonsuit
Add it to your `INSTALLED_APPS`:
``` sourceCode
INSTALLED_APPS = (
...
'jsonsuit.apps.JSONSuitConfig',
...
)
```
## Usage
### Widgets
django-jsonsuit currently provides two widgets to dress your JSON data:
1. `JSONSuit`: Widget that displays JSON data with indentation and syntax highlighting as default, but allows to toggle between the standard django `Textarea` for editing.
2. `ReadonlyJSONSuit`: Widget that simply displays JSON data with indentation and syntax highlighting. It is useful for JSON fields that contain readonly data.
**Note**: Because a widget in django is only responsible for displaying fields, it has no direct access to its field properties. Thus there is no easy way to check if the field is readonly. The readonly behaviour is even handled differently among django forms, model forms and admin. This is why the `ReadonlyJSONSuit` was introduced.
**Note**: When using multiple form instances or multiple forms with equal field names on the same page use [Formsets](https://docs.djangoproject.com/en/dev/topics/forms/formsets/) or [prefixes](https://docs.djangoproject.com/en/dev/ref/forms/api/#prefixes-for-forms) to avoid HTML element id clashes.
#### JSONSuit
In a form or model admin, enable a JSON suit for a particular field:
```python
from jsonsuit.widgets import JSONSuit
class JSONForm(forms.ModelForm):
class Meta:
model = Test
fields = '__all__'
widgets = {
'myjsonfield': JSONSuit(),
}
class JSONAdmin(admin.ModelAdmin):
form = JSONForm
```
Enable JSON suit for every JSONField of a model:
```python
from django.db import models
class JSONAdmin(admin.ModelAdmin):
formfield_overrides = {
models.JSONField: {'widget': JSONSuit }
}
```
#### ReadonlyJSONSuit
In a form or model admin, enable a readonly JSON suit for a particular field:
```python
from jsonsuit.widgets import ReadonlyJSONSuit
class ReadonlyJSONForm(forms.ModelForm):
class Meta:
model = Test
fields = '__all__'
widgets = {
'myjsonfield': ReadonlyJSONSuit(),
}
class ReadonlyJSONAdmin(admin.ModelAdmin):
form = ReadonlyJSONForm
```
Enable readonly JSON suit for every JSONField of a model:
```python
from django.db import models
class ReadonlyJSONAdmin(admin.ModelAdmin):
formfield_overrides = {
models.JSONField: {'widget': ReadonlyJSONSuit }
}
```
### Template Tags
Use the jsonsuit template tag to display serializable objects in templates. Note that in order to use the `jsonsuit`, `jsonsuit_css` and `jsonsuit_js` tags, they must be loaded using `{% load jsonsuit %}`.
```html
{% extends "ui/base.html" %}
{% load jsonsuit %}
{% block title %}{% trans "JSONSuit Template Tag" %}{% endblock %}
{% block styles %}
{{ block.super }}
{% jsonsuit_css %} <!-- include jsonsuit CSS files -->
{% endblock %}
{% block content %}
<div class="row">
<div class="col-md-4">
<h2>Unnamed Suit</h2>
{% jsonsuit data %} <!-- with no parameter supplied,
a uuid is generated as
HTML attribute value to
identify each individual suit:
data-jsonsuit="<uuid>" -->
</div>
<div class="col-md-8">
<h2>Named Suit</h2>
{% jsonsuit data 'suit_name' %} <!-- for each suit,
an optional string
can be supplied, which
serves as HTML attribute
value: data-jsonsuit="<suit_name>" -->
</div>
</div>
{% endblock %}
{% block scripts %}
{{ block.super }}
{% jsonsuit_js %} <!-- include jsonsuit JS files -->
{% endblock %}
```
### Theme
Set JSON syntax highlighter theme in settings:
```python
JSONSUIT_WIDGET_THEME = 'twilight'
```
Available themes: `coy`, `dark`, `default`, `funky`, `okaidia`, `solarizedlight`, `twilight`, `tomorrow`. Defaults to the `default` theme.
### Custom Widget Media
Set custom widget media (JS & CSS) files:
```python
JSONSUIT_WIDGET_MEDIA_JS = (
'jsonsuit/js/mysyntaxhighlighter.js', 'jsonsuit/js/myscripts.js'
)
JSONSUIT_WIDGET_MEDIA_CSS = {
'all': ('jsonsuit/css/mytheme.css', 'jsonsuit/css/mystyles.css')
}
JSONSUIT_READONLY_WIDGET_MEDIA_JS = (
'jsonsuit/js/mysyntaxhighlighter.js', 'jsonsuit/js/myreadonlyscripts.js'
)
JSONSUIT_READONLY_WIDGET_MEDIA_CSS = {
'all': ('jsonsuit/css/mytheme.css', 'jsonsuit/css/myreadonlystyles.css')
}
```
To only replace the syntax highlighter assets for all widgets, simply change:
```python
JSONSUIT_SYNTAX_HIGHLIGHTER_JS = ('jsonsuit/js/mysyntaxhighlighter.js',)
JSONSUIT_SYNTAX_HIGHLIGHTER_CSS = ('jsonsuit/css/mytheme.css',)
```
### Custom HTML template
Override `jsonsuit/widget.html` or `jsonsuit/readonly_widget.html` template:
```bash
jsonsuit/templates
└── jsonsuit
└── widget.html
└── readonly_widget.html
```
## Running Tests
Does the code actually work?
source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install tox
(myenv) $ tox
## Development commands
pip install -r requirements_dev.txt
invoke -l
## Credits
Project dependencies:
- [prism](http://prismjs.com/)
- [vanilla-js](http://vanilla-js.com/)
Project documentation:
- [MkDocs](http://www.mkdocs.org/)
Tools used in rendering this package:
- [Cookiecutter]
- [cookiecutter-djangopackage]
- [Zest.releaser]
[1]: https://badge.fury.io/py/django-jsonsuit.svg
[2]: https://github.com/tooreht/django-jsonsuit/actions/workflows/check.yml/badge.svg?branch=master
[3]: https://codecov.io/gh/tooreht/django-jsonsuit/branch/master/graph/badge.svg
[Cookiecutter]: https://github.com/audreyr/cookiecutter
[cookiecutter-djangopackage]: https://github.com/pydanny/cookiecutter-djangopackage
[Zest.releaser]: https://zestreleaser.readthedocs.io
Raw data
{
"_id": null,
"home_page": "",
"name": "django-jsonsuit",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django-jsonsuit, django, json, suit",
"author": "Marc Zimmermann",
"author_email": "tooreht@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6a/a5/a5636d8d70821d7951e027516ad6eb91674dec6ca3d078cb7bbf0fd13ec2/django-jsonsuit-0.5.0.tar.gz",
"platform": null,
"description": "# django-jsonsuit\n\n![image][1] ![image][2] ![image][3]\n\nDjango goodies to dress JSON data in a suit.\n\n## Documentation\n\nThe full documentation is at <https://tooreht.github.io/django-jsonsuit>. \nAn example project can be found at <https://github.com/tooreht/django-jsonsuit-example>.\n\n## Features\n\n- Editable and readonly widget\n- Change JSON syntax highlighter themes\n- Set custom widget media (JS & CSS) files\n- Use custom HTML templates\n\n## Quickstart\n\nInstall django-jsonsuit:\n\n pip install django-jsonsuit\n\nAdd it to your `INSTALLED_APPS`:\n\n``` sourceCode\nINSTALLED_APPS = (\n ...\n 'jsonsuit.apps.JSONSuitConfig',\n ...\n)\n```\n\n## Usage\n\n### Widgets\n\ndjango-jsonsuit currently provides two widgets to dress your JSON data:\n\n1. `JSONSuit`: Widget that displays JSON data with indentation and syntax highlighting as default, but allows to toggle between the standard django `Textarea` for editing.\n2. `ReadonlyJSONSuit`: Widget that simply displays JSON data with indentation and syntax highlighting. It is useful for JSON fields that contain readonly data.\n\n**Note**: Because a widget in django is only responsible for displaying fields, it has no direct access to its field properties. Thus there is no easy way to check if the field is readonly. The readonly behaviour is even handled differently among django forms, model forms and admin. This is why the `ReadonlyJSONSuit` was introduced.\n\n**Note**: When using multiple form instances or multiple forms with equal field names on the same page use [Formsets](https://docs.djangoproject.com/en/dev/topics/forms/formsets/) or [prefixes](https://docs.djangoproject.com/en/dev/ref/forms/api/#prefixes-for-forms) to avoid HTML element id clashes.\n\n#### JSONSuit\n\nIn a form or model admin, enable a JSON suit for a particular field:\n\n```python\nfrom jsonsuit.widgets import JSONSuit\n\nclass JSONForm(forms.ModelForm):\n class Meta:\n model = Test\n fields = '__all__'\n widgets = {\n 'myjsonfield': JSONSuit(),\n }\n\nclass JSONAdmin(admin.ModelAdmin):\n form = JSONForm\n```\n\nEnable JSON suit for every JSONField of a model:\n\n```python\nfrom django.db import models\n\nclass JSONAdmin(admin.ModelAdmin):\n formfield_overrides = {\n models.JSONField: {'widget': JSONSuit }\n }\n```\n\n#### ReadonlyJSONSuit\n\nIn a form or model admin, enable a readonly JSON suit for a particular field:\n\n```python\nfrom jsonsuit.widgets import ReadonlyJSONSuit\n\nclass ReadonlyJSONForm(forms.ModelForm):\n class Meta:\n model = Test\n fields = '__all__'\n widgets = {\n 'myjsonfield': ReadonlyJSONSuit(),\n }\n\nclass ReadonlyJSONAdmin(admin.ModelAdmin):\n form = ReadonlyJSONForm\n```\n\nEnable readonly JSON suit for every JSONField of a model:\n\n```python\nfrom django.db import models\n\nclass ReadonlyJSONAdmin(admin.ModelAdmin):\n formfield_overrides = {\n models.JSONField: {'widget': ReadonlyJSONSuit }\n }\n```\n\n### Template Tags\n\nUse the jsonsuit template tag to display serializable objects in templates. Note that in order to use the `jsonsuit`, `jsonsuit_css` and `jsonsuit_js` tags, they must be loaded using `{% load jsonsuit %}`. \n\n```html\n{% extends \"ui/base.html\" %}\n{% load jsonsuit %}\n\n{% block title %}{% trans \"JSONSuit Template Tag\" %}{% endblock %}\n\n{% block styles %}\n {{ block.super }}\n {% jsonsuit_css %} <!-- include jsonsuit CSS files -->\n{% endblock %}\n\n{% block content %}\n<div class=\"row\">\n <div class=\"col-md-4\">\n <h2>Unnamed Suit</h2>\n {% jsonsuit data %} <!-- with no parameter supplied,\n a uuid is generated as\n HTML attribute value to\n identify each individual suit:\n data-jsonsuit=\"<uuid>\" -->\n </div>\n <div class=\"col-md-8\">\n <h2>Named Suit</h2>\n {% jsonsuit data 'suit_name' %} <!-- for each suit,\n an optional string\n can be supplied, which\n serves as HTML attribute\n value: data-jsonsuit=\"<suit_name>\" -->\n </div>\n</div>\n{% endblock %}\n\n{% block scripts %}\n {{ block.super }}\n {% jsonsuit_js %} <!-- include jsonsuit JS files -->\n{% endblock %}\n```\n\n### Theme\n\nSet JSON syntax highlighter theme in settings:\n\n```python\nJSONSUIT_WIDGET_THEME = 'twilight'\n```\n\nAvailable themes: `coy`, `dark`, `default`, `funky`, `okaidia`, `solarizedlight`, `twilight`, `tomorrow`. Defaults to the `default` theme.\n\n### Custom Widget Media\n\nSet custom widget media (JS & CSS) files:\n\n```python\nJSONSUIT_WIDGET_MEDIA_JS = (\n 'jsonsuit/js/mysyntaxhighlighter.js', 'jsonsuit/js/myscripts.js'\n)\n\nJSONSUIT_WIDGET_MEDIA_CSS = {\n 'all': ('jsonsuit/css/mytheme.css', 'jsonsuit/css/mystyles.css')\n}\n\nJSONSUIT_READONLY_WIDGET_MEDIA_JS = (\n 'jsonsuit/js/mysyntaxhighlighter.js', 'jsonsuit/js/myreadonlyscripts.js'\n)\n\nJSONSUIT_READONLY_WIDGET_MEDIA_CSS = {\n 'all': ('jsonsuit/css/mytheme.css', 'jsonsuit/css/myreadonlystyles.css')\n}\n```\n\nTo only replace the syntax highlighter assets for all widgets, simply change:\n\n```python\nJSONSUIT_SYNTAX_HIGHLIGHTER_JS = ('jsonsuit/js/mysyntaxhighlighter.js',)\nJSONSUIT_SYNTAX_HIGHLIGHTER_CSS = ('jsonsuit/css/mytheme.css',)\n```\n\n### Custom HTML template\n\nOverride `jsonsuit/widget.html` or `jsonsuit/readonly_widget.html` template:\n\n```bash\njsonsuit/templates\n\u2514\u2500\u2500 jsonsuit\n \u2514\u2500\u2500 widget.html\n \u2514\u2500\u2500 readonly_widget.html\n```\n\n## Running Tests\n\nDoes the code actually work?\n\n source <YOURVIRTUALENV>/bin/activate\n (myenv) $ pip install tox\n (myenv) $ tox\n\n## Development commands\n\n pip install -r requirements_dev.txt\n invoke -l\n\n## Credits\n\nProject dependencies:\n\n- [prism](http://prismjs.com/)\n- [vanilla-js](http://vanilla-js.com/)\n\nProject documentation:\n\n- [MkDocs](http://www.mkdocs.org/)\n\nTools used in rendering this package:\n\n- [Cookiecutter]\n- [cookiecutter-djangopackage]\n- [Zest.releaser]\n\n [1]: https://badge.fury.io/py/django-jsonsuit.svg\n [2]: https://github.com/tooreht/django-jsonsuit/actions/workflows/check.yml/badge.svg?branch=master\n [3]: https://codecov.io/gh/tooreht/django-jsonsuit/branch/master/graph/badge.svg\n [Cookiecutter]: https://github.com/audreyr/cookiecutter\n [cookiecutter-djangopackage]: https://github.com/pydanny/cookiecutter-djangopackage\n [Zest.releaser]: https://zestreleaser.readthedocs.io\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django goodies to dress JSON data in a suit",
"version": "0.5.0",
"split_keywords": [
"django-jsonsuit",
" django",
" json",
" suit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6aa5a5636d8d70821d7951e027516ad6eb91674dec6ca3d078cb7bbf0fd13ec2",
"md5": "35c2df68001e888b17913721485091ed",
"sha256": "86cbe142f4fd6eb8e7eca2682793418b8eeb19aada6ad92812ab3d22a32c1331"
},
"downloads": -1,
"filename": "django-jsonsuit-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "35c2df68001e888b17913721485091ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22026,
"upload_time": "2023-01-20T22:09:08",
"upload_time_iso_8601": "2023-01-20T22:09:08.213587Z",
"url": "https://files.pythonhosted.org/packages/6a/a5/a5636d8d70821d7951e027516ad6eb91674dec6ca3d078cb7bbf0fd13ec2/django-jsonsuit-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-20 22:09:08",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "django-jsonsuit"
}
JSON