Chapitre 06 - Flask, un framework d'application web.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Chapitre 6 - Flask, un framework d'application web "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Les objets : une rapide introduction\n",
    "\n",
    "En programmation, et particulièrement en python, les objets sont des éléments extrêmements importants.\n",
    "\n",
    "### Ce que l'on a déjà vu mais pas sous ces termes \n",
    "\n",
    "Tout commence avec les classes d'objet. Une classe d'objet est une grande catégorie de valeurs qui sont régies par un ensemble de lois similaires et qui peuvent fonctionner de telle ou telle manière. vous connaissez par exemple les classes `str` et les classes `list`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'str'>\n",
      "<class 'str'>\n",
      "<class 'list'>\n"
     ]
    }
   ],
   "source": [
    "print(type(\"Bonjour le monde\"))\n",
    "print(type(\"Au revoir le monde\"))\n",
    "print(type([1,25]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Les phrases `Bonjour le monde` et `Au revoir le monde` sont toutes deux des chaînes de caractères, issues de la classe `str`. La classe est donc une catégorie de valeurs en programmation. Les instances de classes sont elles appelées des objets. En francais donc, `Bonjour le monde` et `Au revoir le monde` sont des objets de la classe `str`.\n",
    "\n",
    "### Les méthodes \n",
    "Les objets peuvent posséder leurs propres fonctions. Nous en avons déjà vu :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Bonjour le master TNAH\n"
     ]
    }
   ],
   "source": [
    "print(\"Bonjour le monde\".replace(\"monde\", \"master TNAH\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Les fonctions proprent à des classes et à leurs objets sont appelées des méthodes. Elles diffèrent des fonctions habituelles par leur syntaxe : une méthode est appelée après un point `.` et est uniquement accessible pour les classes qui la possèdent. On ne peut pas par exemple faire : "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "ename": "AttributeError",
     "evalue": "'list' object has no attribute 'replace'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m/var/folders/wk/q91g78ss31nd3fqgf5k63k1w0000gp/T/ipykernel_16768/3273904211.py\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;34m[\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;36m2\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;36m3\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mreplace\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m3\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m: 'list' object has no attribute 'replace'"
     ]
    }
   ],
   "source": [
    "[1,2,3].replace(1, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Les attributs\n",
    "Un objet peut aussi avoir des attributs. Les attributs sont des propriétés de ces classes qui fonctionnent comme des variables ou des clés de dictionnaires :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5\n",
      "1\n",
      "Il s'en passe des choses derrière\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "from modules_cours.chapitre5 import objet_exemple\n",
    "\n",
    "print(objet_exemple.attribut_exemple)\n",
    "objet_exemple.attribut_exemple = 1\n",
    "print(objet_exemple.attribut_exemple)\n",
    "# Avec une méthode qui change des choses sans qu'on le voit\n",
    "objet_exemple.change_valeur_attribut_exemple(2)\n",
    "print(objet_exemple.attribut_exemple)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Instancer un objet\n",
    "Pour créer un objet qui ne fait pas partie des types principaux, on utilise généralement le nom de la classe avec les paramètres de base dont elle a besoin. Cela ressemble à l'utilisation d'une fonction :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "8\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "from modules_cours.chapitre5 import ObjetExemple\n",
    "\n",
    "objet2 = ObjetExemple()\n",
    "objet2.attribut_exemple = 8\n",
    "print(objet2.attribut_exemple)\n",
    "print(objet_exemple.attribut_exemple)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nous verrons plus tard comment créer nos propres classes et pourquoi. En attendant, une grande partie de python tourne autour des classes et des objets. Vous êtes maintenant au courant du vocabulaire et du système qui l'entoure."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "# Flask\n",
    "\n",
    "Dans le cadre du cours sur Flask, nous construirons un petit [Gazetteer](https://en.wikipedia.org/wiki/Gazetteer). Un Gazetteer est un index de lieux avec des descriptions quand disponibles de ceux-ci\n",
    "\n",
    "## Introduction\n",
    "\n",
    "Flask est un framework pour le développement d'application web en Python. Son concurrent principal, Django, est un peu plus utilisé mais pose le problème de sa taille. Flask est parfait pour de petits projets ou des projets simples en général.\n",
    "\n",
    "**Recommendation** : Le Tutorial de Miguel Grinberg est une référence ( https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-i-hello-world ). Son tutorial est en cours de publication open-access (fin de publication le 8 Mai 2018), il est disponible en entier (moyennant finance) à l'achat ( https://learn.miguelgrinberg.com/ ). *L'auteur de ce cours ne profite en rien de l'achat. Il s'agit de rendre à César ce qui est à César*.\n",
    "\n",
    "Flask est un package python, et comme beaucoup de package Python, il est disponible au téléchargement via PyPI (**Py**thon **P**ackage **I**ndex) et s'installe via la commande `pip install flask`. \n",
    "\n",
    "### Travailler sur son propre projet : recommendations\n",
    "\n",
    "*Il est important de revenir à ce passage plus tard dans votre cours quand il s'agira de rendre des devoirs*\n",
    "\n",
    "Quand vous commencerez vos propres projets, nous vous recommandons de procéder toujours avec un *environnement virtuel* : une installation en vase clos de python qui permet de ne pas interférer avec d'autres projets. En effet, les packages python ont des version spécifiques (Flask existe ainsi en 0.12.2, 0.12.1, 0.11, 0.10, *etc*.) et suivant les projets, peut-être que différentes versions seront utilisées. Les environnement virtuels permettent cette cohabitation en faisant des installations limitées à un dossier en particulier.\n",
    "\n",
    "#### Exemple\n",
    "\n",
    "Disons que vous commencez un projet simple de veille technologique avec une sorte de micro-blog. Voici les commandes que nous ferions (avec le commentaire)\n",
    "\n",
    "- `cd ~` *vous met dans votre dossier utilisateur*\n",
    "- `mkdir veille-micro-blog` *crée un dossier appelé veille-micro-blog* (**A exécuter une fois seulement**)\n",
    "- `cd veille-micro-blog` *vous déplace dans ce dossier*\n",
    "- `python3 -m venv env` *crée un environnement virtuel dans un sous-dossier. Alternative à `virtualenv -p python3 env` (**A exécuter une fois seulement**)\n",
    "- `source env/bin/activate` *remplace dans votre session de terminal le lien vers le python 3 global par un lien vers le python 3 de votre environnement virtuel*\n",
    "- `pip install flask` *installe flask dans votre environnement virtuel* (**A exécuter une fois seulement**)\n",
    "\n",
    "Soit si l'on sépare entre le à-faire-pour-mettre-en-place et le à-faire-à-chaque-fois :\n",
    "\n",
    "```sh\n",
    "cd ~\n",
    "mkdir veille-micro-blog\n",
    "cd veille-micro-blog\n",
    "python3 -m venv env\n",
    "source env/bin/activate\n",
    "pip install flask\n",
    "```\n",
    "\n",
    "et \n",
    "\n",
    "```sh\n",
    "cd ~/veille-micro-blog\n",
    "source env/bin/activate\n",
    "```\n",
    "\n",
    "#### Note : Suis-je dans un environnement virtuel ?\n",
    "Si un environnement virtuel est chargé, votre terminal affiche généralement son nom entre parenthèse. Sur ma machine, cela correspond à cela :\n",
    "\n",
    "```\n",
    "thibault@pompei:~$ source env/bin/activate\n",
    "(env) thibault@pompei:~$\n",
    "```\n",
    "\n",
    "On peut tapper la commande `which python` pour savoir où se trouve notre python :\n",
    "\n",
    "```\n",
    "thibault@pompei:~$ which python\n",
    "/usr/bin/python\n",
    "thibault@pompei:~$ source env/bin/activate\n",
    "(env) thibault@pompei:~$ which python\n",
    "home/thibault/env/bin/python\n",
    "```\n",
    "\n",
    "*Pour savoir quels packages sont installés, vous pouvez taper `pip freeze` dans votre terminal sous votre environnement virtuel*\n",
    "\n",
    "### Une application simple\n",
    "\n",
    "Voyons comment faire un site simple. Le code qui suit a été copié dans un fichier python au chemin `cours-flask/exemple1/app.py`. **Important**: Vous devez avoir votre environnement virtual *sourcé* et tapez `python cours-flask/exemple1/app.py` depuis le dossier racine de ce cours. Une fois le code lancé, allez sur [http://127.0.0.1:5000/](http://127.0.0.1:5000/)\n",
    "\n",
    "#### Exemple 1\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple1\n",
    "python app.py\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "ename": "ModuleNotFoundError",
     "evalue": "No module named 'flask'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
      "\u001b[0;32m/var/folders/wk/q91g78ss31nd3fqgf5k63k1w0000gp/T/ipykernel_16768/3269274885.py\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32mfrom\u001b[0m \u001b[0mflask\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mFlask\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      2\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      3\u001b[0m \u001b[0mapp\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mFlask\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"Nom de l'application\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      4\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m \u001b[0;34m@\u001b[0m\u001b[0mapp\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mroute\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"/\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'flask'"
     ]
    }
   ],
   "source": [
    "from flask import Flask\n",
    "\n",
    "app = Flask(\"Nom de l'application\")\n",
    "\n",
    "@app.route(\"/\")\n",
    "def index():\n",
    "    return \"Hello world !\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'app' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m/var/folders/wk/q91g78ss31nd3fqgf5k63k1w0000gp/T/ipykernel_16768/2630809407.py\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0;31m# Lancez cette case ensuite pour lancer l'application\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 3\u001b[0;31m \u001b[0mapp\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mrun\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m: name 'app' is not defined"
     ]
    }
   ],
   "source": [
    "# Lancez cette case ensuite pour lancer l'application\n",
    "\n",
    "app.run()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Commentaire du code\n",
    "\n",
    "Le code suivant définit un site simpliste :\n",
    "- on crée une application nommée \"Nom de l'application\". Le nom est obligatoire dans Flask car il permet d'avoir plusieurs applications tournant sur le même serveur et de les différencier pour le serveur. Le serveur n'étant pas au courant des noms de variable, c'est le nom d'application qui lui sert.\n",
    "- on définit une route \n",
    "    - en précédant une fonction de `@app.route(\"url_de_la_route\")`\n",
    "    - en écrivant une fonction qui renvoie le contenu de la réponse (Ici une réponse en plein texte et non en html\n",
    "- on lance un serveur de test via *app.run()* \n",
    "\n",
    "## Qu'est-ce qu'une route (et quel rapport avec les URLs ?)\n",
    "\n",
    "Allons sur le site de l'Ecole des Chartes. Nous avons l'adresse http://www.enc-sorbonne.fr/fr/enseignements. Cette adresse se divise en http://www.enc-sorbonne.fr (le domaine) et `/fr/enseignements` (le chemin). Ce chemin (*route* en anglais) correspond pour le site à une certaine page. Quand on développe un site, on ne définit pas une url complète mais seulement le chemin. Ici, `/fr/enseignements`.\n",
    "\n",
    "Mais il est bien sûr possible de faire plus ! Par exemple, que pouvez-vous me dire de ces deux adresses : http://www.enc-sorbonne.fr/fr/cours/initiation-xml et http://www.enc-sorbonne.fr/fr/cours/panorama-ressources-electroniques-existantes ?\n",
    "\n",
    "Le chemin est similaire jusqu'à sa dernière partie ! On trouve souvent ce genre d'adresse par exemple avec des nombres (ce qui rend la chose encore plus claire !) : https://pleiades.stoa.org/places/109321 et https://pleiades.stoa.org/places/167717 où le chemin se découpe en `/places/[nombre]`. \n",
    "\n",
    "### Définir des routes à paramètres\n",
    "\n",
    "Bien sûr, écrire une route par numéro (on parle de 167.717 entrées là tout de même) parait à la fois gargantuesque et idiot. Il est donc possible de définir une route qui fonctionnerait correctement avec cet identifiant ( `python cours-flask/exemple2/app.py` ) :\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@app.route(\"/places/<place_id>\")\n",
    "def chemin_place(place_id):\n",
    "    return \"On est sur \" + place_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "#### Exemple 2\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple2\n",
    "python app.py\n",
    "```\n",
    "\n",
    "Il est tout autant possible de *conditionner* le type de place_id (il serait intelligent par exemple de limiter place_id aux nombres.) D'après la [documentation](http://flask.pocoo.org/docs/0.12/quickstart/#variable-rules), il est possible de configurer les types suivants :\n",
    "\n",
    "| Type | Exemple | Description |\n",
    "| ---- | ------- | ----------- |\n",
    "| **string**  | foo | (Défaut) Accepte n'importe quelle chaîne |\n",
    "| int     | 5 | Accepte les entiers |\n",
    "| float   | 5.1 | Accepte un décimal anglais (avec un . et non une virgule) |\n",
    "| path    | /foo/bar/fichier.txt | Accepte un chemin (attention aux conflits !) |\n",
    "| any     | njfsd88sd0-f9 | Accepte n'importe quelle valeur |\n",
    "| uuid    | 110e8400-e29b-11d4-a716-446655440000 | Acepte une chaîne [UUID](https://fr.wikipedia.org/wiki/Universal_Unique_Identifier) |\n",
    "\n",
    "Ces types de paramètres de route s'utilisent dans la définition de route comme suit (`python cours-flask/exemple3/app.py`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@app.route(\"/places/<int:place_id>\")\n",
    "def chemin_place(place_id):\n",
    "    return \"On est sur \" + str(place_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Désormais, `place_id` ne répond qu'aux entiers et est automatiquement converti en entier (ce qui nous oblige à la transformer en chaîne pour la concaténer.\n",
    "\n",
    "\n",
    "#### Exemple 3\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple3\n",
    "python app.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Les *templates*\n",
    "\n",
    "### Introduction\n",
    "\n",
    "Jusque là, c'est très bien, mais afficher juste une chaîne de caractère ne fait pas de grands sites. Il va nous falloir envoyer du html. Bien sûr, on pourrait écrire cela (`python cours-flask/exemple4/app.py`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@app.route(\"/\")\n",
    "def accueil():\n",
    "    nom_du_site = \"Gazetteer\"\n",
    "    return '''\n",
    "<html>\n",
    "    <head>\n",
    "        <title>{nom}</title>\n",
    "    </head>\n",
    "    <body>Bienvenue !</body>\n",
    "</html>'''.format(nom=nom_du_site)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mais si cela marche bien pour ce petit exemple, cela deviendra vite compliqué et illisible quand vous aurez de (très) nombreuses pages avec un HTML plus complexe qu'un `title` et un `body`. C'est pour cela que de très nombreux frameworks offrent un système de *template*. Un template est un fichier HTML, XML ou équivalent qui sera lu par votre framework et complété le cas échéant par des informations que vous fournirez.\n",
    "\n",
    "Dans Flask, les templates sont généralement mis dans un sous-dossier `templates` du dossier principal de l'application (ici : `cours-flask/exemple4/templates/accueil.html`). Les variables sont alors incluses via des doubles accolades :\n",
    "\n",
    "```html\n",
    "<html>\n",
    "    <head>\n",
    "        <title>{{nom}}</title>\n",
    "    </head>\n",
    "    <body>Bienvenue !</body>\n",
    "</html>\n",
    "```\n",
    "\n",
    "Ce fichier templates est ensuite déclaré et rendu par votre application Flask :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from flask import Flask, render_template\n",
    "\n",
    "app = Flask(\"Application\")\n",
    "\n",
    "\n",
    "@app.route(\"/\")\n",
    "def accueil():\n",
    "    return render_template(\"accueil.html\", nom=\"Gazetteer\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Commentaire de code \n",
    "\n",
    "Par rapport à l'utilisation précédente, nous avons :\n",
    "- importé la fonction `render_template` depuis le module `flask`\n",
    "- utilisé la fonction `render_template` qui prend:\n",
    "    - en premier argument le chemin du template (à partir du sous-dossier template)\n",
    "    - des arguments nommés pour le reste. Ces arguments nommés sont ensuite utilisés comme des variables dans le template\n",
    "\n",
    "**Important:** Pour lancer les applications désormais, vous devrez vous déplacer dans le bon dossier. Pour lancer cet exemple, vous devez avoir votre environnement virtuel sourcé puis taper les commandes suivantes depuis la racine de votre dossier cours :\n",
    "\n",
    "\n",
    "#### Exemple 4\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple4\n",
    "python app.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Information supplémentaire\n",
    "\n",
    "Le système de template de Flask s'appelle [Jinja](http://jinja.pocoo.org/) et il a une vie en dehors de Flask (vous pouvez l'utiliser sans utiliser Flask.)\n",
    "\n",
    "#### Exercice\n",
    "\n",
    "Ajouter à l'exemple précédent une variable comportant votre nom de telle manière que, suivant la valeur de variable, le template affiche `Bienvenue VotreNom`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conditions dans les templates\n",
    "\n",
    "Les templates vont plus loin que le simple affichage de variable, ils permettent aussi de réaliser des conditions pour vérifier qu'une chose ou une autre existe ou bien qu'une valeur particulière est affichée. Par exemple, si l'on avait potentiellement une variable `lieux` qui contiendrait le nombre de lieux enregistrés dans notre index topographique.\n",
    "\n",
    "Nous écririons donc \n",
    "\n",
    "```html\n",
    "...\n",
    "\n",
    "    <body>\n",
    "        <h1>Bienvenue !</h1>\n",
    "        <p>Il y a {{lieux|length} enregistrés, voici le premier : {{lieux[0]}}</p>\n",
    "    </body>\n",
    "</html>\n",
    "```\n",
    "\n",
    "**Note** : Il n'est pas possible de faire `len(lieux)` dans un template de Flask. Nous sommes obligés de passer par l'équivalent `{{lieux|length}}`\n",
    "\n",
    "Mais le résultat ne serait pas très convivial. Afficher potentiellement `Voici le premier : ` et du vide donnera l'impression que le site ne marche pas. Et pour cause. Nous utiliserons donc un `if` :\n",
    "\n",
    "```html\n",
    "...\n",
    "\n",
    "    <body>\n",
    "        <h1>Bienvenue !</h1>\n",
    "        <p>\n",
    "            Il y a {{lieux|length}} enregistrés\n",
    "            {% if lieux %}\n",
    "            , voici le premier : {{lieux[0]}}\n",
    "            {% endif %}\n",
    "    </p>\n",
    "    </body>\n",
    "</html>\n",
    "```\n",
    "\n",
    "Un bloc `if` est alors commencé par un `{% if condition %}` ou *conditions* est une condition python classique (on se souvient qu'une liste vide est égal à False et que donc par opposition, `lieux` sera positif si il y a un seul élément dans la liste). Le bloc `{% if condition %}` se termine nécessairement par un nouveau bloc `{% endif %}`.\n",
    "\n",
    "Il est bien sûr possible d'aller plus loin qu'un `if` : on peut compléter ce bloc par un `{% elif %}` et/ou un `{% else %}` \n",
    "\n",
    "```html\n",
    "...\n",
    "\n",
    "    <body>\n",
    "        <h1>Bienvenue !</h1>\n",
    "        <p>\n",
    "            {% if lieux %}\n",
    "                Il y a {{lieux|length}} enregistrés , voici le premier : {{lieux[0]}}\n",
    "            {% else %}\n",
    "                La base de données est en cours de constitution\n",
    "            {% endif %}\n",
    "    </p>\n",
    "    </body>\n",
    "</html>\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from flask import Flask, render_template\n",
    "\n",
    "app = Flask(\"Application\")\n",
    "\n",
    "\n",
    "@app.route(\"/\")\n",
    "def accueil(exemple=None):\n",
    "    lieux = [\"Col. Lugdunum\", \"Augustomagus\"]\n",
    "    return render_template(\"accueil.html\", nom=\"Gazetteer\", lieux=lieux)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Exemple 5\n",
    "\n",
    "Lancez l'exemple 5 pour pouvoir voir le résultat \n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple5\n",
    "python app.py\n",
    "```\n",
    "\n",
    "puis allez sur http://127.0.0.1:5000/ et sur http://127.0.0.1:5000/exemple/exemple1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Les dictionnaires dans les templates\n",
    "\n",
    "Les dictionnaires dans les templates peuvent être appelés différemment : on peut utiliser le `.` en place des crochets habituels. Ainsi pour la liste de dictionnaires qui suit\n",
    "\n",
    "```python\n",
    "lieux = [\n",
    "    {\n",
    "        \"nom\": \"Col. Lugdunum\",\n",
    "        \"moderne\": \"Lyon\",\n",
    "        \"latlong\": [45.762095775, 4.822438025],\n",
    "        \"type\": \"ville\",\n",
    "        \"description\": \"Col. Lugdunum was a Roman military colony from 43 BC and a major center in Gaul. Marcus Agrippa was involved in its expansion and two Roman emperors, Claudius and Caracalla, were born there.\"\n",
    "    },\n",
    "    {\n",
    "        \"nom\": \"Samarobriva Ambianorum\",\n",
    "        \"moderne\": \"Amiens\",\n",
    "        \"type\": \"ville\",\n",
    "        \"description\": \"An ancient place, cited: BAtlas 11 C3 Samarobriva Ambianorum \",\n",
    "        \"latlong\": [49.8936075, 2.297948]\n",
    "    }\n",
    "]\n",
    "```\n",
    "\n",
    "on pourra appelé au choix `{{lieux[0][\"nom\"]}}` ou `{{lieux[0].nom}}` \n",
    "\n",
    "#### *templates/accueil.html*\n",
    "\n",
    "```html\n",
    "\n",
    "        <p>\n",
    "            {% if lieux %}\n",
    "                Il y a {{ lieux|length }} enregistrés , voici le premier : {{lieux[0].nom}}\n",
    "            {% else %}\n",
    "                La base de données est en cours de constitution\n",
    "            {% endif %}\n",
    "    </p>\n",
    "```\n",
    "\n",
    "#### *templates/place.html*\n",
    "\n",
    "```html\n",
    "<html>\n",
    "    <head>\n",
    "        <title>Gazetteer {%if lieu %}| Lieu : {{lieu.nom}} {% endif %}</title>\n",
    "    </head>\n",
    "    <body>\n",
    "        {% if lieu %}\n",
    "            <h1>{{lieu.nom}}</h1>\n",
    "            <h2>{{lieu.moderne}}</h2>\n",
    "            <dl>\n",
    "                <dt>Longitude</dt><dd>{{lieu.latlong[1]}}</dd>\n",
    "                <dt>Latitude</dt><dd>{{lieu.latlong[0]}}</dd>\n",
    "                <dt>Description</dt><dd>{{lieu.description}}</dd>\n",
    "                <dt>Type</dt><dd>{{lieu.type}}</dd>\n",
    "            </dl>\n",
    "        {% else %}\n",
    "            <p>La base de données est en cours de constitution</p>\n",
    "        {% endif %}\n",
    "    </body>\n",
    "</html>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Contenu d'app.py\n",
    "\n",
    "```python\n",
    "from flask import Flask, render_template\n",
    "\n",
    "app = Flask(\"Application\")\n",
    "\n",
    "lieux = [\n",
    "    {\n",
    "        \"nom\": \"Col. Lugdunum\",\n",
    "        \"moderne\": \"Lyon\",\n",
    "        \"latlong\": [45.762095775, 4.822438025],\n",
    "        \"type\": \"ville\",\n",
    "        \"description\": \"Col. Lugdunum was a Roman military colony from 43 BC and a major center in Gaul. Marcus \"\n",
    "                       \"Agrippa was involved in its expansion and two Roman emperors, Claudius and Caracalla, \"\n",
    "                       \"were born there.\"\n",
    "    },\n",
    "    {\n",
    "        \"nom\": \"Samarobriva Ambianorum\",\n",
    "        \"moderne\": \"Amiens\",\n",
    "        \"type\": \"ville\",\n",
    "        \"description\": \"An ancient place, cited: BAtlas 11 C3 Samarobriva Ambianorum \",\n",
    "        \"latlong\": [49.8936075, 2.297948]\n",
    "    }\n",
    "]\n",
    "\n",
    "\n",
    "@app.route(\"/\")\n",
    "def accueil():\n",
    "    return render_template(\"accueil.html\", nom=\"Gazetteer\", lieux=lieux)\n",
    "\n",
    "\n",
    "@app.route(\"/place/<int:place_id>\")\n",
    "def lieu(place_id):\n",
    "    return render_template(\"place.html\", nom=\"Gazetteer\", lieu=lieux[place_id])\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Exemple 6\n",
    "\n",
    "Lancez l'exemple 6 pour pouvoir voir le résultat \n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple6\n",
    "python app.py\n",
    "```\n",
    "\n",
    "puis allez sur http://127.0.0.1:5000/ puis sur http://127.0.0.1:5000/place/0 ou http://127.0.0.1:5000/place/1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Boucles dans les templates et liens\n",
    "\n",
    "Il ne manquait donc plus qu'une chose du python traditionnel: les boucles. Une fois ce type d'expression apprise, vous auraient l'ensemble des expressions importantes dans le système de template de Flask. Tout comme les `if`, les expressions de boucles se font entre des `{% %}` : `{% for valeur in conteneur %}` et `{%endfor%}`.\n",
    "\n",
    "```html\n",
    "Il y a {{lieux|length}} enregistrés :\n",
    "<ul>\n",
    "    {% for lieu in lieux %}\n",
    "        <li>{{lieu.nom}}</li>\n",
    "    {% endfor %}\n",
    "</ul>\n",
    "```\n",
    "\n",
    "Le système fonctionne comme les boucles `for` en python : `{% for _ in _ %}` est donc aussi valable pour `dict.items()`, `dict.values()`, `dict.keys()`, *etc.*\n",
    "\n",
    "À partir de cette boucle, il serait intéressant de se servir de cette page d'accueil pour faire un index. Et pour faire un index, il faut des liens. Et pour faire des liens... il faut `url_for()` dans Flask ! La fonction `url_for()` est appelée du côté du template et doit prendre comme premier argument le nom de la fonction qui vous intéresse (par exemple `lieu` est le nom de notre fonction pour la route `@app.route(\"/place/<int:place_id>\")`. Les arguments suivants correspondent aux arguments nécessaire à la construction de l'url (ici `place_id`) : `url_for(\"lieu\", place_id=0)` retournera la valeur `/place/0`. Dans le HTML, cela donnera : \n",
    "\n",
    "```html\n",
    "Il y a {{lieux|length}} enregistrés :\n",
    "<ul>\n",
    "    {% for lieu_id, lieu in lieux.items() %}\n",
    "        <li><a href=\"{{url_for('lieu', place_id=lieu_id)}}\">{{lieu.nom}}</a></li>\n",
    "    {% endfor %}\n",
    "</ul>\n",
    "```\n",
    "\n",
    "ou bien pour retourner à l'accueil : \n",
    "\n",
    "```html\n",
    "<p><a href=\"{{url_for('accueil')}}\">Retour à l'accueil</a></p>\n",
    "```\n",
    "\n",
    "**Note:** Nous avons changé la liste en un dictionnaire de dictionnaire dans le fichier app.py : \n",
    "\n",
    "```python\n",
    "lieux = {\n",
    "    0: {\n",
    "        \"nom\": \"Col. Lugdunum\",\n",
    "        \"moderne\": \"Lyon\",\n",
    "        \"latlong\": [45.762095775, 4.822438025],\n",
    "        \"type\": \"ville\",\n",
    "        \"description\": \"Col. Lugdunum was a Roman military colony from 43 BC and a major center in Gaul. Marcus \"\n",
    "                       \"Agrippa was involved in its expansion and two Roman emperors, Claudius and Caracalla, \"\n",
    "                       \"were born there.\"\n",
    "    },\n",
    "    #...\n",
    "}\n",
    "```\n",
    "\n",
    "#### Exemple 7\n",
    "\n",
    "Lancez l'exemple 7 pour pouvoir voir le résultat\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple7\n",
    "python app.py\n",
    "```\n",
    "\n",
    "puis allez sur http://127.0.0.1:5000/ "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Héritage dans les templates\n",
    "\n",
    "La composition d'un site web est souvent répétitive : on retrouve ainsi très souvent le même en-tête, le même menu, le même pied-de-page et c'est le centre du contenu qui change.\n",
    "\n",
    "![Composition classique d'une page web en vertical](images/decoupage.site.png)\n",
    "\n",
    "Mais nous avons déjà deux pages. Comme d'habitude, les programmeur-se-s ont cherché à éviter la répétition de tous les éléments. Pour deux raisons :\n",
    "\n",
    "- c'est une perte de temps de répéter les éléments, même en copiant-collant\n",
    "- c'est un véritable enfer de maintenance : il faut vérifier à chaque changement que l'ensemble des pages ont été modifiées.\n",
    "\n",
    "On va donc chercher à créer un ensemble de sous-pages qui ne contiennent que l'élément *main* tandis que l'entourage de la page sera importée depuis notre dite page. Ainsi nos pages seront constituées :\n",
    "- d'un bloc principal contenant les éléments voués à se répéter\n",
    "- d'un bloc secondaire contenant les informations spécifiques à une page \n",
    "\n",
    "![Découpage des éléments et responsabilités des blocs](images/incrustation.site.png)\n",
    "\n",
    "Pour faire cela sous Jinja, il existe un moyen simple : la définition de block via `{% block nom_de_bloc %}` et `{% endblock %}`. On définit un block dans le fichier conteneur.html que l'on étend dans les pages via `{% extends \"conteneur.html\" %}` (Attention, pas de `{%endextends%}` ici !\n",
    "\n",
    "### Avec un seul bloc d'import\n",
    "\n",
    "#### templates/conteneur.html\n",
    "\n",
    "```html\n",
    "<html>\n",
    "    <head>\n",
    "        <title>Gazetteer</title>\n",
    "    </head>\n",
    "    <body>\n",
    "        <div><h1>Bienvenue sur le Gazetteer</h1></div>\n",
    "        <div>{% block corps%}{%endblock%}</div>\n",
    "    </body>\n",
    "</html>\n",
    "```\n",
    "\n",
    "#### templates/accueil.html\n",
    "\n",
    "```html\n",
    "{% extends \"conteneur.html\" %}\n",
    "{% block corps %}\n",
    "Il y a {{lieux|length}} enregistrés :\n",
    "<ul>\n",
    "    {% for lieu_id, lieu in lieux.items() %}\n",
    "        <li><a href=\"{{url_for('lieu', place_id=lieu_id)}}\">{{lieu.nom}}</a></li>\n",
    "    {% endfor %}\n",
    "</ul>\n",
    "{% endblock %}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Deux blocks\n",
    "\n",
    "Il est aussi possible d'étendre plusieurs blocs avec un seul conteneur : il suffit de déclarer l'ensemble des blocs et de les remplir le cas échéant : \n",
    "\n",
    "#### templates/conteneur.html\n",
    "\n",
    "```html\n",
    "<html>\n",
    "    <head>\n",
    "        <title>Gazetteer {%block titre %}{%endblock%}</title>\n",
    "    </head>\n",
    "    <body>\n",
    "        <div><h1>Bienvenue sur le Gazetteer</h1></div>\n",
    "        <div>{% block corps%}{%endblock%}</div>\n",
    "    </body>\n",
    "</html>\n",
    "```\n",
    "\n",
    "#### templates/pages/accueil.html\n",
    "*Pour plus de lisibilité, il est commun de regrouper les éléments semblables dans des sous-dossiers de templates.*\n",
    "\n",
    "```html\n",
    "{% extends \"conteneur.html\" %}\n",
    "{% block corps %}\n",
    "Il y a {{lieux|length}} enregistrés :\n",
    "<ul>\n",
    "    {% for lieu_id, lieu in lieux.items() %}\n",
    "        <li><a href=\"{{url_for('lieu', place_id=lieu_id)}}\">{{lieu.nom}}</a></li>\n",
    "    {% endfor %}\n",
    "</ul>\n",
    "{% endblock %}\n",
    "```\n",
    "\n",
    "#### templates/pages/places.html\n",
    "\n",
    "```html\n",
    "{% extends \"conteneur.html\" %}\n",
    "{% block titre %}\n",
    "    {%if lieu %}| Lieu : {{lieu.nom}} {% endif %}\n",
    "{% endblock %}\n",
    "\n",
    "{% block corps %}\n",
    "    {% if lieu %}\n",
    "        <h1>{{lieu.nom}}</h1>\n",
    "        <h2>{{lieu.moderne}}</h2>\n",
    "        <dl>\n",
    "            <dt>Longitude</dt><dd>{{lieu.latlong[1]}}</dd>\n",
    "            <dt>Latitude</dt><dd>{{lieu.latlong[0]}}</dd>\n",
    "            <dt>Description</dt><dd>{{lieu.description}}</dd>\n",
    "            <dt>Type</dt><dd>{{lieu.type}}</dd>\n",
    "        </dl>\n",
    "    {% else %}\n",
    "        <p>La base de données est en cours de constitution</p>\n",
    "    {% endif %}\n",
    "    <p><a href=\"{{url_for('accueil')}}\">Retour à l'accueil</a></p>\n",
    "{% endblock %}\n",
    "```\n",
    "\n",
    "#### Exemple 8\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple8\n",
    "python app.py\n",
    "```\n",
    "\n",
    "puis allez sur http://127.0.0.1:5000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Les includes\n",
    "\n",
    "En plus de bloc, il existe la possibilité non pas d'étendre mais d'inclure un ensemble d'éléments. Cela devient très pratique quand on veut multiplier les squelettes principaux ou qu'un ensemble de sous-éléments se répètent (par exemple, plusieurs pages ont une visionneuse d'image). Le découpage logique se fait alors comme suit :\n",
    "- un ensemble de pages\n",
    "- des conteneurs qui seront étendus par ces pages\n",
    "- des sous-éléments incrustable dans les conteneurs ou les pages \n",
    "\n",
    "![Incrustation avancée avec des sous-éléments](images/incrustation.avancee.png)\n",
    "\n",
    "Cette inclusion se fait via `{% include \"chemin/vers/inclusion/html\" %}` et ne possède pas de fin `{% endincludes %}`.\n",
    "\n",
    "Nous pouvons donc changer `conteneur.html` et créer une page `partials/metadata.html`. Notez que si vous avez des `blocks` dans un include, le block ne sera pas complété par la page.\n",
    "\n",
    "#### conteneur.html\n",
    "\n",
    "```html\n",
    "<html>\n",
    "    <head>\n",
    "        <title>Gazetteer {%block titre %}{%endblock%}</title>\n",
    "        {% include \"partials/metadata.html\" %}\n",
    "    </head>\n",
    "    <body>\n",
    "        <div><h1>Bienvenue sur le Gazetteer</h1></div>\n",
    "        <div>{% block corps%}{%endblock%}</div>\n",
    "    </body>\n",
    "</html>\n",
    "\n",
    "```\n",
    "\n",
    "\n",
    "#### partials/metadata.html\n",
    "\n",
    "```html\n",
    "<meta name=\"description\" content=\"Gazetteer formidable développé par l'Ecole Nationale des Chartes\">\n",
    "<meta name=\"keywords\" content=\"Gazetteer,Chartes,Ecole,Topographie,Dictionnaire,Topologie\">\n",
    "<meta name=\"author\" content=\"Thibault Clérice\">\n",
    "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n",
    "```\n",
    "\n",
    "#### Exemple 9\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple9\n",
    "python app.py\n",
    "```\n",
    "\n",
    "puis allez sur http://127.0.0.1:5000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Les assets\n",
    "\n",
    "Pour finir ce chapitre sur les bases de flask, je propose que l'on essaye de faire quelque chose d'un peu plus joli. Parce que pour l'instant... disons que le design est discutable.\n",
    "\n",
    "Les assets, contrairement aux templates, sont des fichiers statiques : ils ne nécessitent pas de calcul ou de remplacement. Alors pour les lier, il suffit de les placer dans un dossier `/static/` dans le dossier principal de l'application et d'y mettre le nécessaire (on a chargé pour l'exemple 10 les fichiers nécessaires à bootstrap)\n",
    "\n",
    "Pour réaliser le lien vers un fichiers statique, on utilise aussi la fonction `url_for()`. En premier paramètre, on utilise le nom `\"static\"` et le paramètre nommé `filename=\"chemin/vers/le/fichier/depuis/le/dossier/static.gif\"`. Exemple pour le fichier css de bootstrap :\n",
    "\n",
    "```html\n",
    "<link rel=\"stylesheet\" href=\"{{ url_for('static', filename='css/bootstrap.css')}}\">\n",
    "```\n",
    "\n",
    "#### Exemple 10\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple10\n",
    "python app.py\n",
    "```\n",
    "\n",
    "puis allez sur http://127.0.0.1:5000\n",
    "\n",
    "\n",
    "## Pour aller plus loin\n",
    "\n",
    "Les systèmes de template étant utilisés par de nombreux systèmes, regardez les fichiers `supports/chapitre-5/template.omeka.php` et `supports/chapitre-5/template.wordpress.php` qui sont tous deux des fichiers templates pour Omeka et WordPress. Notez que PHP, contrairement à python, peut s'écrire directement dans un fichier html et qu'`echo` est à peu près l'équivalent de `print` en python"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}