=============================
django-reactive
=============================
.. image:: https://badge.fury.io/py/django-reactive.svg
:target: https://badge.fury.io/py/django-reactive
.. image:: https://github.com/tyomo4ka/django-reactive/workflows/CI/badge.svg?branch=master
:target: https://github.com/tyomo4ka/django-reactive/actions
.. image:: https://codecov.io/gh/tyomo4ka/django-reactive/branch/master/graph/badge.svg
:target: https://codecov.io/gh/tyomo4ka/django-reactive
django-reactive integrates `react-jsonschema-form <https://github.com/mozilla-services/react-jsonschema-form>`_ (RJSF)
in Django projects.
Motivation
----------
`JSON types <https://www.postgresql.org/docs/10/datatype-json.html>`_ in Postgres allow combining both relational
and non-relational approaches to storing data. That can lead to a simpler database design in the most cases.
Django provides ORM support for JSON types in Postgres and other databases via the
`JSONField model field <https://docs.djangoproject.com/en/4.1/ref/models/fields/#django.db.models.JSONField>`_. Also the
`JSONField form field <https://docs.djangoproject.com/en/4.1/ref/forms/fields/#jsonfield>`_ allows basic support of JSON in forms.
Django ORM even `allows querying <https://docs.djangoproject.com/en/4.1/topics/db/queries/#querying-jsonfield>`_ against the data stored
inside the JSON structures. Moreover, it is possible to improve performance of these queries using
`GIN indexes <https://www.postgresql.org/docs/15/datatype-json.html#JSON-INDEXING>`_ with **jsonb** types
`in Django <https://docs.djangoproject.com/en/4.1/ref/contrib/postgres/indexes/#ginindex>`_, which
makes opens up a wide range of possibilities for simplifying application design, such as polymorphic collections, storing complex hierarchies in JSON, lists of related entities, etc.
However, the main limitation of JSONField in Django is the lack of good support of UI for JSON structures as defining JSON objects
inside the textarea inputs is not practical for most use cases. django-reactive tries to address this problem by offering an
integration between JSONField and the awesome `react-jsonschema-form <https://github.com/mozilla-services/react-jsonschema-form>`_
(RJSF) JavaScript library.
django-reactive also uses Python `jsonschema <https://github.com/Julian/jsonschema>` library for backend validation. Such integration
can significantly reduce the amount of work needed for building custom forms for JSONField types.
In most cases it only requires a JSON schema configuration for such field and optionally a UI schema
to modify some representation parameters.
A basic example of this is demonstrated below:
.. code-block:: python
from django.db import models
from django_reactive.fields import ReactJSONSchemaField
class Registration(models.Model):
basic = ReactJSONSchemaField(
help_text="Registration form",
schema={
"title": "Register now!",
"description": "Fill out the form to register.",
"type": "object",
"required": [
"firstName",
"lastName"
],
"properties": {
"firstName": {
"type": "string",
"title": "First name"
},
"lastName": {
"type": "string",
"title": "Last name"
},
"age": {
"type": "integer",
"title": "Age"
},
"bio": {
"type": "string",
"title": "Bio"
},
"password": {
"type": "string",
"title": "Password",
"minLength": 3
},
"telephone": {
"type": "string",
"title": "Telephone",
"minLength": 10
}
}
},
ui_schema={
"firstName": {
"ui:autofocus": True,
"ui:emptyValue": ""
},
"age": {
"ui:widget": "updown",
"ui:title": "Age of person",
"ui:description": "(earthian year)"
},
"bio": {
"ui:widget": "textarea"
},
"password": {
"ui:widget": "password",
"ui:help": "Hint: Make it strong!"
},
"date": {
"ui:widget": "alt-datetime"
},
"telephone": {
"ui:options": {
"inputType": "tel"
}
}
},
)
It will generate a form like this:
.. image:: images/simple.png
Quick start
-----------
Install django-reactive::
pip install django-reactive
Add it to your `INSTALLED_APPS`:
.. code-block:: python
INSTALLED_APPS = (
...
'django_reactive',
...
)
Running the example
-------------------
Build the docker image for the Django application in `example/`:
* Run `docker compose up -d`
This will automatically create the database, run migrations, import the default superuser, and run the Django development server on `http://127.0.0.1:8000`.
Django admin example
====================
* Open http://127.0.0.1:8000/admin/ and login with username `admin` and password `test`.
* Go to the "Test models" admin section to see the example forms.
Normal Django view example
==========================
* Open http://127.0.0.1:8000/create/ to create a basic form example.
You will be redirected to the detail view of the created object after the form saves.
Usage outside of Django admin
-----------------------------
To use outside of the Django admin, the following are required in the template:
* A call to the form media property using {{ form.media }}
* An HTML submit input with `name="_save"`.
.. code-block:: html
<!DOCTYPE html>
<html>
<head>
<title>Homepage</title>
</head>
<body>
{{ form.media }}
<form method="post">
{% csrf_token %}
{{ form }}
<input type="submit" value="Save" name="_save">
</form>
</body>
</html>
Optional configuration
----------------------
Schema fields accept the following parameters for additional configuration:
* ``extra_css``: Include additional static CSS files available in the widget.
* ``extra_js``: Include additional static JavaScript files available in the widget.
* ``on_render``: A python method to make dynamic schema modifications at render-time.
Extra CSS and JSS files should be accessible using Django's staticfiles configurations and passed as a list of strings.
Render methods require both ``schema`` and ``ui_schema`` as arguments to allow dynamic schema modification when rendering the widget. An optional ``instance`` keyword argument may also be used for referencing an object instance (must be set on the widget in the form). This method does not return anything.
Example usage
=============
The example below demonstrates a use-case in which the options available for a particular field may be dynamic and unavailable in the initial schema definition. These would be populated at render-time and made available in the form UI.
.. code-block:: python
def set_task_types(schema, ui_schema):
from todos.models import TaskType
task_types = list(TaskType.objects.all().values_list("name", flat=True))
schema["definitions"]["Task"]["properties"]["task_type"]["enum"] = task_types
ui_schema["task_lists"]["items"]["tasks"]["items"]["task_type"][
"ui:help"
] = f"Select 1 of {len(task_types)} task types"
class Todo(models.Model):
"""
A collection of task lists for a todo.
"""
name = models.CharField(max_length=255)
task_lists = ReactJSONSchemaField(
help_text="Task lists",
schema=TODO_SCHEMA,
ui_schema=TODO_UI_SCHEMA,
on_render=set_task_types,
extra_css=["css/extra.css"],
extra_js=["js/extra.js"],
)
Schema model form class
=======================
The form class ``ReactJSONSchemaModelForm`` (subclassed from Django's ``ModelForm``) can be used to provide the model form's instance object to the schema field widgets:
.. code-block:: python
from django_reactive.forms import ReactJSONSchemaModelForm
class MyModelForm(ReactJSONSchemaModelForm):
...
This allows the ``on_render`` method set for a schema field to reference the instance like this:
.. code-block:: python
def update_the_schema(schema, ui_schema, instance=None):
if instance and instance.some_condition:
ui_schema["my_schema_prop"]["ui:help"] = "Some extra help text"
Features
--------
* React, RJSF and other JS assets are bundled with the package.
* Integration with default Django admin theme.
* Backend and frontend validation.
* Configurable static media assets.
* Dynamic schema mutation in widget renders.
Limitations
-----------
* `Additional properties <https://github.com/mozilla-services/react-jsonschema-form#expandable-option>`_ ( a feature of RJSF) is not supported.
To implement this behavior you can define an array schema with one property serving as a key of the object and do
transformation in the Django form.
* An outdated version (1.8) of RJSF is used in this project. Not all features of RJSF 1.8 are compatible with JSON Schema 4.0. Please, refer to the documentation if any issues.
Future development
------------------
* At the moment there is no plans to add new features or support a newer version of RJSF.
* Probably, it is a good idea to replace RJSF with a more Django-friendly solution. It would require significant development effort though, that's why the idea is put on back burner at the moment.
Raw data
{
"_id": null,
"home_page": "https://github.com/tyomo4ka/django-reactive",
"name": "django-reactive",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4",
"maintainer_email": "",
"keywords": "django,postgres,json,jsonschema,react",
"author": "Artem Kolesnikov",
"author_email": "tyomo4ka@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/86/71/9bd9cedef01cf2d179f1da78f873a0572b260f46bd7a7ee504eaf77cb4be/django_reactive-0.0.12.tar.gz",
"platform": null,
"description": "=============================\ndjango-reactive\n=============================\n\n.. image:: https://badge.fury.io/py/django-reactive.svg\n :target: https://badge.fury.io/py/django-reactive\n\n.. image:: https://github.com/tyomo4ka/django-reactive/workflows/CI/badge.svg?branch=master\n :target: https://github.com/tyomo4ka/django-reactive/actions\n\n.. image:: https://codecov.io/gh/tyomo4ka/django-reactive/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/tyomo4ka/django-reactive\n\ndjango-reactive integrates `react-jsonschema-form <https://github.com/mozilla-services/react-jsonschema-form>`_ (RJSF)\nin Django projects.\n\nMotivation\n----------\n\n`JSON types <https://www.postgresql.org/docs/10/datatype-json.html>`_ in Postgres allow combining both relational\nand non-relational approaches to storing data. That can lead to a simpler database design in the most cases.\n\nDjango provides ORM support for JSON types in Postgres and other databases via the\n`JSONField model field <https://docs.djangoproject.com/en/4.1/ref/models/fields/#django.db.models.JSONField>`_. Also the\n`JSONField form field <https://docs.djangoproject.com/en/4.1/ref/forms/fields/#jsonfield>`_ allows basic support of JSON in forms.\nDjango ORM even `allows querying <https://docs.djangoproject.com/en/4.1/topics/db/queries/#querying-jsonfield>`_ against the data stored\ninside the JSON structures. Moreover, it is possible to improve performance of these queries using\n`GIN indexes <https://www.postgresql.org/docs/15/datatype-json.html#JSON-INDEXING>`_ with **jsonb** types\n`in Django <https://docs.djangoproject.com/en/4.1/ref/contrib/postgres/indexes/#ginindex>`_, which\nmakes opens up a wide range of possibilities for simplifying application design, such as polymorphic collections, storing complex hierarchies in JSON, lists of related entities, etc.\n\nHowever, the main limitation of JSONField in Django is the lack of good support of UI for JSON structures as defining JSON objects\ninside the textarea inputs is not practical for most use cases. django-reactive tries to address this problem by offering an\nintegration between JSONField and the awesome `react-jsonschema-form <https://github.com/mozilla-services/react-jsonschema-form>`_\n(RJSF) JavaScript library.\n\ndjango-reactive also uses Python `jsonschema <https://github.com/Julian/jsonschema>` library for backend validation. Such integration\ncan significantly reduce the amount of work needed for building custom forms for JSONField types.\n\nIn most cases it only requires a JSON schema configuration for such field and optionally a UI schema\nto modify some representation parameters.\n\nA basic example of this is demonstrated below:\n\n.. code-block:: python\n\n from django.db import models\n\n from django_reactive.fields import ReactJSONSchemaField\n\n\n class Registration(models.Model):\n basic = ReactJSONSchemaField(\n help_text=\"Registration form\",\n schema={\n \"title\": \"Register now!\",\n \"description\": \"Fill out the form to register.\",\n \"type\": \"object\",\n \"required\": [\n \"firstName\",\n \"lastName\"\n ],\n \"properties\": {\n \"firstName\": {\n \"type\": \"string\",\n \"title\": \"First name\"\n },\n \"lastName\": {\n \"type\": \"string\",\n \"title\": \"Last name\"\n },\n \"age\": {\n \"type\": \"integer\",\n \"title\": \"Age\"\n },\n \"bio\": {\n \"type\": \"string\",\n \"title\": \"Bio\"\n },\n \"password\": {\n \"type\": \"string\",\n \"title\": \"Password\",\n \"minLength\": 3\n },\n \"telephone\": {\n \"type\": \"string\",\n \"title\": \"Telephone\",\n \"minLength\": 10\n }\n }\n },\n ui_schema={\n \"firstName\": {\n \"ui:autofocus\": True,\n \"ui:emptyValue\": \"\"\n },\n \"age\": {\n \"ui:widget\": \"updown\",\n \"ui:title\": \"Age of person\",\n \"ui:description\": \"(earthian year)\"\n },\n \"bio\": {\n \"ui:widget\": \"textarea\"\n },\n \"password\": {\n \"ui:widget\": \"password\",\n \"ui:help\": \"Hint: Make it strong!\"\n },\n \"date\": {\n \"ui:widget\": \"alt-datetime\"\n },\n \"telephone\": {\n \"ui:options\": {\n \"inputType\": \"tel\"\n }\n }\n },\n )\n\nIt will generate a form like this:\n\n.. image:: images/simple.png\n\nQuick start\n-----------\n\nInstall django-reactive::\n\n pip install django-reactive\n\nAdd it to your `INSTALLED_APPS`:\n\n.. code-block:: python\n\n INSTALLED_APPS = (\n ...\n 'django_reactive',\n ...\n )\n\nRunning the example\n-------------------\n\nBuild the docker image for the Django application in `example/`:\n\n* Run `docker compose up -d`\n\nThis will automatically create the database, run migrations, import the default superuser, and run the Django development server on `http://127.0.0.1:8000`.\n\nDjango admin example\n====================\n\n* Open http://127.0.0.1:8000/admin/ and login with username `admin` and password `test`.\n* Go to the \"Test models\" admin section to see the example forms.\n\nNormal Django view example\n==========================\n\n* Open http://127.0.0.1:8000/create/ to create a basic form example.\n\nYou will be redirected to the detail view of the created object after the form saves.\n\nUsage outside of Django admin\n-----------------------------\n\nTo use outside of the Django admin, the following are required in the template:\n\n* A call to the form media property using {{ form.media }}\n\n* An HTML submit input with `name=\"_save\"`.\n\n.. code-block:: html\n\n <!DOCTYPE html>\n <html>\n <head>\n <title>Homepage</title>\n </head>\n <body>\n {{ form.media }}\n <form method=\"post\">\n {% csrf_token %}\n {{ form }}\n <input type=\"submit\" value=\"Save\" name=\"_save\">\n </form>\n </body>\n </html>\n\nOptional configuration\n----------------------\n\nSchema fields accept the following parameters for additional configuration:\n\n* ``extra_css``: Include additional static CSS files available in the widget.\n* ``extra_js``: Include additional static JavaScript files available in the widget.\n* ``on_render``: A python method to make dynamic schema modifications at render-time.\n\nExtra CSS and JSS files should be accessible using Django's staticfiles configurations and passed as a list of strings.\n\nRender methods require both ``schema`` and ``ui_schema`` as arguments to allow dynamic schema modification when rendering the widget. An optional ``instance`` keyword argument may also be used for referencing an object instance (must be set on the widget in the form). This method does not return anything.\n\nExample usage\n=============\n\nThe example below demonstrates a use-case in which the options available for a particular field may be dynamic and unavailable in the initial schema definition. These would be populated at render-time and made available in the form UI.\n\n.. code-block:: python\n\n def set_task_types(schema, ui_schema):\n from todos.models import TaskType\n\n task_types = list(TaskType.objects.all().values_list(\"name\", flat=True))\n schema[\"definitions\"][\"Task\"][\"properties\"][\"task_type\"][\"enum\"] = task_types\n ui_schema[\"task_lists\"][\"items\"][\"tasks\"][\"items\"][\"task_type\"][\n \"ui:help\"\n ] = f\"Select 1 of {len(task_types)} task types\"\n\n class Todo(models.Model):\n \"\"\"\n A collection of task lists for a todo.\n \"\"\"\n\n name = models.CharField(max_length=255)\n task_lists = ReactJSONSchemaField(\n help_text=\"Task lists\",\n schema=TODO_SCHEMA,\n ui_schema=TODO_UI_SCHEMA,\n on_render=set_task_types,\n extra_css=[\"css/extra.css\"],\n extra_js=[\"js/extra.js\"],\n )\n\nSchema model form class\n=======================\n\nThe form class ``ReactJSONSchemaModelForm`` (subclassed from Django's ``ModelForm``) can be used to provide the model form's instance object to the schema field widgets:\n\n.. code-block:: python\n\n from django_reactive.forms import ReactJSONSchemaModelForm\n class MyModelForm(ReactJSONSchemaModelForm):\n ...\n\nThis allows the ``on_render`` method set for a schema field to reference the instance like this:\n\n.. code-block:: python\n\n def update_the_schema(schema, ui_schema, instance=None):\n if instance and instance.some_condition:\n ui_schema[\"my_schema_prop\"][\"ui:help\"] = \"Some extra help text\"\n\nFeatures\n--------\n\n* React, RJSF and other JS assets are bundled with the package.\n* Integration with default Django admin theme.\n* Backend and frontend validation.\n* Configurable static media assets.\n* Dynamic schema mutation in widget renders.\n\nLimitations\n-----------\n\n* `Additional properties <https://github.com/mozilla-services/react-jsonschema-form#expandable-option>`_ ( a feature of RJSF) is not supported.\n\nTo implement this behavior you can define an array schema with one property serving as a key of the object and do\ntransformation in the Django form.\n\n* An outdated version (1.8) of RJSF is used in this project. Not all features of RJSF 1.8 are compatible with JSON Schema 4.0. Please, refer to the documentation if any issues.\n\nFuture development\n------------------\n\n* At the moment there is no plans to add new features or support a newer version of RJSF.\n* Probably, it is a good idea to replace RJSF with a more Django-friendly solution. It would require significant development effort though, that's why the idea is put on back burner at the moment.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django JSON form field on steroids",
"version": "0.0.12",
"split_keywords": [
"django",
"postgres",
"json",
"jsonschema",
"react"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "502022e122dafd035c8b0bd07aa39c9a",
"sha256": "6acc33be78c53fdfa454052a84edaacfd1cf61dd6a376c966b876e74ce163fd5"
},
"downloads": -1,
"filename": "django_reactive-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "502022e122dafd035c8b0bd07aa39c9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4",
"size": 360522,
"upload_time": "2022-12-29T12:01:15",
"upload_time_iso_8601": "2022-12-29T12:01:15.934877Z",
"url": "https://files.pythonhosted.org/packages/e2/2a/0a648e465cb4b2c5dde986b77e43466efeed0679049163153fbc065dd277/django_reactive-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "e6d6b0e69e710e5402f4a5160135e0aa",
"sha256": "c3048fcd2be32c7647d20bbc08566cd8ab06487544073edd96fc861758b481ec"
},
"downloads": -1,
"filename": "django_reactive-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "e6d6b0e69e710e5402f4a5160135e0aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4",
"size": 359182,
"upload_time": "2022-12-29T12:01:17",
"upload_time_iso_8601": "2022-12-29T12:01:17.648324Z",
"url": "https://files.pythonhosted.org/packages/86/71/9bd9cedef01cf2d179f1da78f873a0572b260f46bd7a7ee504eaf77cb4be/django_reactive-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-29 12:01:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "tyomo4ka",
"github_project": "django-reactive",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "django-reactive"
}
JSON
