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 pagedjs together with the chromium webbrowser in headless mode.
The boilerplate uses the python framework [Flask](https://palletsprojects.com/p/flask/) to run the webinterface and to generate the HTML of the book. To generate the PDF it uses the javascript library [paged.js](https://pagedjs.org/) together with the chromium webbrowser in headless mode.
# Installation
The
First [download](https://gitlab.constantvzw.org/anais_berck/pagedjs-flask-boilerplate/-/archive/main/pagedjs-flask-boilerplate-main.zip) it on gitlab.
## Index
Or clone the repository:
- [Installation](#installation)
- [Contents of the boilerplate](#contents-of-the-boilerplate)
This boilerplate uses Python 3 and the framework [Flask](https://palletsprojects.com/p/flask/).
> This installation guide assumes a basic understanding of the shell or terminal. If you are not familiar with it there are many [introduction tutorials](https://www.digitalocean.com/community/tutorials/an-introduction-to-the-linux-terminal) online. During the summerschool relearn this [short introduction](http://relearn.be/2013/r/cheat-sheet::git-and-the-command-line.html) was written.
Find information on how to [install python here](https://www.python.org/downloads/)
### Getting the boilerplate
To install the requirements, move to the directory this readme is located in, and then run. Optionally create a virtual environment:
The easiest way to get this boilerplate is to [download](https://gitlab.constantvzw.org/anais_berck/pagedjs-flask-boilerplate/-/archive/main/pagedjs-flask-boilerplate-main.zip) a copy of it on gitlab.
`pip install -r requirements.txt`
You can also clone the repository using git. Make sure you execute the command in the folder where you want to place the boilerplate:
Then install [pagedjs-cli](https://gitlab.coko.foundation/pagedjs/pagedjs-cli), with the command:
___ in case pagedjs-cli does not show up, follow these instructions:
### 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:
```bash
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](https://www.python.org/downloads/).
### 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](https://docs.python.org/3/tutorial/venv.html)
Extensive installation instructions for Flask can be found [here](https://flask.palletsprojects.com/en/latest/installation/), but it is easiest to install it with the python package manager (pip), with the command:
```bash
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:
```bash
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](https://github.com/nvm-sh/nvm). You can find extensive instructions on it [here](https://github.com/nvm-sh/nvm#installing-and-updating). But it can be installed with the following command, it downloads and executes the install script:
Then install the latest Long Term Support release of node and npm:
```bash
nvm install --lts
```
### pagedjs-cli
Finally install [pagedjs-cli](https://gitlab.coko.foundation/pagedjs/pagedjs-cli), with the command:
```bash
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:
```bash
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](#node) 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:
```bash
./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 🤞.
<!--
### in case pagedjs-cli does not show up, follow these instructions:
check the version of node (this should be: v16.17.0)
check the version of node (this should be: v16.17.0)
'$ node --version'
```sh
node --version
```
check if nvm is installed
check if nvm is installed
'$ nvm'
```bash
nvm
```
if nvm does not show up, install nvm with the following command:
if nvm does not show up, install nvm with the following command:
Finally edit a copy of `settings.example.py` and save it as `settings.py`.
Finally edit a copy of `settings.example.py` and save it as `settings.py`.
It is important to set the `PAGEDJS_BINARY_PATH`, you should be able to find it
It is important to set the `PAGEDJS_BINARY_PATH`, you should be able to find it
by running: `whereis pagedjs-cli`.
by running: `whereis pagedjs-cli`. -->
Now you should be able to start the interface with: `./run.sh`.
# Contents of the boilerplate
## Contents of the boilerplate
- `app.py` the flask webapp, generating the views
- `app.py` the flask webapp, generating the views
- `pagedjs.py` helper functions to run pagedjs-cli from python
- `pagedjs.py` helper functions to run pagedjs-cli from python
- `utils.py` utitilities for generative books
- `utils.py` utitilities for generative books
- `templates/index.html` template for the index
- `templates/index.html`jinja template for the index
- `templates/book.html` template for the book itself
- `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/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
- `static/pagedjs.interface.css` css style rules provided by paged.js to have a more rich preview in debug mode
# Usage
The boilerplate essentially has two views: `index` and `generate`. The `index` shows the homepage and a link to the `generate` function. In this example the generated book is downloaded as a PDF.
## 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`:
```python
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](https://flask.palletsprojects.com/en/2.2.x/quickstart/). 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](https://flask.palletsprojects.com/en/2.2.x/quickstart/#routing) these functions are linked to a url, in `app.py` the index is defined like so:
```python
@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](https://jinja.palletsprojects.com/en/3.1.x/) templating engine. You can find extensive documentation on it [here](https://jinja.palletsprojects.com/en/3.1.x/templates/).
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:
```python
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 (=):
```jinja
<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:
```jinja
{{ 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`.
The template `templates/book.html` is used with styles from `static/style.css` to generate the PDF, adjust them to adjust your book. In `app.py` the function generate loads the template, adjust that function to generate context and / or HTML.
## Deployment
In the [documentation of paged.js](https://pagedjs.org/documentation/) a lot of information on print specific functionality in CSS can be found.
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.
# Deployment
## Further reading
Todo
Note: this boilerplate does not make any effort at rate-limiting.
- In the [documentation of paged.js](https://pagedjs.org/documentation/) a lot of information on print specific functionality in CSS can be found.
