Pinax Documents

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:

Releases: published to PyPI or tagged in app repos in the Pinax GitHub organization
Global documentation: Pinax documentation website
App specific documentation: app repos in the Pinax GitHub organization
Support information: SUPPORT.md file in the Pinax default community health file repo
Contributing information: CONTRIBUTING.md file in the Pinax default community health file repo
Current and historical release docs: Pinax Wiki

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.

"success" - sixty percent or more available
"warning" - forty percent or less storage remaining
"danger" - ten percent or less storage remaining

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

Drop Django 1.11, 2.0, and 2.1, and Python 2,7, 3.4, and 3.5 support
Add Django 2.2 and 3.0, and Python 3.6, 3.7, and 3.8 support
Update packaging configs
Direct users to community resources

1.0.2

Allow use with any account-management package by removing django-user-accounts dependency
Require pinax-templates>=2.0.0 if using pinax-templates without django-user-accounts

1.0.1

Update requirements
Replace pinax-theme-bootstrap requirement with pinax-templates
Remove doc build support
Improve documentation markup

1.0.0

Standardize documentation layout
Drop Django v1.8, v1.10 support
Replace _clone with _chain to fix unexpected keyword argument 'user' error
Add hookset documentation
Add view documentation

0.6.0

Add Django 2.0 compatibility testing
Drop Django 1.9 and Python 3.3 support
Convert CI and coverage to CircleCi and CodeCov
Add PyPi-compatible long description
Move documentation to README.md

0.4.2

Fix bug in document deletion where quota was not given back
Made model strings for Folder and Document Python 3 compatible

0.4.1

Updating documentation

0.4.0

Moved template locations to be under pinax/ PR #9
Namespaced URLs PR #10, PR #16
Moved signal receiver to receivers.py PR #11
Converted views to class based views PR #12
Added hooksets PR #15
Document deletion PR #17
Folder deletion PR #19
Disallow document name duplicates within same folder PR #20
Disallow folder name duplicates within same parent PR #20

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.

Files

README.md

Latest commit

History

README.md

File metadata and controls

Pinax Documents

Table of Contents

About Pinax

Important Links

pinax-documents

Overview

Supported Django and Python Versions

Documentation

Installation

Usage

Views

document_create

document_detail

document_download

document_delete

document_index

folder_create

folder_detail

members

can_share

folder_share

folder_delete

Model Managers

Folder.members(folder, **kwargs)

Folder.objects.for_user(user)

Document.objects.for_user(user)

Template Tags

Filters

can_share

readable_bytes

Hookset Methods

already_exists_validation_message(name, folder)

can_share_folder(self, user, folder)

document_created_message(self, request, document)

document_deleted_message(self, request, document)

file_upload_to(self, instance, filename)

folder_created_message(self, request, folder)

folder_deleted_message(self, request, folder)

folder_pre_delete(self, request, folder)

folder_shared_message(self, request, user, folder)

folder_unshared_message(self, request, user, folder)

share_with_options(self, user, folder)

storage_color(self, user_storage)

Settings

PINAX_DOCUMENTS_HOOKSET

Templates

Customizing Templates

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

Code of Conduct

Connect with Pinax

License

`members`

`can_share`

`Folder.members(folder, **kwargs)`

`Folder.objects.for_user(user)`

`Document.objects.for_user(user)`

`already_exists_validation_message(name, folder)`

`can_share_folder(self, user, folder)`

`document_created_message(self, request, document)`

`document_deleted_message(self, request, document)`

`file_upload_to(self, instance, filename)`

`folder_created_message(self, request, folder)`

`folder_deleted_message(self, request, folder)`

`folder_pre_delete(self, request, folder)`

`folder_shared_message(self, request, user, folder)`

`folder_unshared_message(self, request, user, folder)`

`share_with_options(self, user, folder)`

`storage_color(self, user_storage)`

`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`