Metadata-Version: 1.0
Name: djcroco
Version: 0.2.6
Summary: UNKNOWN
Home-page: https://github.com/mattack108/djcroco/
Author: Matt Lenc
Author-email: matt.lenc@gmail.com
License: UNKNOWN
Description: djcroco
        =======
        
        .. image:: https://travis-ci.org/mattack108/djcroco.png?branch=master
           :target: https://travis-ci.org/mattack108/djcroco
        
        .. image:: https://pypip.in/v/djcroco/badge.png
           :target: https://pypi.python.org/pypi/djcroco
        
        .. image:: https://pypip.in/d/djcroco/badge.png
           :target: https://pypi.python.org/pypi/djcroco
        
        ``djcroco`` is a custom `Django <https://www.djangoproject.com/>`_ model field to
        add support for the `Crocodoc API <https://crocodoc.com/>`_.
        
        It behaves like standard `FileField <https://docs.djangoproject.com/en/dev/ref/models/fields/#filefield>`_
        so you can still use most of its properties (e.g. ``name``, ``size``, ``url``
        etc) while having extra ones to play with Crocodoc API.
        
        ``djcroco`` is supported by `Incuna <http://incuna.com>`_ (an awesome company
        I work for!).
        
        Installation
        ------------
        
        To install ``djcroco``, simply run: ::
        
            pip install djcroco
        
        Include in ``urls.py``: ::
        
            url(r'', include('djcroco.urls')),
        
        Define Crocodoc API token in ``settings.py``: ::
        
            CROCO_API_TOKEN = '<api_token>'
        
        Or alternatively as env variable: ::
        
            export CROCO_API_TOKEN='<api_token>'
        
        When optional parameters for URLs are used (see below for more details) - then
        you need to add ``djcroco`` to ``INSTALLED_APPS``: ::
        
            INSTALLED_APPS += ('djcroco',)
        
        And load its template tags in the template you wish to use them in: ::
        
            {% load croco_tags %}
        
        Usage
        -----
        
        Define the field in model you wish to extend: ::
        
            from django.db import models
        
            from djcroco.fields import CrocoField
        
        
            class Example(models.Model):
                name = models.CharField(max_length=255)
                document = CrocoField()
        
                def __unicode__(self):
                    return self.name
        
        
        Custom thumbnails size
        ----------------------
        
        You can pass ``thumbnail_size`` like so: ::
        
            document = CrocoField(thumbnail_size=(150, 150))
        
        Where tuple is represented as *(width, height)*.
        
        If you do not pass custom thumbnail size, the default will be used (100x100).
        The maximum dimensions for thumbnail is **300x300**.
        
        Render the awesomeness
        ----------------------
        
        Documents
        ^^^^^^^^^
        
        ::
        
            {{ obj.document.name }}
        
        Returns name of the document.
        
        ::
        
            {{ obj.document.size }}
        
        Returns size of the document (in bytes).
        
        ::
        
            {{ obj.document.size_human }}
        
        Returns human-readable size of the document (eg. 1.3 MB).
        
        ::
        
            {{ obj.document.type }}
        
        Returns type (extension) of the document.
        
        ::
        
            {{ obj.document.uuid }}
        
        Returns UUID of the document (note: each Crocodoc document has unique id).
        
        Thumbnails
        ^^^^^^^^^^
        
        ::
        
            {{ obj.document.thumbnail }}
        
        Returns thumbnail as inline image (see `Data URI scheme <https://en.wikipedia.org/wiki/Data_URI_scheme>`_ for more details). See below for how to download a thumbnail.
        
        URLs
        ^^^^
        
        ::
        
            {{ obj.document.url }}
        
        Returns url of the document so it can be viewed directly.
        
        ::
        
            {{ obj.document.content_url }}
        
        Returns url of the document wrapped in `HttpResponse <https://docs.djangoproject.com/en/dev/ref/request-response/#django.http.HttpResponse>`_ object.
        
        Both ``url`` and ``content_url`` can be extended with `optional parameters <https://crocodoc.com/docs/api/#session-create>`_.
        
        ::
        
            {{ obj.document.url|editable:"true"|user_id:"1"|user_name:"admin" }}
        
        ``editable`` param allows users to create annotations and comments while viewing the document.
        **Default: false**
        
        ``user_id`` and ``user_name`` will be shown in the viewer to attribute annotations and comments to their author. **Required if editable is true**
        
        ::
        
            {{ obj.document.url|user_filter:"1,2,3" }}
        
        Limits which users' annotations and comments are shown. Possible values are: *all*, *none*, or a comma-separated list of user IDs. **Default: all**
        
        **Note**: ``user_filter`` is a renamed version of Crocodoc's ``filter`` in order to work in Django template system.
        
        Full list of supported `parameters <https://crocodoc.com/docs/api/#session-create>`_.
        
        Downloads
        ^^^^^^^^^
        
        ::
        
            {{ obj.document.download_document }}
        
        Returns the original document in PDF format.
        
        ::
        
            {{ obj.document.download_document|annotated:"true" }}
        
        Returns the original document with annotations. **Default: false**
        
        ::
        
            {{ obj.document.download_document|user_filter:"1,2,3" }}
        
        Returns the original document with annotations limited to given users.
        Possible values are: *all*, *none*, or a comma-separated list of user IDs. **Default: all**
        
        ::
        
            {{ obj.document.download_thumbnail }}
        
        Returns a thumbnail of the document's first page in PNG format.
        
        ::
        
            {{ obj.document.download_thumbnail|size:"99x99" }}
        
        Same as ``download_thumbnail`` with custom dimensions of the thumbnail in the format *{width}x{height}*. Largest dimensions allowed are 300x300. **Default: 100x100**
        
        ::
        
            {{ obj.document.download_text }}
        
        Returns the full text from a document.
        Note: This method is available only if your Crocodoc account has text
        extraction enabled.
        
        Dependencies
        ------------
        
        - Python 2.6.x, 2.7.x
        - Django 1.3.x, 1.4.x, 1.5.x
        - `crocodoc <https://pypi.python.org/pypi/crocodoc>`_ 0.1.1
        
        Python 3.x will be supported soon!
        
Platform: UNKNOWN
