rename views to mvc and add content to templatetags

source/docs.rst

@@ -9,13 +9,13 @@ On en a déjà parlé plus haut, il existe un standard en Python pour la défini
 Python étant un langage interprété fortement typé, il est plus que conseillé, au même titre que les tests unitaires, de documenter son code.
 Cela impose une certaine rigueur, mais améliore énormément la qualité (et la reprise) du code par une tierce personne. Cela implique aussi de **tout** documenter: les modules, les paquets, les classes, les fonctions, méthodes, ... Tout doit avoir un *docstring* associé :-).
 
-Plusieurs modules de documentation existent, mais nous allons nous concentrer sur Sphinx, qui semble être le plus complet et qui permet d'héberger directement sa documentation sur ReadTheDocs.org. Nous allons également faire en sorte que cette documentation soit compatible avec Django, puisque c'est le but de notre projet.
+Plusieurs modules de documentation existent, mais nous allons nous concentrer sur Sphinx, qui semble être le plus complet et qui permet d'héberger directement sa documentation sur `ReadTheDocs.org <https://readthedocs.org/>`_. Nous allons également faire en sorte que cette documentation soit compatible avec Django, puisque c'est le but de notre projet.
 
 ------
 Sphinx
 ------
 
-Commencez par installer Sphinx et ajoutez le dans le fichier `requirements/base.txt`. *A priori*, il n'est pas nécessaire de spécifier une version: Sphinx est un outil périphérique, qui ne dépendra pas des autres librairies. Une fois que ce sera fait, exécutez la commande ``sphinx-quickstart``, afin d'initier la documentation pour notre projet:
+Commencez par installer Sphinx et ajoutez le dans le fichier ``requirements/base.txt``. *A priori*, il n'est pas nécessaire de spécifier une version: Sphinx est un outil périphérique, qui ne dépendra pas des autres librairies. Une fois que ce sera fait, exécutez la commande ``sphinx-quickstart``, afin d'initier la documentation pour notre projet:
 
 .. code-block:: shell
 

source/mvc.rst

@@ -5,6 +5,6 @@ Contrôleurs
 Dans un *pattern* MVC classique, la traduction immédiate du **contrôleur** est une **vue**. Et comme on le verra par la suite, la **vue** est en fait le **template**.
 Les vues agrègent donc les informations à partir d'un des composants et les font transiter vers un autre. En d'autres mots, la vue sert de pont entre les données gérées par la base et l'interface utilisateur.
 
-.. include:: views/templates.rst
+.. include:: mvc/views.rst
-.. include:: views/views.rst
+.. include:: mvc/templates.rst
-.. include:: views/urls.rst
+.. include:: mvc/urls.rst

source/mvc/templates.rst

@@ -78,5 +78,53 @@ Django vient avec un ensemble de *tags*. On a vu la boucle ``for`` ci-dessus, ma
  * ``{% if ... %} ... {% elif ... %} ... {% else %} ... {% endif %}``: permet de vérifier une condition et de n'afficher le contenu du bloc que si la condition est vérifiée.
  * Opérateurs de comparaisons: ``<``, ``>``, ``==``, ``in``, ``not in``.
  * Regroupements avec le tag ``{% regroup ... by ... as ... %}``.
- * ``{% url %}``
+ * ``{% url %}`` pour construire facilement une URL
  * ...
+
+Non-builtins
+============
+
+En plus des quelques tags survolés ci-dessus, il est également possible de construire ses propres tags. La structure est un peu bizarre, car elle consiste à ajouter un paquet dans une de vos applications, à y définir un nouveau module et à y définir un ensemble de fonctions. Chacune de ces fonctions correspondra à un tag appelable depuis vos templates.
+
+Il existe trois types de tags *non-builtins*: 
+
+ 1. Les filtres - on peut les appeler grâce au *pipe* ``|`` directement après une valeur dans le template. 
+ 2. Les tags simples - ils peuvent prendre une valeur ou plusieurs en paramètre et retourne une nouvelle valeur. Pour les appeler, c'est *via* les tags ``{% nom_de_la_fonction param1 param2 ... %}``.
+ 3. Les tags d'inclusion: ils retournent un contexte (ie. un dictionnaire), qui est ensuite passé à un nouveau template. 
+
+Pour l'implémentation:
+
+ 1. On prend l'application ``wish`` et on y ajoute un répertoire ``templatetags``, ainsi qu'un fichier ``__init__.py``. 
+ 2. Dans ce nouveau paquet, on ajoute un nouveau module que l'on va appeler ``tools.py``
+ 3. Dans ce module, pour avoir un aperçu des possibilités, on va définir trois fonctions (une pour chaque type de tags possible).
+ 
+.. code-block:: shell
+
+    [Inclure un tree du dossier template tags]
+
+.. code-block:: python
+    
+    # wish/tools.py
+    
+    # coding=utf-8
+
+    from django import template
+
+    from wish.models import Wishlist
+
+    register = template.Library()
+
+    @register.filter(is_safe=True)
+    def add_xx(value):
+        return '%sxx' % value
+
+    @register.simple_tag
+    def current_time(format_string):
+        return datetime.datetime.now().strftime(format_string)
+
+    @register.inclusion_tag('wish/templatetags/wishlists_list.html')
+    def wishlists_list():
+        return { 'list': Wishlist.objects.all() }  
+    
+    
+Pour plus d'informations, la `documentation officielle est un bon début <https://docs.djangoproject.com/en/stable/howto/custom-template-tags/#writing-custom-template-tags>`_.

source/mvc/urls.rst

@@ -26,4 +26,21 @@ Le champ `urlpatterns` associe un ensemble d'adresses à des fonctions. Dans le
 Reverse
 =======
 
-Chaque
+En associant un nom ou un libellé à chaque URL, il est possible de récupérer sa *traduction*. Cela implique par contre de ne plus toucher à ce libellé par la suite...
+
+Dans le fichier ``urls.py``, on associe le libellé ``wishlists`` à l'URL ``r'^$`` (c'est-à-dire la racine du site):  
+
+.. code-block:: python
+
+    from wish.views import WishListList
+
+    urlpatterns = [
+        url(r'^admin/', include(admin.site.urls)),
+        url(r'^$', WishListList.as_view(), name='wishlists'),
+    ]
+
+De cette manière, dans nos templates, on peut à présent construire un lien vers la racine avec le tags suivant: 
+
+.. code-block:: html
+
+    <a href="{% url 'wishlists' %}">{{ yearvar }} Archive</a>

source/templates.rst

@@ -1,3 +0,0 @@
-=========
-Templates
-=========