paperclip 2.1.2

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.2 (2018-03-25)
==================

** New **

* Support Django 1.8 to 1.11


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