Metadata-Version: 2.1
Name: django-pdf-view
Version: 3.1.2
Summary: Django app for seamlessly displaying and downloading PDF documents in browser
License: MIT
Keywords: pdf,pdf view,django pdf,django pdf view,generate pdf,django generate pdf
Author: Miloš Roknić
Author-email: roknic.milos.994@gmail.com
Maintainer: Miloš Roknić
Maintainer-email: roknic.milos.994@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: django (>=5.1.1,<6.0.0)
Requires-Dist: pdfkit (>=1.0.0,<2.0.0)
Project-URL: documentation, https://github.com/roknicmilos/django-pdf-view/blob/main/README.md
Project-URL: homepage, https://github.com/roknicmilos/django-pdf-view
Project-URL: issues, https://github.com/roknicmilos/django-pdf-view/issues
Project-URL: repository, https://github.com/roknicmilos/django-pdf-view/
Description-Content-Type: text/markdown

# Django PDF View

[![Build Status](https://github.com/roknicmilos/django-pdf-view/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/roknicmilos/django-pdf-view/actions/workflows/ci.yml/?query=branch:main)
[![PyPI version](https://img.shields.io/pypi/v/django-pdf-view.svg)](https://pypi.org/project/django-pdf-view/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/roknicmilos/django-pdf-view.svg)](https://github.com/roknicmilos/django-pdf-view/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/roknicmilos/django-pdf-view.svg)](https://github.com/roknicmilos/django-pdf-view/issues)
[![codecov](https://codecov.io/github/roknicmilos/django-pdf-view/graph/badge.svg?token=VF1XVECK7P)](https://codecov.io/github/roknicmilos/django-pdf-view)

## Purpose

The primary purpose of this Django package is to streamline the creation of PDF
documents and allow for easy viewing or downloading in the browser. The package
provides a **solid foundation of HTML and CSS for PDF file layout**. To use it,
simply create an HTML template for your PDF document, then create a view that
inherits from `PDFView` and define the necessary class attributes to generate
the PDF.

This approach enables developers to focus on crafting the content and styles of
their PDF pages without having to deal with complex layout issues.

### Key Features

- **Predefined Page Layout**: Includes built-in base HTML and CSS to help
  structure your PDF pages efficiently.

- **Flexible PDF Content and Styling**: Easily create your own HTML template for
  the PDF document and customize the appearance by applying your own CSS.

- **PDF View Response Options**: Seamlessly switch between viewing the PDF,
  displaying the HTML content, and downloading the PDF file.

## Prerequisites

- [wkhtmltopdf](https://wkhtmltopdf.org/)

## Installation

```bash
pip install django-pdf-view
```

or

```bash
poetry add django-pdf-view
```

## Configuration

Add `django-pdf-view` to your `INSTALLED_APPS` in `settings.py`:

```python
INSTALLED_APPS = [
    ...
    'pdf_view',
    ...
]
```

## Usage

In order to create your own PDF, you need to implement your own view and
template.

1. Create a new view to render the PDF:

    ```python
   # my_app/views.py    
        
   from pdf_view.views.pdf_view import PDFView
        
        
   class MyPDFView(PDFView):
        template_name = 'my_app/my_pdf.html'
        title = 'My PDF Document' # optional
        filename = 'My PDF.pdf' # optional
        css_paths = [ # optional
            'my_pdf/css/my_pdf.css',
        ]
    ```

2. Create a new template to define the content of your PDF page:

   ```html
   <!-- my_app/templates/my_app/pdf_page.html -->
   
   <div class="page">
        <h1 class="my-title">{{ title }}</h1>
        <p class="my-text">{{ text }}</p>
        <p class="my-text">Additional PDF page text.</p>
   </div>
   
   <!-- Define more <div class="page"> elements for additional pages -->
   ```

3. Add the new URL patterns to your project's `urls.py`:

    ```python
    # my_app/urls.py    
    
    from django.urls import path
    from my_app.views import MyPDFView
    
    urlpatterns = [
        path('pdf-file/', MyPDFView.as_view(response_type='pdf'), name='pdf-file'),
        path('pdf-html/', MyPDFView.as_view(response_type='html'), name='pdf-html'),
        path('pdf-download/', MyPDFView.as_view(response_type='download'), name='pdf-download'),
    ]
    ```
   <br/>

4. Visit the belows listed URLs:

- To view the PDF
  file: [http://localhost:8000/pdf-file/](http://localhost:8000/pdf-file/)
- To view the
  HTML: [http://localhost:8000/pdf-html/](http://localhost:8000/pdf-html/)
- To download the PDF
  file: [http://localhost:8000/pdf-download/](http://localhost:8000/pdf-download/)

### Default template context

- PDF document:
    - `title`: Title of the PDF document (used in `<title>` tag).
    - `css`: Content of the CSS files specified in the `css_paths` attribute.
    - `content`: Content of the HTML template.
    - `response_type`: Type of the response (`pdf`, `html` or `download`).

### `svg` template tag

`svg` template tag is provided by the `django-pdf-view` package. This template
tag can be used to include SVG images in the PDF document.

**Usage example**:

```html
{% load svg %}

<!-- Some HTML content -->

{% svg 'path/to/image.svg' %}

<!-- Some more HTML content -->
```

You can also dynamically set a custom color to the SVG by adding
`data-dynamic-color="true"` to elements in the SVG file that contain the `fill`
attribute.

**Example**:

```html

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <path fill="white" data-dynamic-color="true" .../>
</svg>
```

and then in the template:

```html
{% load svg %}

<!-- Some HTML content -->

{% svg 'path/to/image.svg' 'black' %}

<!-- Some more HTML content -->
```

In the above example, the fill color of the SVG will be changed from white to
black.

## Bugs/Requests

If you encounter any bugs or have any requests, please use
[GitHub issue tracker](https://github.com/roknicmilos/django-pdf-view/issues)
to report them.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

