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
• Contents of the boilerplate
• Usage
• Deployment
• Furter reading

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 views
• pagedjs.py helper functions to run pagedjs-cli from python
• utils.py utitilities for generative books
• templates/index.html jinja template for the index
• templates/book.html jinja template for the book itself
• static/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