Chapitre 9 - Premier formulaire et la recherche.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Chapitre 9 - Premier formulaire et la recherche \n",
    "===\n",
    "\n",
    "Nous savons désormais :\n",
    "\n",
    "- Afficher des pages\n",
    "- Récupérer des données\n",
    "\n",
    "Mais le propre d'un site est d'être un peu plus interactif qu'un livre, et l'une des fonctions les plus recherchées est souvent la question.\n",
    "\n",
    "## Quelques recommandations quant aux formulaires \n",
    "\n",
    "### Le formulaire en HTML\n",
    "\n",
    "Les éléments nécessaires à un formulaire en HTML sont :\n",
    "\n",
    "- la balise `<form />` qui doit englober l'ensemble des champs et des boutons\n",
    "- on spécifiera la méthode à employer pour envoyer les données (attribut `method`)\n",
    "- on spécifiera l'URL vers laquelle ces données sont envoyées (attribut `action`)\n",
    "- la balise form inclut toujours un bouton via une balise `<button type=\"submit\">Envoyer</button>`.\n",
    "- on donnera toujours un `name` aux autres inputs\n",
    "- on appréciera pour les champs de texte l'utilisation de l'attribut `placeholder` qui permet d'afficher une légende dans un champ\n",
    "\n",
    "### Rappel : les types de champs textes\n",
    "\n",
    "Depuis HTML5, les `<input type=\"text\" />` peuvent être spécifiés plus finement :\n",
    "\n",
    "- color\n",
    "- date\n",
    "- datetime-local\n",
    "- email\n",
    "- month\n",
    "- number\n",
    "- range\n",
    "- search\n",
    "- tel\n",
    "- time\n",
    "- url\n",
    "- week\n",
    "\n",
    "Pour plus de détails, nous vous recommandons la lecture de la page suivante : https://www.alsacreations.com/tuto/lire/1372-formulaires-html5-nouveaux-types-champs-input.html\n",
    "\n",
    "### POST ou GET ?\n",
    "\n",
    "Prenons un formulaire avec un champ `recherche`.\n",
    "\n",
    "L'utilisation des méthodes POST ou GET a un impact visible sur les pages. En effet, **la méthode GET ajoute les informations du formulaire dans la barre URL**. Ainsi, l'utilisation d'un formulaire GET est fortement recommandée dans le cadre de formulaire de recherche. Il permettra de partager les résultats de recherche de manière simple !\n",
    "\n",
    "Au contraire, **GET est à proscrire de tout formulaire à données sensibles**, on y préférera POST. Cela évitera d'avoir des adresses mails, ou pire, des mots de passe dans les adresses visitées. Il est en effet très simple de récupérer ce genre d'informations par des outils malicieux."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Un formulaire, des formulaires ?\n",
    "\n",
    "Dans le cadre d'un site tel que le nôtre, on peut imaginer assez facilement :\n",
    "\n",
    "- une recherche rapide dans la barre de navigation en haut de la page\n",
    "- un grand champ de recherche sur la page d'accueil\n",
    "- une recherche à facettes\n",
    "\n",
    "Dans un premier temps, nous allons nous concentrer sur les deux options simples.\n",
    "\n",
    "### Dans la barre de recherche avec bootstrap\n",
    "\n",
    "On utilisera le composant de recherche en barre de navigation de bootstrap pour réaliser un outil graphiquement acceptable. La [documentation](http://getbootstrap.com/docs/4.0/components/navbar/#forms) nous donne l'extrait suivant : \n",
    "\n",
    "```html\n",
    "<nav class=\"navbar navbar-light bg-light justify-content-between\">\n",
    "  <a class=\"navbar-brand\">Navbar</a>\n",
    "  <form class=\"form-inline\">\n",
    "    <input class=\"form-control mr-sm-2\" type=\"search\" placeholder=\"Search\" aria-label=\"Search\">\n",
    "    <button class=\"btn btn-outline-success my-2 my-sm-0\" type=\"submit\">Search</button>\n",
    "  </form>\n",
    "</nav>\n",
    "```\n",
    "\n",
    "On le modifiera afin de pouvoir réaliser notre propre formulaire :\n",
    "\n",
    "#### Extrait du template container.html\n",
    "\n",
    "```html\n",
    "<nav class=\"navbar navbar-expand-md navbar-dark bg-dark justify-content-between\">\n",
    "    <a class=\"navbar-brand\" href=\"{{ url_for('accueil') }}\">Gazetteer</a>\n",
    "    <form class=\"form-inline\">\n",
    "      <input class=\"form-control\" type=\"search\" name=\"keyword\" placeholder=\"Recherche rapide\" aria-label=\"Recherche\">\n",
    "      <button class=\"btn btn-outline-info\" type=\"submit\">Rechercher</button>\n",
    "    </form>\n",
    "</nav>\n",
    "```\n",
    "\n",
    "### Le HTML ok mais la récupération de l'information ?\n",
    "\n",
    "Flask propose de récupérer les informations de formulaire via la variable `flask.request` (Documentation [simple](http://flask.pocoo.org/docs/0.12/quickstart/#accessing-request-data) / [complexe](http://flask.pocoo.org/docs/0.12/api/#incoming-request-data)). On commencera donc à importer cette variable :\n",
    "\n",
    "```python\n",
    "from flask import Flask, request\n",
    "```\n",
    "\n",
    "Cette variable possède entre autres un attribut `args` qui fonctionne comme un dictionnaire et qui récupère les valeurs disponibles dans l'URL de telle sorte que, pour l'URL `http://localhost/une_page?i=0&recherche=quelque%20chose` on aura :\n",
    "\n",
    "```python\n",
    "request.args == {\n",
    "    \"une_page\": \"0\",\n",
    "    \"recherche\": \"quelque chose\" # %20 remplace un espace dans les URLs\n",
    "}\n",
    ">>> True\n",
    "```\n",
    "*Au sujet des `%` dans les barres URL, voir https://en.wikipedia.org/wiki/Percent-encoding*\n",
    "\n",
    "On va donc simplement créer une nouvelle route qui récupèrera cette information !\n",
    "\n",
    "#### Extrait de `routes.py`\n",
    "```python\n",
    "@app.route(\"/recherche\")\n",
    "def recherche():\n",
    "    # On préfèrera l'utilisation de .get() ici\n",
    "    #   qui nous permet d'éviter un if long (if \"clef\" in dictionnaire and dictonnaire[\"clef\"])\n",
    "    motclef = request.args.get(\"keyword\", None)\n",
    "    # On crée une liste vide de résultat (qui restera vide par défaut\n",
    "    #   si on n'a pas de mot clé)\n",
    "    resultats = []\n",
    "    # On fait de même pour le titre de la page\n",
    "    titre = \"Recherche\"\n",
    "    if motclef:\n",
    "        resultats = Place.query.filter(\n",
    "            Place.place_nom.like(\"%{}%\".format(motclef))\n",
    "        ).all()\n",
    "        titre = \"Résultat pour la recherche `\" + motclef + \"`\"\n",
    "    return render_template(\"pages/recherche.html\", resultats=resultats, titre=titre)\n",
    "```\n",
    "\n",
    "#### Faire une requête `LIKE`\n",
    "\n",
    "Pour construire une requête LIKE avec SQL Alchemy:\n",
    "\n",
    "- On construit une requête à filtre `Place.query.filter()`\n",
    "- Dans le filtre, on ajoute la propriété de champ (ici, `Place.place_nom`)\n",
    "- On fait suivre ce champ de la méthode `.like()` avec le contenu de la recherche \n",
    "    - Ici les jokers `%` entourent la valeur de mot clef\n",
    "- On récupère l'ensemble des résultats via `.all()`\n",
    "\n",
    "#### Nouveau template : `templates/pages/recherche.html`\n",
    "\n",
    "```html\n",
    "{% extends \"conteneur.html\" %}\n",
    "\n",
    "{% block titre %}| {{titre}}{%endblock%}\n",
    "\n",
    "{% block corps %}\n",
    "<h1>{{titre}}</h1>\n",
    "    {% if resultats %}\n",
    "    <p>Il y a {{resultats|length}} lieux qui répondent à votre requête :</p>\n",
    "        <ul>\n",
    "            {% for lieu in resultats %}\n",
    "                <li><a href=\"{{url_for('lieu', place_id=lieu.place_id)}}\">{{lieu.place_nom}}</a></li>\n",
    "            {% endfor %}\n",
    "        </ul>\n",
    "    {% endif %}\n",
    "{% endblock %}\n",
    "```\n",
    "\n",
    "#### `templates/container.html`\n",
    "\n",
    "On corrige afin de metre l'action au formulaire :\n",
    "\n",
    "```html\n",
    "  <nav class=\"navbar navbar-expand-md navbar-dark bg-dark justify-content-between\">\n",
    "    <a class=\"navbar-brand\" href=\"{{ url_for('accueil') }}\">Gazetteer</a>\n",
    "    <form class=\"form-inline\" action=\"{{url_for(\"recherche\")}}\" method=\"GET\">\n",
    "      <input class=\"form-control\" name=\"keyword\" type=\"search\" placeholder=\"Recherche rapide\" aria-label=\"Recherche\">\n",
    "      <button class=\"btn btn-outline-info\" type=\"submit\">Rechercher</button>\n",
    "    </form>\n",
    "  </nav>\n",
    "```\n",
    "\n",
    "#### Pour lancer l'exemple en terminal\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple13\n",
    "python run.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Multiplier les formulaires\n",
    "\n",
    "À partir du moment où la page de réception du formulaire est déjà disponible, on peut multiplier ce formulaire. Qu'importe le nombre d'entrées, il suffit d'une seule sortie !\n",
    "\n",
    "Pour ce faire, on a créé un nouveau template `partials/recherche.html` que l'on inclura sur la page d'accueil et la page de recherche.\n",
    "\n",
    "Regardez les templates de l'exemple14 puis lancez l'exemple.\n",
    "\n",
    "#### Pour lancer l'exemple en terminal\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple14\n",
    "python run.py\n",
    "```\n",
    "\n",
    "## Aller plus loin\n",
    "\n",
    "Il existe une manière de bien sécuriser nos formulaires et d'en réutiliser facilement. Je vous conseille la lecture de [The Flask Mega-Tutorial Part III: Web Forms](https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-iii-web-forms)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}