Django goodies to dress JSON data in a suit.
Project description
django-jsonsuit
===============
|image| |image| |image|
Django goodies to dress JSON data in a suit.
Documentation
-------------
The full documentation is at https://tooreht.github.io/django-jsonsuit.
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``:
.. code:: 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.
JSONSuit
^^^^^^^^
In a form or model admin, enable a JSON suit for a particular field:
.. code:: 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:
.. code:: python
from django.contrib.postgres.fields import JSONField
class JSONAdmin(admin.ModelAdmin):
formfield_overrides = {
JSONField: {'widget': JSONSuit }
}
ReadonlyJSONSuit
^^^^^^^^^^^^^^^^
In a form or model admin, enable a readonly JSON suit for a particular
field:
.. code:: 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:
.. code:: python
from django.contrib.postgres.fields import JSONField
class ReadonlyJSONAdmin(admin.ModelAdmin):
formfield_overrides = {
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 %}``.
.. code:: 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 css class name is generated
to identify each individual suit -->
</div>
<div class="col-md-8">
<h2>Named Suit</h2>
{% jsonsuit data 'suit_name' %} <!-- for each suit,
a css class name
can be supplied -->
</div>
</div>
{% endblock %}
{% block scripts %}
{{ block.super }}
{% jsonsuit_js %} <!-- include jsonsuit js files -->
{% endblock %}
Theme
~~~~~
Set JSON syntax highlighter theme in settings:
.. code:: python
JSONSUIT_WIDGET_THEME = 'twilight'
Available themes: ``coy``, ``dark``, ``default``, ``funky``,
``okaidia``, ``solarizedlight``, ``twilight``. Defaults to the
``default`` theme.
Custom Widget Media
~~~~~~~~~~~~~~~~~~~
Set custom widget media (JS & CSS) files:
.. code:: 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:
.. code:: 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:
.. code:: 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
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 <https://github.com/audreyr/cookiecutter>`__
- `cookiecutter-djangopackage <https://github.com/pydanny/cookiecutter-djangopackage>`__
.. |image| image:: https://badge.fury.io/py/django-jsonsuit.svg
.. |image| image:: https://travis-ci.org/tooreht/django-jsonsuit.svg?branch=master
.. |image| image:: https://codecov.io/gh/tooreht/django-jsonsuit/branch/master/graph/badge.svg
History
-------
Version 0.4.0 (2017-06-18)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Add jsonsuit template tags
Version 0.3.0 (2017-06-02)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Add ReadonlyJSONSuit widget
- Make app settings more modular
- Make JS code more generic (mostly using classes in selectors)
- Use Prism's "default" theme as default
Version 0.2.0 (2017-05-14)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Change JSON syntax highlighter themes
- Set custom widget media (JS & CSS) files
- Use custom HTML template
Version 0.1.0 (2017-05-13)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- First release on PyPI.
===============
|image| |image| |image|
Django goodies to dress JSON data in a suit.
Documentation
-------------
The full documentation is at https://tooreht.github.io/django-jsonsuit.
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``:
.. code:: 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.
JSONSuit
^^^^^^^^
In a form or model admin, enable a JSON suit for a particular field:
.. code:: 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:
.. code:: python
from django.contrib.postgres.fields import JSONField
class JSONAdmin(admin.ModelAdmin):
formfield_overrides = {
JSONField: {'widget': JSONSuit }
}
ReadonlyJSONSuit
^^^^^^^^^^^^^^^^
In a form or model admin, enable a readonly JSON suit for a particular
field:
.. code:: 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:
.. code:: python
from django.contrib.postgres.fields import JSONField
class ReadonlyJSONAdmin(admin.ModelAdmin):
formfield_overrides = {
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 %}``.
.. code:: 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 css class name is generated
to identify each individual suit -->
</div>
<div class="col-md-8">
<h2>Named Suit</h2>
{% jsonsuit data 'suit_name' %} <!-- for each suit,
a css class name
can be supplied -->
</div>
</div>
{% endblock %}
{% block scripts %}
{{ block.super }}
{% jsonsuit_js %} <!-- include jsonsuit js files -->
{% endblock %}
Theme
~~~~~
Set JSON syntax highlighter theme in settings:
.. code:: python
JSONSUIT_WIDGET_THEME = 'twilight'
Available themes: ``coy``, ``dark``, ``default``, ``funky``,
``okaidia``, ``solarizedlight``, ``twilight``. Defaults to the
``default`` theme.
Custom Widget Media
~~~~~~~~~~~~~~~~~~~
Set custom widget media (JS & CSS) files:
.. code:: 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:
.. code:: 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:
.. code:: 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
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 <https://github.com/audreyr/cookiecutter>`__
- `cookiecutter-djangopackage <https://github.com/pydanny/cookiecutter-djangopackage>`__
.. |image| image:: https://badge.fury.io/py/django-jsonsuit.svg
.. |image| image:: https://travis-ci.org/tooreht/django-jsonsuit.svg?branch=master
.. |image| image:: https://codecov.io/gh/tooreht/django-jsonsuit/branch/master/graph/badge.svg
History
-------
Version 0.4.0 (2017-06-18)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Add jsonsuit template tags
Version 0.3.0 (2017-06-02)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Add ReadonlyJSONSuit widget
- Make app settings more modular
- Make JS code more generic (mostly using classes in selectors)
- Use Prism's "default" theme as default
Version 0.2.0 (2017-05-14)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Change JSON syntax highlighter themes
- Set custom widget media (JS & CSS) files
- Use custom HTML template
Version 0.1.0 (2017-05-13)
~~~~~~~~~~~~~~~~~~~~~~~~~~
- First release on PyPI.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
django-jsonsuit-0.4.0.tar.gz
(19.4 kB
view hashes)
Built Distribution
Close
Hashes for django_jsonsuit-0.4.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 11c704ba72840f502522f9b757f1a527c8e3779557eabe986319eb0afd47dce5 |
|
MD5 | 5db374412730e5b954adc2827a17f089 |
|
BLAKE2b-256 | 64fcfcef3322311058c505ded91054ddb2741f67e82b42e86a3feea9a0d47b46 |