JournaKit Legalazy
Transform on-the-fly your OpenDocument .odt files into a simple website on top of Flask and Mustache.
JournaKit Legalazy aims to make the availability of legal documents like Terms of Service, Copyright and Privacy easy like editing a document inside a Word Processor. However, it can be used for any other purpose especially when you don't want to expose a grapgical web interface and you have long texts to quickly put online.
Suggested software
JournaKit Legalazy is developed using these free/libre open source software.
On client:
- LibreOffice (ver. >= 5.4)
To edit data.db on development:
On server:
You can use any other compatible alternative (e.g. OpenOffice on client and Apache as server) but examples and tests you'll find in this document assume you're using these.
Quick start
Just clone this repository on a system provided with Python 3:
git clone https://github.com/chirale/legalazy.git
Make a virtualenv (suggested) and install the dependencies:
pip install -r requirements.txt
Then run the application:
$ export FLASK_APP=views.py
$ flask run
* Running on http://127.0.0.1:5000/
And visit the provided URL.
A page titled Welcome to Legalazy will appear at the test url. Two directories host documents and information about website:
- data - database folder, settings, menu, titles
- docs - .odt documents
These folder will hosts styles:
- static - stylesheets, scripts, images and other static files
- views/templates - Moustache templates
On the first start, a new SQLite database will be created inside the data folder. Open the database file with a reader like DB Browser for SQLite (http://sqlitebrowser.org/).
You’ll find these tables:
- page - list of pages and associated documents
Edit the row with the tilde ~ as slug: this is the page record for the home page. Change the title to something different then Write changes. Refresh the web page to see a different title in the title bar.
Duplicate the home row and change the slug to foo. Then edit title to Foo boo, in_nav to 1 and nav_order to 10 and Write changes.
Refreshing the home page, a new menu item appears as Foo boo.
However, the content will be the same since the same example.odt filename is used for both rows.
Go to database and change the Foo filename to foo.odt. Create a new .odt file inside the docs folder called foo.odt, then refresh the web page to see the content of the document in the browser.
The text document is converted on-the-fly and served as HTML. Indexes and Table of contents are rendered as anchors so you can add those at the beginning of the document to make a working in-page index.
Now you have two browsable slug (path):
- / the home page
- /foo the Foo page
Reference them as absolute path inside any document to allow navigation between pages.
Template
Templates in views/templates are written in Mustache (https://mustache.github.io/). Main variables are:
- style - style from document
- title - page title
- body - HTML content as extracted from document
Style and body are generated by Legalazy using odfpy (https://github.com/eea/odfpy) and presented in the standard base.mustache unescaped with the {{& ...}} syntax.
To serve static files use the static/ directory. Put images, css, fonts and any other static file referencing them like /static/style.css.
Menu
On JournaKit Legalazy a simple, one level menu is provided, delegating inner page navigation to the Index / TOC feature of OpenDocument.
On the page table there are two references to menu:
- in_nav - Set to 1 (True) to display this page in menu, keep 0 to hide
- menu_order - Order menu items by this integer value. The smallest value will be the first menu item.
Fonts
On LibreOffice you can choose what font has to be used for each type of element.
You can use this feature to choose a free font from Google Fonts like this:
- Choose the font
- Copy the code from Embed Font and paste into the head of views/template/base.html
- Download the font to the client (when needed)
- Assign the font to desired elements on LibreOffice
The example.odt provides an example involving the use of the neat font Crimison Text by S. Kosch.
Once you have added the reference to the web font on the web template, declarations made inside LibreOffice will be applied on the web page as well.
Plain text version
To easily integrate Legalazy with textarea elements, a plain text alternative version of every page is available using the Accept HTTP header.
On a valid path, try:
curl -X GET -H 'Accept: application/json' -i 'http://127.0.0.1:5000/privacy'
to get a Json response like this:
{ "body": "Body content \n\n converted in plain text",
"title": "Pagename | Sitename",
"style": "parsed CSS goes here"
}
By default, "style" doesn't appear in results to reduce payload but it can be enabled setting:
KEEP_DOCUMENT_STYLES_APPLICATION_JSON = True
A simple AJAX call can fill the textarea using the Accept header preserving site paths.
Settings
Settings are loaded from settings.py on compile time. Any change needs an application restart to be applied.
Cache
No cache system is currently implemented in Legalazy. However, you can use caching capabilities of our webserver to cache pages from proxy.
This is how to cache responses received from proxied servers on nginx and an example.
Backup and upgrade
To backup data and settings, copy these directories:
- data
- docs
And the file settings.py.
To backup styles and templates, copy these two directories:
- static
- views
You can paste to a fresh installation of JournaKit Legalazy to clone a website or keep stored as backup.