====== Le module html ======

Défini dans ''%%html.py%%'', c'est un module permettant de regrouper les fonctions concernant les pages html, notamment les erreurs et les problèmes d'entêtes. Définit la classe ''%%Html%%''.

Quand on parle de fichiers html ci-dessous, on suppose qu'ils se trouvent dans ''%%FileManager.BASE_URL%%''. La classe nécessitera d'ailleurs l'utilisation de la classe ''%%FileManager%%''.

Vous pouvez tester le bon fonctionnement avec le module de test : {{ .:html.test.py |}}.

===== Initialisation =====

Un objet ''%%Html%%'' devra représenter une page. Lors de la création de l'objet on pourra préciser le contenu de plusieurs façons :

  * donner un code d'erreur, pour générer la page d'erreur automatiquement,
  * donner le contenu de la page sous forme d'un texte,
  * donner un nom de fichier html dont on charge le contenu.

Mais comment indiquer ce choix ? Python propose une syntaxe élégante :

<code python>
# on souhaite pouvoir appeler une fonction fct avec diverses options :
fct(error_code=200)
fct(content='pwet')
fct(filename='exemple.html')

# voici comment définir la fonction
def fct(**options):
    # options contient un dictionnaire avec les options
    # par ex, dans le premier cas, options = {"error_code":200}
    # dans le 2e cas, options = {"content":"pwet"}
    # dans le 3e cas, options = {"filename":"exemple.html"}
    # il suffit donc de tester ce que contient options pour savoir quoi faire !
</code>

Cette explication vous aidera pour la méthode ''%%__init__%%''

===== Interface de la classe Html =====

  * attribut ''%%error_code = 200%%'', 200 étant la valeur par défaut et qui précise la valeur du code d'erreur en cours -- //le code d'erreur est utilisé pour les pages d'erreurs comme 404//
  * attribut ''%%content = ""%%'', par défaut vide, qui représente le contenu texte de la page
  * méthode ''%%__init__(self, **options)__%%''. Comme expliqué précédemment, ''%%**options%%'' permet de recevoir des arguments variables. Dans la méthode, ''%%options%%'' sera un dictionnaire qui devra contenir l'une des options : ''%%filename%%'', ''%%error_code%%'' ou ''%%content%%''.
    * En l'absence de ces 3  options, on agira par défaut comme si c'était ''%%error_code = 501%%''
    * si ''%%filename%%'', tentative de chargement du fichier en mode texte, dans la partie publique du site. Si succès, le contenu est placé dans l'attribut ''%%content%%'' de l'objet. Sinon, on bascule sur ''%%error_code = 404%%'' (not found)
    * si ''%%error_code%%'', avec ''%%error_code%%'' une valeur acceptée, on affecte l'attribut ''%%error_code%%'' et on génère la page d'erreur correspondante dans ''%%content%%'' (voir les méthodes suivantes). Si ''%%error_code%%'' n'est pas valable, on prend par défaut ''%%error_code = 501%%''
    * si ''%%content%%'', la valeur de l'attribut ''%%content%%'' de l'objet est actualisée.
  * méthode ''%%entete(self) -> str%%'' renvoie l'entête d'une réponse html selon le code html. Je détaille plus bas les entêtes.
  * méthode ''%%load_default_error_page(self)%%'' qui selon ''%%error_code%%''  modifie l'attribut ''%%content%%'' pour un code html par défaut. Voir plus bas pour les messages par défaut. On n'acceptera que les erreurs 404 et 501.
  * méthode ''%%load_error_page(self)%%'' qui selon ''%%error_code%%'' teste l'existence d'une page d'erreur, par exemple un fichier ''%%404.html%%''. S'il existe, charge cette page dans l'attribut ''%%content%%'', sinon charge la page par défaut (méthode précédente).
  * méthode ''%%is_html(self, filename:str) -> bool%%'' qui renvoie ''%%True%%'' si le nom est bien de la forme ''%%*.html%%''
  * méthode ''%%encode(self)%%'' qui renvoie l'entête correspondant à ''%%error_code%%'' suivi du contenu ''%%content%%'' le tout encodé en ''%%utf8%%''.

===== Entêtes =====

Voici par exemple l'entête pour un chargement avec succès (code 200)

<code lang-none>
HTTP/1.1 200 OK
host: le site local
Content-Type: text/html
</code>

Mais il y a des caractères cachés extrêmement importants. À chaque saut de ligne ''%%\r\n%%'' et deux fois ''%%\r\n%%'' à la fin. On pourra donc l'écrire :
<code python>
"HTTP/1.1 200 OK\r\nhost: le site local\r\nContent-Type: text/html\r\n\r\n"
</code>

Pour une erreur 404
<code lang-none>
HTTP/1.1 404 Not Found\r\n
host: le site local\r\n
Content-Type: text/html\r\n\r\n
</code>

ou encore pour une erreur 501
<code lang-none>
HTTP/1.1 501 Not Implemented
host: le site local
Content-Type: text/html\n
</code>

Ces trois codes suffisent pour l'instant. Au besoin vous trouverez les autres facilement sur [[https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP|internet]].

===== Pages d'erreur par défaut =====

Pour une erreur 404 :

<code html>
<!DOCTYPE html PUBLIC><html><head><meta charset="UTF-8"></head><body>Erreur 404 : Fichier n'existe pas.</body></html>
</code>

Pour une erreur 501 :

<code html>
<!DOCTYPE html PUBLIC><html><head><meta charset="UTF-8"></head><body>Erreur 501 : Erreur sur le serveur.</body></html>
</code>