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()