Paperless: A Better Front-End

[danielquinn]

The one we have right now is the one that comes free with Django. It's great for what it's supposed to do, but it was never meant as a primary front-end.

Now that there's a proper REST API, we need a real front-end in the one-page-app style.

[Ubadub]

@danielquinn my understanding of the API is that it is only limited to file uploads right now. Am I mistaken?

[danielquinn]

Actually no, there's a full RESTful API in there, it's just not documented yet. Just go to /api to see it working :-)

Note to self: document the friggin' API.

Update: It's documented now

[Ubadub]

Would you mind if I forked this and created a proper front-end?

[danielquinn]

Not at all, but you should know that I've been in contact with someone who's doing just that over on Bitbucket. I'll give you the same instructions I gave him:

1. Run ./manage.py startapp my_ui (You can name your app anything you like, so long as it’s alphanumeric. No dashes or spaces. It should also be all lowercase. This will create a new directory next to documents called myui wherein you’ll do all of your work.
2. Run mkdir -p myui/templates/documents myui/static/myui. The first directory is an override for the default (I’ll go into that later) and the second is where you’ll put your css, js, img files.
3. Create a file called index.html in myui/templates/documents/index.html and put all of your code in there. Inside that file, if you need to reference any of the static files, make sure you have {% load staticfiles %} at the top of the file, and then reference your script files with <script src="{% static 'myui/path/to/whatever.js' %}"></script>. This will reference myui/static/myui/path/to/whatever.js.
4. Now for the Python changes. Edit paperless/urls.py to un-comment the line just below the bit that says “Normal Pages (coming soon)”. This will turn on the router that points to the view that looks for documents/index.html — the file you’re overriding in your app.
5. Open paperless/settings.py, find the INSTALLED_APPS tuple there and add "myui", to the list. At first try adding it before "documents",, but if that doesn’t work try after it. I can’t remember which overrides which.

My current plan is to develop a front-end of my own, if only to sharpen my own front-end skills and provide a simple default. The idea however is that users should be able to choose the frontend they want just by setting a variable in /etc/paperless.conf, maybe something like PAPERLESS_UI=myui. That way people can use whatever ui they want and I'm not in a position of having to choose from the different ones supplied.

I reserve the right to change the directory structure though, as structurally things just might make more sense in a slightly different way. So long as you develop your fork doing regular pulls from master though, it shouldn't matter.

[Cyber1000]

Which kind (technology) of ui are you thinking about? Just interested ... . Thinking of a better ui for paperless on my own, but I'm more into .NET+angular than in python/django.

[Ubadub]

Well since there is an API set up you wouldn't have to write more than a few lines of python. You could do all of the querying entirely from javascript.

[danielquinn]

For my own initial front-end, I think I'll be using Backbone.js and Bootstrap, possibly with FontAwesome, but @Ubadub is right, outside of the 5 instructions above, you shouldn't need to write any Python as the API is everything you should need.

[Cyber1000]

Yeah, looked throught the api, looks fine. Just wanted to know what's planned on your side.

Nice Project :+1:

[JaimeObregon]

PDF.js is an easy to integrate JavaScript library by Mozilla which would allow that new frontend to display the frontpage of each document as a HTML5 iframe, even making the document browsable and searchable right away from the browser, without requiring the user to first download and open the file with an external PDF viewer which in rare cases (mobile?) he might not have at hand. But probably this would not work if the PDF files are encrypted.

Another very powerful functionality would be "live" (AJAX) search, narrowing the search results box dynamically as the user types. As Paperless is probably best suited for small-to-medium document archives (from hundreds to thousands of files, as for larger bases there are already a plethora of complex Document Managent Systems), the search functionality could be easily implemented in the user's browser using Lunr.js.

I'm familiar with these two libraries and I find them robust enough and quick to integrate.

[timwhite]

:+1: for something like PDF.js for better viewing of the PDF in the frontend without having to download it. I often want to just look at the PDF to better label it, without downloading it.

[danielquinn]

PDF.js sounds super-handy so thanks, that's something to fiddle with One of the guys I've been talking to about making a UI has been developing his just using a browser plugin, but it's nice to know that there's a plugin-free option. You don't need to worry about the PDFs being encrypted though, as they stream back to the browser unencrypted so long as you're logged in.

There's also the thumbnail, which should serve for @timwhite's need to just see what it is rather than read it all.

The search feature works just fine against the server too using the REST API. Just visit /api in your local installation and check out the Filters button under Documents. There's lots of ways to find documents and all of this can be plugged into ajax.

[philippeowagner]

I personally dislike the admin site. I dislike how it looks, how it feels and what it takes to integrate new feature or adapt the default mechanism. I thought as well about another UI for paperless.

I would suggest to build upon http://propeller.in/propeller-template-list.html. It's a responsive framework build with Bootstrap based on Google's Material Design Standards. It integrates best practices and state of the art, is open source and that it looks cool is a big plus ;-)

From my point of view

• Backbone.js is outdated and souldn't be used today and
• FontAwesome is great but missing in Propeller as far I can see.

At the end of the day they could be different UIs and the paperless core could continue to provide the default admin site UI. I see a lot of benefits in the approach of disconnecting the application and it's end user user interface.

[thomasbrueggemann]

Just to push in another idea. I started writing an React/Electron based client for the Paperless API. It currently lives here: https://github.com/thomasbrueggemann/paperless-desktop

At the moment the look & feel is targeted towards macOS and it is very much a work in progress project. Feel free to check it out if you like. I was looking for something that feels more native and maybe even integrates better into the OS with notifications or alarms.

[philippeowagner]

Nice!

[denysvitali]

Wow, congrats @thomasbrueggemann , I really like the UI 👍

[thomasbrueggemann]

Feel free to contribute, there is still plenty to do 😇

[JaimeObregon]

Great job! Thank you very much for this contribution. @danielquinn: Should this alternate frontend be mentioned in the README? To me, it seems mature enough. If so, I can submit a PR updating the docs.

[denysvitali]

@JaimeObregon I agree on that, this should definitively be mentioned!

[danielquinn]

Wow @thomasbrueggemann that's a really slick looking interface. Unfortunately, I don't know anything about React/Electron stuff so I have no idea how to try it out, but if I understand correctly, this is a proper system application and not just a UI on top of Paperless in a browser. Is it cross platform (Linux, Mac, Windows)? Does it work as a client for a Paperless installation on a different computer?

Once you're happy with the stability of paperless-desktop (you said here that "there's still plenty to do") and you've added some documentation for how to install it, I'd love to link to this in Paperless' README for users who want something prettier than my feeble attempts :-)

[denysvitali]

@danielquinn
To try it out you simply clone the project, and then with node.js installed (node+npm) you cd into the project directory and do npm install && npm start (you only have to do npm install once, the other times you only have to type npm start)

This should be a proper application, even though​ it is a "webview" with OS functionality. Btw the app just connects to any Paperless server you want to connect to: as said this uses the Paperless APIs.

About the completeness I let @thomasbrueggemann answer since I only tried to run it but forget I got no instance of Paperless running / set up at the time.

It is cross plattform, I've been able to start it in Arch Linux without any problem, and as Node.JS and Electron are involved (Electron is the base of Atom Editor) this should really be cross platform.

To answer your last question, yes, since this is a wrapper to the APIs of Paperless you can run it from a client computer and connect to a server that runs paperless (it will probably be my config really soon).

[thomasbrueggemann]

@danielquinn Yes, it is cross-platform, as @denysvitali explained. But I used http://photonkit.com/ as a CSS UI library. This only provides the macOS look&feel. But there are other UI librarys out there that produce macOS and Windows looking components (e.g. http://reactdesktop.js.org/demo/), which I just recently discovered.

Regarding completeness: What is missing is the editing of tags, correspondents and documents within the app. Creating tags & correspondents already works.

Ideally the "stable" version would provide a .dmg file for macOS users and a .exe for Windows users. Electron can package those. But for development purposes I wrote some docs in the Wiki.

But yeah, I'll get back to you as soon as it is fully usable.

[danielquinn]

Thanks @denysvitali! I'm afraid my node-foo is just abysmal. I should also note that I had node version 0.12.15 in my environment for another project and that was mucking up the npm install step. However, once I dumped that version and installed a modern one, your steps made it easy to get running.

And it really does look excellent.

There was just one hiccup during my setup: my Paperless installation is on a local server on my LAN on port 8000 and the welcome screen asks for "Hostname" when what it really wants is http://my-hostname:8000. Outside of that though, the process is easy, the implementation clean and elegant. Bravo @thomasbrueggemann.

Let me know when you feel your project is ready to be included in the README here. I might also include a section in the Paperless documentation for "further customisation & improvement" or something.

[schemen]

Hey Guys! Any update on this? :)

[danielquinn]

Re-developing the front-end to be prettier has fallen way-back on the backburner for me on account of the fact that @thomasbrueggemann has been doing an excellent job on paperless-desktop. His work is so good that frankly, I've not seen any real benefit in pulling together a more impressive UI in the browser.

What we have right now is a basic thumbnail frontend accomplished with a bunch of hacks on top of the Django admin. If you'd like to have something more advanced, feel free to setup a separate project that plugs into the API (like paperless-desktop) but if you're asking if/when I'll be continuing my work on rebuilding the UI on the default Paperless install, that'll be a while. Probably not until I decide to try out Angular one day.

[philippeowagner]

@thomasbrueggemann just released a new version a few days ago. I highly recommend to install and use it. paperless-desktop is awesome!

[philippeowagner]

BTW, paperless is awesome as well - but everybody here knows this, right? ;-)

[bkanuka]

I really like the work that @thomasbrueggemann has put in, but it doesn't fit my use case simply because it's a desktop app. My family uses multiple OS's and being able to access files through a web ui is a real benefit. I think it would still be useful to have a non-admin simple interface for just searching and tags.

[lbischof]

A web ui could also be used on phones and chromebooks