Django integration

Uploadcare is a scalable end-to-end file platform that you can get up and running in minutes. Integrating Uploadcare allows you to fully manage file uploads, storage, processing, and delivery.

Requirements
Install
Configuration
Usage

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

To run smoothly, consider having these:

Uploadcare account.
A public API key of an Uploadcare project.
Django 1.11+

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.

See the example below:

from django.db import models

from pyuploadcare.dj import FileField, ImageField


class Candidate(models.Model):
  name = models.CharField(max_length=120)
  about = models.TextField()

  resume = FileField(blank=True, null=True)
  photo = ImageField(blank=True, null=True, manual_crop="")

  def __unicode__(self):
      return self.name

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:

<a href="">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()

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

photo = ImageField(manual_crop="")

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

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

<img src="">
    - original image, cropped as specified during upload, with an aspect ratio of 2:3
<img src="-/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")

<img src="">
    - original image, cropped as specified during upload, dimensions are 200x300
<img src="-/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:

class CandidateUpdateView(UpdateView):
  model = Candidate
  success_url = '/'

  def get_initial(self):
    initial = super(CandidateUpdateView, self).get_initial()

    if self.object and self.object.photo_old and not self.object.photo:
        initial['photo'] = self.object.photo_old.url

    return initial

Now, as soon as the update page gets opened, your original file will be moved to Uploadcare. This allows your users to check it out in the widget and replace or re-crop it if needed.

Consider looking into UC Optimize and Migro as alternative migration options.

That’s it

Uploadcare fields are just as simple to use as CharField. Drop us a line in case you have any questions about integrating or using Uploadcare.

Check out our Django tutorial on GitHub.

uploadcaredocs