e7ec53304d | 2 years ago | |
---|---|---|
__pycache__ | 2 years ago | |
static | 2 years ago | |
templates | 2 years ago | |
.~lock.data_trees.csv# | 2 years ago | |
README.md | 2 years ago | |
app.py | 2 years ago | |
data_trees.csv | 2 years ago | |
dreaming_trees.py | 2 years ago | |
dreams_selection_till_p47.txt | 2 years ago | |
pagedjs.py | 2 years ago | |
requirements.txt | 2 years ago | |
run.sh | 2 years ago | |
settings.py | 2 years ago | |
utils.py | 2 years ago |
README.md
Pagedjs Flask boilerplate / recipe
The boilerplate uses the python framework Flask to run the webinterface and to generate the HTML of the book. To generate the PDF it uses the javascript library paged.js together with the chromium webbrowser in headless mode.
The
Index
Installation
This installation guide assumes a basic understanding of the shell or terminal. If you are not familiar with it there are many introduction tutorials online. During the summerschool relearn this short introduction was written.
Getting the boilerplate
The easiest way to get this boilerplate is to download a copy of it on gitlab.
You can also clone the repository using git. Make sure you execute the command in the folder where you want to place the boilerplate:
git clone git@gitlab.constantvzw.org:anais_berck/pagedjs-flask-boilerplate.git
Python3
The boilerplate uses Python 3. If you know you have it installed this step can be skipped. If you are not sure it's installed on your computer, run the following command in the terminal:
python3 --version
It should output the version number of the copy of Python you have installed, something like:
3.10.7
If the terminal instead prints something like:
Command 'python3' not found...
It is most likely Python isn't installed. You can download it, and find installation instructions here.
Flask
It is advised to install Flask in a virtual environment, how to use and install them isn't covered here. Please find more information on virtual environments in the Python documentation
Extensive installation instructions for Flask can be found here, but it is easiest to install it with the python package manager (pip), with the command:
pip3 install flask
Node
Pagedjs-cli uses node.js
, and it is installed with the node pakacge manager npm
if you know you have installed a (recent) version of node.js
and npm
, you can skip this step. First check npm
is installed using the command:
npm --version
It should output the version number of the copy of npm you have installed, something like:
8.15.1
If the terminal instead prints something like:
Command 'npm' not found...
It is most likely npm (and node) arent't installed. There are several ways on how to do it. The easiest is with nvm, the node virtual manage. You can find extensive instructions on it here. But it can be installed with the following command, it downloads and executes the install script:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
Then, to avoid having to restart your terminal, run:
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
Then install the latest Long Term Support release of node and npm:
nvm install --lts
pagedjs-cli
Finally install pagedjs-cli, with the command:
npm install -g pagedjs-cli
It is quite likely you'll get some warning messages during installation. This doesn't mean it failed though!
To verify pagedjs-cli
was correctly installed, run:
pagedjs-cli --help
This should print out the usage instructions. When it produces an error it is quite likely your version of node
and or npm
was too old. In the previous step you'll find instructions on how to install a more recent version of node
using nvm
.
Starting the boilerplate
Now that all the pieces are in place you can start the boilerplate by running:
./run.sh
This command should start the Flask application. If you open a browser and load the url: http://localhost:5000 you should see the index of the boiler plate. When you click the link 'generate' a PDF-file should be downloaded 🤞.
Contents of the boilerplate
app.py
the flask webapp, generating the viewspagedjs.py
helper functions to run pagedjs-cli from pythonutils.py
utitilities for generative bookstemplates/index.html
jinja template for the indextemplates/book.html
jinja template for the book itselfstatic/style.css
css style rules for the index and book (it's possible to split them up, also adjust the templates then)static/pagedjs.interface.css
css style rules provided by paged.js to have a more rich preview in debug mode
Usage
Running the boilerplate
The boilerplate can be started with the bash script run.sh
. This script starts the application in development mode. Which is practical during development as it reloads whenever it detects a change to the code.
Debug mode
The boilerplate has a debug mode. In debug mode the generate function doesn't generate a PDF but instead returns an HTML preview with the help of paged.js. This should be slightly quicker, but also allows to inspect the generated HTML. Activate the debug mode by setting the DEBUG
variable in settings.py
to True
:
DEBUG = True
Adjusting the boilerplate
The boilerplate uses a Flask app to generate the html for the index and book, the code of the application is in the file app.py
. You can find more information on Flask here. Summarised very shortly, Flask is a light frame work for web applications. Flask applications are written in python, these applcations consist of functions generating HTML using the route()
decorator these functions are linked to a url, in app.py
the index is defined like so:
@app.route('/')
def index():
return render_template('index.html')
On line 1 of this snippet the url is defined, and on line 3 the html is generated and returned to the browser of the visitor. Flask uses the Jinja templating engine. You can find extensive documentation on it here.
The application has two views, defined by similarly named functions: index
and generate
. The function index
generates and shows the homepage. The function generate
generates the HTML book. You can insert the code for your book in this function.
The application uses Jinja templates to generate the HTML of the book. It is advised to generate your data in the application and to then use this data in the template to generate the HTML. The data can be forwarded to the tempate by extending the render_template
call in the python script using keyword arguments. Where you define the name of the argument before the equal sign, and assign the value after it:
generated_data = function_call()
html = render_template('book.html', DEBUG=DEBUG, generated_data=generated_data)
The variable will be available in the template under the name that you set before the equal sign (=):
<section>
{{ generated_data }}
</section>
It is possible to generate HTML in the python script and to forward this HTML as a variable to the template, it is important though to mark it in the template as a snippet of HTML that shouldn't be escaped. You do this with the safe
filter:
{{ variable_containing_html|safe }}
The template templates/book.html
is used with for the book, the template templates/index.html
is used for the index-page of the application. The styles are set in static/style.css
.
Deployment
To do: instructions on how to install it on a server and make it publicly accessible. It should be noted this boilerplate does not make any effort at rate-limiting.
Further reading
- In the documentation of paged.js a lot of information on print specific functionality in CSS can be found.
- Jinja documentation
- Flask documentation