Support css & js overrides

jonaswinkler · Jul 8, 2018 · e7daf7d · e7daf7d
1 parent ba1f437
commit e7daf7d
Show file tree

Hide file tree

Showing 7 changed files with 116 additions and 2 deletions.
diff --git 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
@@ -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
@@ -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, ``<project root>/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 ``<head>``, and the Javascript stuffed into the last line of the
+``<body>``.
diff --git 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
@@ -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
@@ -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(
+            '<link rel="stylesheet" type="text/css" href="{}" />'.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(
+            '<script src="{}"></script>'.format(
+                os.path.join(settings.MEDIA_URL, "overrides.js")
+            )
+        )
+    return ""
diff --git 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",
 
 ]