Metadata-Version: 2.0
Name: django-jsonsuit
Version: 0.3.0
Summary: Django goodies to dress JSON data in a suit.
Home-page: https://github.com/tooreht/django-jsonsuit
Author: Marc Zimmermann
Author-email: tooreht@gmail.com
License: MIT
Keywords: django-jsonsuit
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 1.10
Classifier: Framework :: Django :: 1.11
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: django (>=1.8)

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 }
      }

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.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.


