Pinax Documents

CircleCi Codecov

Table of Contents

About Pinax

Pinax is an open-source platform built on the Django Web Framework. It is an ecosystem of reusable Django apps, themes, and starter project templates. This collection can be found at http://pinaxproject.com.

Important Links

Where you can find what you need:

pinax-documents

Overview

pinax-documents is a well tested, documented, and proven document management app for collecting and sharing documents in folders.

Supported Django and Python Versions

Django / Python 3.6 3.7 3.8
2.2 * * *
3.0 * * *

Documentation

Installation

To install pinax-documents:

    $ pip install pinax-documents

Add pinax.documents to your INSTALLED_APPS setting:

    INSTALLED_APPS = [
        # other apps
        "pinax.documents",
    ]

Add pinax.documents.urls to your project urlpatterns:

    urlpatterns = [
        # other urls
        url(r"^docs/", include("pinax.documents.urls", namespace="pinax_documents")),
    ]

Usage

Views

Four views handle Document creation, detail, downloading, and deletion. Four views handle Folder creation, detail, sharing, and deletion. All views require an authenticated user but no special permission.

document_create

Validates form input to create a new Document. Optionally adds document to a specified Folder. Specify a folder by adding ?f=5 URL kwarg to the GET request, where 5 is the PK of the desired Folder. Redirects to the document index view.

URL: pinax_documents:document_create

Template: pinax/documents/document_create.html

Form class: pinax.forms.DocumentCreateForm

document_detail

Shows document detail, if document is within the requesting user's scope.

URL: pinax_documents:document_detail

Template: pinax/documents/document_detail.html

document_download

Download a specified Document, if document is within requesting user's scope.

URL: pinax_documents:document_download

document_delete

Delete the specified Document. Redirects to document index view.

URL: pinax_documents:document_create

Template: pinax/documents/document_confirm_delete.html

document_index

Show a list of Documents within user scope. URL: pinax_documents:document_index

Template: pinax/documents/index.html

folder_create

Create a new Folder.

A folder can be created as a subfolder of an existing folder. To create this relationship specify a parent folder by adding ?p=3 URL kwarg to the GET request, where 3 is the PK of the desired "parent" folder.

URL: pinax_documents:folder_create

Template: pinax/documents/folder_create.html

Form class: pinax.forms.FolderCreateForm

folder_detail

Shows folder detail, including all documents within the requesting user's scope.

URL: pinax_documents:folder_detail

Template: pinax/documents/folder_detail.html

Detail view context variables:

members

User members of the folder.

can_share

True if user can share the folder.

folder_share

Share a folder with another user.

URL: pinax_documents:folder_share

Template: pinax/documents/folder_share.html

folder_delete

Delete the specified Folder. Redirects to document index view.

URL: pinax_documents:folder_delete

Template: pinax/documents/folder_confirm_delete.html

Model Managers

Folder.members(folder, **kwargs)

Folder.objects.for_user(user)

Returns all Folders a user can do something with. Chainable query method.

Document.objects.for_user(user)

Returns all Documents a user can do something with. Chainable query method.

Template Tags

{% load pinax_documents_tags %}

Filters

can_share

Returns True if member can share with user:

    {{ member|can_share:user }}
readable_bytes

Display number of bytes using appropriate units.

    {{ 73741824|readable_bytes }}

yields "70MB".

Hookset Methods

already_exists_validation_message(name, folder)

String used to indicate a document with name already exists in folder.

can_share_folder(self, user, folder)

Return True if user can share folder.

document_created_message(self, request, document)

Success message when document is created.

document_deleted_message(self, request, document)

Success message when a document is deleted.

file_upload_to(self, instance, filename)

Callable passed to the FileField's upload_to kwarg on Document.file

folder_created_message(self, request, folder)

Success message when folder is created.

folder_deleted_message(self, request, folder)

Success message when a folder is deleted.

folder_pre_delete(self, request, folder)

Perform folder operations prior to deletions. For example, deleting all contents.

folder_shared_message(self, request, user, folder)

Success message when a folder is shared.

folder_unshared_message(self, request, user, folder)

Success message when a folder is unshared.

share_with_options(self, user, folder)

Return a list of users with whom user can share folder.

storage_color(self, user_storage)

Returns a label indicating amount of storage used.

Settings

PINAX_DOCUMENTS_HOOKSET

Used to provide your own custom hookset methods, as described above. Value is a dotted path to your own hookset class:

PINAX_DOCUMENTS_HOOKSET = "myapp.hooks.DocumentsHookSet"

Templates

Default templates are provided by the pinax-templates app in the documents section of that project.

Reference pinax-templates installation instructions to include these templates in your project.

View live pinax-templates examples and source at Pinax Templates!

Customizing Templates

Override the default pinax-templates templates by copying them into your project subdirectory pinax/documents/ on the template path and modifying as needed.

For example if your project doesn't use Bootstrap, copy the desired templates then remove Bootstrap and Font Awesome class names from your copies. Remove class references like class="btn btn-success" and class="icon icon-pencil" as well as bootstrap from the {% load i18n bootstrap %} statement. Since bootstrap template tags and filters are no longer loaded, you'll also need to update {{ form|bootstrap }} to {{ form }} since the "bootstrap" filter is no longer available.

base.html

document_confirm_delete.html

document_create.html

document_detail.html

folder_confirm_delete.html

folder_create.html

folder_detail.html

folder_share.html

index.html

Change Log

2.0.0

1.0.2

1.0.1

1.0.0

0.6.0

0.4.2

0.4.1

0.4.0

0.3.1

0.3.0

0.2.0

0.1

Contribute

Contributing information can be found in the Pinax community health file repo.

Code of Conduct

In order to foster a kind, inclusive, and harassment-free community, the Pinax Project has a Code of Conduct. We ask you to treat everyone as a smart human programmer that shares an interest in Python, Django, and Pinax with you.

Connect with Pinax

For updates and news regarding the Pinax Project, please follow us on Twitter @pinaxproject and check out our Pinax Project blog.

License

Copyright (c) 2012-present James Tauber and contributors under the MIT license.