Note
This document is for model fields and widgets. If you're looking for HTML form input fields, see: User's guide on Input field types <guide/inputs>
.
Contents:
django_jsonform.models.fields
2.0
It is basically a subclass of Django's JSONField
, but for convenience, it automatically sets up the JSON editor widget for you.
In Django < 3.1, for databases other than Postgres, it uses a TextField
underneath.
Parameters:
schema
A dict
or a callable object specifying the schema for the current field.
A callable is useful for specifying dynamic choices <dynamic choices>
.
The callable function may optionally receive the current model instance. See: Accessing model instance in callable schema
.
2.1 The ability to provide a callable was added.
2.8 Callable schema may receive an instance
argument.
pre_save_hook
2.10
(Optional) Sometimes you may wish to transform the JSON data before saving in the database.
For that purpose, you can provide a callable through this argument which will be called before saving the field's value in the database.
The pre_save_hook
callable will receive the current value of the field as the only argument. It must return the value which you intend to save in the database.
def pre_save_hook(value):
# do something with the value ...
return value
class MyModel(...):
items = JSONField(schema=..., pre_save_hook=pre_save_hook)
file_handler
2.11
(Optional) Provide a the url of the view for handling file uploads. See document
on uploading files <file url>
for usage.
**options
This JSONField
accepts all the arguments accepted by Django's JSONField
, such as a custom encoder
or decoder
.
For details about other parameters, options and attributes of the JSONField
, see Django's docs.
Usage:
from django_jsonform.models.fields import JSONField
class MyModel(models.Model):
ITEMS_SCHEMA = {...}
items = JSONField(schema=ITEMS_SCHEMA)
2.0
A subclass of Django's ArrayField
except it renders a dynamic form widget.
It takes exactly the same arguments as the original class.
It also supports multiple levels of array nesting.
Usage:
from django_jsonform.models.fields import ArrayField
class MyModel(models.Model):
items = ArrayField(models.CharField(max_length=50), size=10)
# ...
For more details, see Django's docs.
django_jsonform.forms.fields
2.0
It is a subclass of Django's forms.JSONField
.
Parameters:
schema
A dict
or a callable object.
model_name
(Optional) Name of the model. It is sent along with the AJAX requests to your file handler view.
file_handler
(Optional) Provide a the url of the view for handling file uploads.
**options
It also accepts other options which are accepted by Django's forms.JSONField
.
For details about other parameters, options and attributes, see Django's docs.
Usage:
from django_jsonform.forms.fields import JSONFormField
class MyForm(forms.Form):
my_field = JSONFormField(schema=schema)
django_jsonform.widgets
The widget which renders the editor.
It can be used in a form if you don't want to use the model field.
Parameters:
schema
A dict
or a callable object specifying the schema for the current field.
A callable is useful for specifying dynamic choices <dynamic choices>
.
The callable function may optionally receive the current model instance. See: Accessing model instance in callable schema
.
2.1 The ability to provide a callable was added.
2.8 Callable schema may receive an instance
argument.
model_name
(Optional). The name of the model. It is passed to the file upload handler so that you can identify which model is requesting the file upload.
See Handling file uploads
for more details.
file_handler
2.11
(Optional) Provide a the url of the view for handling file uploads. See document
on uploading files <file url>
for usage.
validate_on_submit
2.12
(Optional) Whether to validate the data on the browser when form is submitted.
Default False
.
See Validating data in browser <validate-on-submit>
for more.
attrs
2.12
(Optional) A dictionary mapping of HTML attributes and values for the widget container element.
Usage:
# admin.py
from django_jsonform.widgets import JSONFormWidget
from myapp.models import ShoppingList
class ShoppingListForm(forms.ModelForm):
class Meta:
model = ShoppingList
fields = '__all__'
widgets = {
'items': JSONFormWidget(schema=ShoppingList.ITEMS_SCHEMA)
}
class ShoppingListAdmin(admin.ModelAdmin):
form = ShoppingListForm
admin.site.register(ShoppingList, ShoppingListAdmin)
This widget can not be used directly with Django's ArrayField
because Django's ArrayField
converts the value from array to a string before passing it to the widget whereas it expects a list or a dict.
2.8
Automatically accessing model instance in a widget is not possible. This is due the way Django initialises the widgets and form fields.
However, you can bypass this limitation by manually setting an instance
attribute on the widget.
To do this, you are required to create a custom form class for your model:
# models.py
def callable_schema(instance=None):
# instance will be None while creating new object
if instance:
# ... do something with the instance ...
else:
# ... do something else ...
return schema
class MyModel(models.Model):
my_field = JSONField(schema=callable_schema)
...
# admin.py
# create a custom modelform
class MyModelForm(forms.ModelForm):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
# manually set the current instance on the widget
self.fields['my_field'].widget.instance = self.instance
# set the form on the admin class
class MyAdmin(admin.ModelAdmin):
form = MyModelForm
admin.site.register(MyModel, MyAdmin)
Your callable schema function will get the current model instance
on Edit/Change admin page. It will be None
on the Add new page (i.e. while creating new objects).
2.19
It is possible to make the whole JSON form readonly dynamically on a per user or per request basis.
This can be done by setting the disabled
attribute on the JSON form field. Note that this attribute is set on the form field itself, not on the field's widget.
You are also required to create a custom form class for your model:
# admin.py
# create a custom modelform
class MyModelForm(forms.ModelForm):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.fields['my_json_field'].disabled = True # disable the field
# set the form on the admin class
class MyAdmin(admin.ModelAdmin):
form = MyModelForm
admin.site.register(MyModel, MyAdmin)
Now the whole form will be rendered in readonly mode.
Security wise this works just as well because the disabled
attribute on a form field tells Django to ignore that field's value on form submission. See also: Django docs on Field.disabled.