Skip to content

Latest commit

 

History

History
107 lines (79 loc) · 3.11 KB

README.md

File metadata and controls

107 lines (79 loc) · 3.11 KB

django-template-docx

Django-Template-Docx provide all the necessities to easily include docx merging capabilities to any Django project.

Main functionnalities:

  • Easy data definition for developpers
  • Autogenerated documentations for end users
  • complete set of views and templates for end users to upload templates and download them merged

Install

pip install django-docx-template

Then update your settings:

INSTALLED_APPS = [
    ...
    "django_docx_template",
    ...
]

to finish, wire urls:

# config/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("docx/", include("django_docx_template.urls")),
]

Usage

Create a DataSource

First you'll need to create a source of data:

# my_app/data_sources.py
from django_docx_template.data_sources import DataSource

# let's imagine you have a Model Person
from .models import Person


class PersonSource(data_sources.DataSource):
    # properties
    label = "Data source for Person"
    model = Person
    url_args = {"pk": "int"}
    # fields that will be used for merging
    first_name = data_sources.Field(examples=["Pierre", "Paul"])
    last_name = data_sources.Field(examples=["Smith", "Dupont"])
    size = data_sources.Field(examples=["180", "190"])
    favorite_color = data_sources.Field(source="color__label", examples=["red", "blue"])

then you need to add the data source to your settings:

# config/settings.py
...
DJANGO_DOCX_TEMPLATE = {
    "data_sources":[
        "my_app.data_sources.PersonDataSource",
    ]
}

Now your end users can access :

  • docx/sources/ to explore data sources and related documentation
  • docx/templates/ to browse and upload new templates
  • docx/templates/detail/ to test downloading document

For example, to download a document with slug="identity" and wired to the data source previously built, the url would be /docx/template/detail/identity/123 (where 123 is a person_id).

Ideas for future improvements

  • add documentations
  • Make a ModelDataSource that really autogenerated doc from field type and help argument
  • Then make a mixin that turn a Model into DataSource (would be awesome)
  • Add managed command to help generate DataSource
  • Customize admin views
  • Add options to make DocxTemplates invisible or undeletable to wire them in other part of the app without risking enduser changing it
  • Add protection mechanisms to provided views to restrict them to a particular set of users or restrict template list
  • Add check mechanisms to valid docx document on upload (example a tag in the document that is not in the datasource should raise a warning because it will never be populated)

Contributing

Please, use Black as code formatter and make sure the test coverage stick to 100%.

To run test, please see https://github.com/Swannbm/runtest_on_dj_packages ; if you know a better way to do it I am all ears :D

For packaging, use Poetry:

poetry build
poetry publish --username xxx --password xxxx

Why

Because it is fun !