Django Widget¶
Settings¶
The minimal configuration for a Django project using Uploadcare looks like this:
UPLOADCARE = {
"pub_key": "<your public key>",
"secret": "<your private key>",
}
You can generate these keys in your project settings on the Uploadcare dashboard.
In addition to the required settings pub_key and secret, there are several optional settings available.
Below is the full default configuration:
UPLOADCARE = {
"pub_key": "",
"secret": "",
"cdn_base": None,
"upload_base_url": None,
"signed_uploads": False,
"use_legacy_widget": False,
"use_hosted_assets": True,
"widget": {
"version": "0.36.0",
"variant": "regular",
"build": "min",
"options": {},
"override_js_url": None,
"override_css_url": {
"regular": None,
"inline": None,
"minimal": None,
},
},
"legacy_widget": {
"version": "3.x",
"build": "full.min",
"override_js_url": None,
},
}
PyUploadcare takes assets from CDN by default, e.g.:
<script type="module">
import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.x/web/blocks.min.js";
LR.registerBlocks(LR);
</script>
<!-- ... -->
<lr-file-uploader-inline
css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.x/web/lr-file-uploader-regular.min.css"
ctx-name="my-uploader"
></lr-file-uploader-inline>
If you don’t want to use hosted assets you have to turn off this feature:
UPLOADCARE = {
# ...
"use_hosted_assets": False,
}
In this case local assets will be used.
If you want to provide custom url for assets then you have to specify widget url:
UPLOADCARE = {
# ...
"widget": {
"override_js_url": "http://path.to/your/blocks.js",
"override_css_url": {
"regular": "http://path.to/your/lr-file-uploader-regular.css",
"inline": "http://path.to/your/lr-file-uploader-inline.css",
"minimal": "http://path.to/your/lr-file-uploader-minimal.css",
},
},
}
Uploadcare widget will use default upload handler url, unless you specify:
UPLOADCARE = {
# ...
"upload_base_url": "http://path.to/your/upload/handler",
}
Use widget_options
to pass arbitrary options to the file uploader:
UPLOADCARE = {
# ...
"widget": {
"options": {
"source-list": "local,url,camera",
"camera-mirror": True,
},
},
}
Settings for legacy widget¶
If you want to use our legacy jQuery-widget, you can enable it in settings:
UPLOADCARE = {
"pub_key": "<your public key>",
"secret": "<your private key>",
"use_legacy_widget": True,
}
Settings that are specific to the legacy widget are prefixed with legacy_
:
UPLOADCARE = {
# ...
"use_legacy_widget": True,
"legacy_widget": {
"version": "3.x", # ~= 3.0 (latest)
"build": "min", # without jQuery
"override_js_url": "http://path.to/your/uploadcare.js",
},
}
If you have signed uploads enabled in your Uploadcare project, widget-based uploads will fail unless you enable the signed_uploads
setting in your Django project:
UPLOADCARE = {
# ...,
'signed_uploads': True,
}
Model Fields¶
As you will see, with Uploadcare, adding and working with a file field is just as simple as with a TextField. To attach Uploadcare files to a model, you can use a FileField or ImageField. These fields play by common Django rules. South migrations are supported.
Note
When you call your_model_form.is_valid()
or call photo.full_clean()
directly it invokes File.store()
method automatically. In other cases
you should store objects manually, e.g:
photo.photo_2x3 = File("a771f854-c2cb-408a-8c36-71af77811f3b")
photo.save()
photo.photo_2x3.store()
FileField¶
FileField
does not require an uploaded file to be any certain format.
from django.db import models
from pyuploadcare.dj.models import FileField
class Candidate(models.Model):
resume = FileField()
ImageField¶
ImageField
requires an uploaded file to be an image. An optional parameter
manual_crop
enables, if specified, a manual cropping tool: your user can
select a part of an image she wants to use. If its value is an empty string,
the user can select any part of an image; you can also use values like
"3:4"
or "200x300"
to get exact proportions or dimensions of resulting
image. Consult widget documentation regarding setting up the manual crop:
from django.db import models
from pyuploadcare.dj.models import ImageField
class Candidate(models.Model):
photo = ImageField(blank=True, manual_crop="")
Advanced widget options¶
You can pass any widget options via FileWidget
’s attrs argument:
from django import forms
from pyuploadcare.dj.forms import FileWidget, ImageField
# Optional: provide advanced widget options https://uploadcare.com/docs/file-uploader/options/
class CandidateForm(forms.Form):
photo = ImageField(widget=FileWidget(attrs={
"source-list": "local,url,camera",
"camera-mirror": True,
}))
Use LegacyFileWidget
whenever you want to switch back to jQuery-based
widget on a field-by-field basis without turning it on globally (using
"use_legacy_widget": True
).
from django import forms
from pyuploadcare.dj.forms import LegacyFileWidget, ImageField
class CandidateForm(forms.Form):
photo = ImageField(widget=LegacyFileWidget)
FileGroupField¶
FileGroupField
allows you to upload more than one file at a time. It stores
uploaded files as a group:
from django.db import models
from pyuploadcare.dj.models import FileGroupField
class Book(models.Model):
pages = FileGroupField()
ImageGroupField¶
ImageGroupField
allows you to upload more than one image at a time.
It stores uploaded images as a group:
from django.db import models
from pyuploadcare.dj.models import ImageGroupField
class Gallery(models.Model):
photos = ImageGroupField()