Skip to main content

Attach files to Django models

Project description

Paperclip
=========

Add attachments to Django models, used in `MapEntity <https://github.com/makinacorpus/django-mapentity>`_.

=======
INSTALL
=======

Installing from pypi (using pip)

::

pip install paperclip


Installing from github

::

pip install -e git://github.com/makinacorpus/django-paperclip.git#egg=django-paperclip

=======
UPGRADE
=======

After upgrade to 0.4.0, if you want to enable links to Youtube/Soundcould media,
you have to add an additional column to the database:

::

ALTER TABLE paperclip_attachment ADD COLUMN attachment_video VARCHAR(200) NOT NULL DEFAULT '';


===========
BASIC USAGE
===========

* Add ``easy_thumbnails``, ``embed_video`` and ``paperclip`` to ``INSTALLED_APPS``

* Include urls

::

urlpatterns = [
...
url(r'^paperclip/', include('paperclip.urls')),
...
]

* Include scripts in template

::

<script src="{% static "paperclip/bootstrap-confirm.js" %}" type="text/javascript"></script>
<script src="{% static "paperclip/spin.min.js" %}" type="text/javascript"></script>
<script src="{% static "paperclip/paperclip.js" %}" type="text/javascript"></script>

If you use bootstrap 3, please include ``paperclip/bootstrap-3-confirm.js`` instead of ``paperclip/bootstrap-confirm.js``.

* Include list and form in template

::

{% include 'paperclip/attachment_list.html' with object=my_instance attachment_form_next=my_instance.get_detail_url %}

* Add paperclip models in one of your apps

::

class FileType(paperclip.models.FileType):
pass

class Attachment(paperclip.models.Attachment):
pass

* Configure

Define the following django setting:

::

PAPERCLIP_ENABLE_VIDEO = False,
PAPERCLIP_FILETYPE_MODEL = 'myapp.FileType'
PAPERCLIP_ATTACHMENT_MODEL = 'myapp.Attachment'
PAPERCLIP_ACTION_HISTORY_ENABLED = True

* Make migration and migrate


=========
TEMPLATES
=========

Three templates are embeded and can easily be overriden :

* ``paperclip/attachment_list.html`` : renders a table displaying attached files for an object and an upload form using the two following templates
* ``paperclip/_attachment_table.html`` : renders a table displaying attached files for an object
* ``paperclip/_attachment_form.html`` : renders an upload form


============
TEMPLATETAGS
============

Two templatetags are provided :

get_attachments_for
````````````````````
Resolves attachments that are attached to a given object. You can specify the variable name in the context the attachments are stored using the `as` argument. Default context variable name is `attachments`. You can filter on a specified FileType with the optional `only_type` argument.

Examples

::

{% get_attachments_for my_instance as "my_attachments" %}
{% get_attachments_for my_instance as "my_attachments" only_type my_filetype_instance %}

attachment_form
```````````````
Renders a "upload attachment" form. `obj` argument is required and represents the instance to which you want to associate the file. A bound form can be given optionnaly with the argument ``form``. Important : a ``attachment_form_next`` variable is expected in context. If you want to use a custom form class, you can add ``attachment_form_class`` variable in context too

Examples

::

{% with object=my_instance attachment_form_next=my_instance.get_detail_url %}
{% attachment_form object %}
{% endwith %}

OR

# views.py
...
context['object'] = my_instance
context['attachment_form_next'] = my_instance.get_detail_url(=)
context['attachment_form_class'] = MyAttachmentForm
...

# template
{% attachment_form object %}

==================
USE A CUSTOM FORM
==================

You can use a custom django form by following this steps. Parenthetically, It's the recommended solution if you want to use django-crispy-forms or django-floppyforms.

* Write your custom form :

::

from paperclip.forms import AttachmentForm

class MyAttachmentForm(AttachmentForm):
...

Note: To be sure to not break the form logic, we recommend to inherit from the native ``paperclip.forms.AttachmentForm``.

* Add your form class in a ``attachment_form_class`` variable of the main view context

::

context['attachment_form_class'] = MyAttachmentForm

* Override ``'add_attachment'`` and ``'update_attachment'`` URLs to provide your custom form class in arguments

::

from my_app.forms import MyAttachmentForm

urlpatterns = [
url(r'^paperclip/', include('paperclip.urls')),
...
url(r'^add-for/(?P<app_label>[\w\-]+)/'
r'(?P<model_name>[\w\-]+)/(?P<pk>\d+)/$',
'paperclip.views.add_attachment',
kwargs={'attachment_form': MyAttachmentForm},
name="add_attachment"),

url(r'^update/(?P<attachment_pk>\d+)/$',
'paperclip.views.update_attachment',
kwargs={'attachment_form': MyAttachmentForm},
name="update_attachment"),
...
]


Note: Be sure to write these URLs after having included paperclip URLs.

=======
CLEANUP
=======

Deleting or changing an attachment does not remove the old attached file from disk.
From time to time you can clean obsolete files by running:

::

./manage.py clean_attachments


=======
AUTHORS
=======

|makinacom|_

.. |makinacom| image:: http://depot.makina-corpus.org/public/logo.gif
.. _makinacom: http://www.makina-corpus.com


=======
LICENSE
=======

* LGPL


=========
CHANGELOG
=========

2.1.1 (2017-03-23)
==================

** Fixes **

* Fix releases required includes


2.1.0 (2017-03-23)
==================

** New **

* From now, Attachment model support external picture URLs


2.0.0 (2017-02-21)
==================

** BREAKING CHANGES **

* Provide an abstract model. Users are required to define their own
Attachment model


1.0.0 (2017-01-14)
==================

** BREAKING CHANGES **

* Remove support of Django <= 1.7
* Rename parameter 'module_name' as 'model_name' in urls

** New **

* Support Django 1.8
* Add initial migration (Caution! it depends on app settings)


0.5.0 (2016-01-11)
==================

** New **

* Add a command to clean obsolete files


0.4.1 (2015-03-20)
==================

** Fixes **

* Fix uploaded file modification


0.4.0 (2015-03-20)
==================

** New **

* Allow to add links to Youtube or Soundcloud media


0.3.0 (2015-03-18)
==================

** Removed (WARNING: backward incompatibility) **

* Totally remove crispy_forms and floppy_forms integration (you can now override the form by a custom one instead)

** New **

* Allow usage of a custom form


0.2.3 (2014-12-15)
==================

* Handle swappable User model
* Embed spinner, bootstrap-confirm and add a bootstrap-3-confirm
* Remove crispy_forms dependency


0.2.2 (2014-11-14)
==================

* Fix permission check for attachments


0.2.0 (2014-11-12)
==================

* Allow to override file types from request.


0.1.3 (2014-11-07)
==================

* Fix packaging of locale files


0.1.2 (2014-11-07)
==================

* Fix upload regular expressions for author and legend


0.1.1 (2014-11-03)
==================

* Fix missing SVG media in package


0.1.0 (2014-10-23)
==================

* Initial working version

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

paperclip-2.1.1.tar.gz (67.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page