From e7daf7dae41c5919088cdbf826a347611b22a6d5 Mon Sep 17 00:00:00 2001 From: Daniel Quinn Date: Sun, 8 Jul 2018 16:06:57 +0100 Subject: [PATCH] Support css & js overrides --- .gitignore | 2 + docs/changelog.rst | 7 ++++ docs/customising.rst | 27 +++++++++++++ docs/index.rst | 1 + src/documents/templates/admin/base_site.html | 40 ++++++++++++++++++++ src/documents/templatetags/customisation.py | 37 ++++++++++++++++++ src/paperless/settings.py | 4 +- 7 files changed, 116 insertions(+), 2 deletions(-) create mode 100644 docs/customising.rst create mode 100644 src/documents/templates/admin/base_site.html create mode 100644 src/documents/templatetags/customisation.py diff --git a/.gitignore b/.gitignore index 617cf507a..a16f958a3 100644 --- a/.gitignore +++ b/.gitignore @@ -61,6 +61,8 @@ target/ media/documents/*.gpg media/documents/thumbnails/* media/documents/originals/* +media/overrides.css +media/overrides.js # Sqlite database db.sqlite3 diff --git a/docs/changelog.rst b/docs/changelog.rst index f3442fe9a..84cc6bae9 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -14,6 +14,11 @@ Changelog doing active development on Paperless using the Docker environment: `#376`_. +* You now also have the ability to customise the interface to your heart's + content by creating a file called ``overrides.css`` and/or ``overrides.js`` + in the root of your media directory. Thanks to `Mark McFate`_ for this + idea: `#371`_ + 2.0.0 ===== @@ -445,6 +450,7 @@ bulk of the work on this big change. .. _thinkjk: https://github.com/thinkjk .. _mcronce: https://github.com/mcronce .. _Enno Lohmeier: https://github.com/elohmeier +.. _Mark McFate: https://github.com/SummittDweller .. _#20: https://github.com/danielquinn/paperless/issues/20 .. _#44: https://github.com/danielquinn/paperless/issues/44 @@ -515,6 +521,7 @@ bulk of the work on this big change. .. _#351: https://github.com/danielquinn/paperless/pull/351 .. _#352: https://github.com/danielquinn/paperless/pull/352 .. _#354: https://github.com/danielquinn/paperless/issues/354 +.. _#371: https://github.com/danielquinn/paperless/issues/371 .. _#374: https://github.com/danielquinn/paperless/pull/374 .. _#375: https://github.com/danielquinn/paperless/pull/375 .. _#376: https://github.com/danielquinn/paperless/pull/376 diff --git a/docs/customising.rst b/docs/customising.rst new file mode 100644 index 000000000..8110e214a --- /dev/null +++ b/docs/customising.rst @@ -0,0 +1,27 @@ +.. _customising: + +Customising Paperless +##################### + +Currently, the Paperless' interface is just the default Django admin, which +while powerful, is rather boring. If you'd like to give the site a bit of a +face-lift, or if you simply want to adjust the colours, contrast, or font size +to make things easier to read, you can do that by adding your own CSS or +Javascript quite easily. + + +.. _customising-overrides: + +Overrides +========= + +On every page load, Paperless looks for two files in your media root directory +(the directory defined by your ``PAPERLESS_MEDIADIR`` configuration variable or +the default, ``/media/``) for two files: + +* ``overrides.css`` +* ``overrides.js`` + +If it finds either or both of those files, they'll be loaded into the page: the +CSS in the ````, and the Javascript stuffed into the last line of the +````. diff --git a/docs/index.rst b/docs/index.rst index dbeade955..7710a330c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,6 +40,7 @@ Contents utilities guesswork migrating + customising extending troubleshooting scanners diff --git a/src/documents/templates/admin/base_site.html b/src/documents/templates/admin/base_site.html new file mode 100644 index 000000000..8d5e903d6 --- /dev/null +++ b/src/documents/templates/admin/base_site.html @@ -0,0 +1,40 @@ +{% extends 'admin/base_site.html' %} + +{# NOTE: This should probably be extending base.html. See CSS comment below details. #} + + +{% load custom_css from customisation %} +{% load custom_js from customisation %} + + +{% block blockbots %} + + {% comment %} + This really should be extending `extrastyle`, but the the + django-flat-responsive package decided that it wanted to put its CSS in + this block, so to make sure that overrides are in fact overriding + everything else, we have to do the Wrong Thing here. + + Once we switch to Django 2.x and drop django-flat-responsive, we should + switch this to `extrastyle` where it should be. + {% endcomment %} + + {{ block.super }} + + {% custom_css %} + +{% endblock blockbots %} + + +{% block footer %} + + {% comment %} + The Django admin doesn't have a block for Javascript you'd want placed in + the footer, so we have to use this one instead. + {% endcomment %} + + {{ block.super }} + + {% custom_js %} + +{% endblock footer %} diff --git a/src/documents/templatetags/customisation.py b/src/documents/templatetags/customisation.py new file mode 100644 index 000000000..793fd0eb3 --- /dev/null +++ b/src/documents/templatetags/customisation.py @@ -0,0 +1,37 @@ +import os + +from django import template +from django.conf import settings +from django.utils.safestring import mark_safe + +register = template.Library() + + +@register.simple_tag() +def custom_css(): + theme_path = os.path.join( + settings.MEDIA_ROOT, + "overrides.css" + ) + if os.path.exists(theme_path): + return mark_safe( + ''.format( + os.path.join(settings.MEDIA_URL, "overrides.css") + ) + ) + return "" + + +@register.simple_tag() +def custom_js(): + theme_path = os.path.join( + settings.MEDIA_ROOT, + "overrides.js" + ) + if os.path.exists(theme_path): + return mark_safe( + ''.format( + os.path.join(settings.MEDIA_URL, "overrides.js") + ) + ) + return "" diff --git a/src/paperless/settings.py b/src/paperless/settings.py index 6dd0b6419..91d2d2651 100644 --- a/src/paperless/settings.py +++ b/src/paperless/settings.py @@ -67,12 +67,12 @@ "reminders.apps.RemindersConfig", "paperless_tesseract.apps.PaperlessTesseractConfig", - "flat_responsive", + "flat_responsive", # TODO: Remove as of Django 2.x "django.contrib.admin", "rest_framework", "crispy_forms", - "django_filters" + "django_filters", ]