Integrating Uploadcare into Django is about adding a File Field to an existing Django project in a couple of simple steps. That will enable your users to see the progress of their uploads, pick files from social media and cloud storage, and keep editing a form while files a being uploaded asynchronously.

Requirements

Install

It all starts with installing a pyuploadcare package. Head to pip for that:

pip install pyuploadcare

Configuration

Open settings.py and add a dictionary holding your API keys. If you don’t have an account, feel free to use our demo keys (see example below) for testing purposes. Keep in mind that we delete all files from our demo account every few hours.

UPLOADCARE = {# Don’t forget to set real keys when it gets real :)

'pub_key': 'demopublickey','secret': 'demoprivatekey',}

Usage

Adding media to a model via Uploadcare is about using FileField, FileGroupField, ImageField or ImageGroupField.

The described fields follow common Django rules and support Django migrations.

ImageField requires an uploaded file to be an image. There also exists manual_crop, an optional parameter that enables a manual cropping tool allowing users to outline a crop area in an image. If it holds an empty string in its value, cropping operates in Free mode. You are free to use values like "3:4" or "200x300" to specify dimensions or aspect ratios of a resulting image. You can learn more about crop in the widget documentation.

Forms outside Django admin

You might want to use Uploadcare outside Django admin. It’s going to work just as well. Just don’t forget to add `` to the <head> section of your page.

Using uploaded files

After a file gets uploaded, you can work with it. For instance, if you want a download link, using your field alone will do:

<ahref="">Download</a>

You can also apply Media Processing operations via URL directives. For example, Image Processing will work with any image uploaded to Uploadcare. If you specify the manual_crop param, processing operations will be applied to a cropped image version.

photo = ImageField()

<imgsrc=""> — original image<imgsrc="-/scale_crop/200x300/center/"> — original image scaled down and cropped to fit into 200x300

photo = ImageField(manual_crop="")

<imgsrc=""> - original image, cropped as specified during upload<imgsrc="-/scale_crop/200x300/center/"> - same as above, scaled down and cropped to fit into 200x300

photo = ImageField(manual_crop="2:3")

<imgsrc=""> - original image, cropped as specified during upload, with an aspect ratio of 2:3<imgsrc="-/scale_crop/200x300/center/"> - same as above, scaled down to fit into 200x300. Since the initial aspect ratio is 2:3, no cropping is needed

photo = ImageField(manual_crop="200x300")

<imgsrc=""> - original image, cropped as specified during upload, dimensions are 200x300<imgsrc="-/resize/100x/"> - same as above, downscaled, half size along each axis

Migrating existing files to Uploadcare

If you already have a file database and wish to migrate it to Uploadcare, the simplest way would be keeping all of those files in place and using Uploadcare Widget to migrate your content iteratively. The widget should be allowed to upload files from URLs.

To set your Uploadcare field value to the original URL, use the initial parameter of the Django form. See how it’s done with Class-Based Views: