17_plantillas_de_django.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![imagenes/pythonista.png](imagenes/pythonista.png)](https://pythonista.io)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Plantillas de *Django*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**ADVERTENCIA:**  \n",
    "\n",
    "Para poder realizar exitosamente los ejercicios de esta notebook, es necesario haber seguido al pie de la letra y en orden sucesivo las instrucciones de todas las notebooks previas."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plantillas (*templates*).\n",
    "\n",
    "*Django* es un framework diseñado primordialmente para desplegar páginas web de forma dinámica mediante el patrón *MVT*, el cual además de los modelos y las funciones de vista, aprovecha el uso de plantillas para lograr tal  finalidad.\n",
    "\n",
    "Una plantilla es un documento el cual contiene texto y código que permite a *Django* crear un texto nuevo a partir del original combinándolo con los datos que se le ingresan mendiante un *contexto*.\n",
    "\n",
    "**Ejemplo:**\n",
    "\n",
    "El archivo ```src/17/base.html``` contiene el siguiente texto que corresponde  una plantilla básicas que combina código en HTML y etiquetas basadas en el *lenguaje de plantillas de Django*.\n",
    "\n",
    "``` HTML\n",
    "<!DOCTYPE html>\n",
    "<html>\n",
    "    <header>\n",
    "        <meta charset=\"UTF-8\">\n",
    "        <title>{{ titulo }}</title>\n",
    "    </header>\n",
    "    <body>\n",
    "        {% block cuerpo %}\n",
    "        <h1>¡Hola, mundo!</h1>\n",
    "        {% endblock %}\n",
    "    </body>\n",
    "</html>\n",
    "```\n",
    "\n",
    "**Nota:**\n",
    "Aún cuando lo más común es usar HTML, las plantillas de *Django* pueden utilizarse para crear documentos en distintos formatos como *XML*, *YAML*, *JSON*, etc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## El lenguaje de plantillas de *Django* (*DTL*).\n",
    "\n",
    "El lenguaje de plantillas de *Django* (*DTL* por sus siglas en inglés) permiten modificar a un  documento que contiene código basado en dicho lenguaje, ejecutándolo junto con datos externos que son asignados como si fueran variables globales.\n",
    "\n",
    "El *DTL* reconoce los tipos básicos de *Python*.\n",
    "\n",
    "### Tipos de etiquetas.\n",
    "\n",
    "El *DTL* utiliza etiquetas, la cuales se conforman por código encerrado entre llaves ```{``` y ```}```.\n",
    "\n",
    "#### Etiquetas para expresiones.\n",
    "\n",
    "```\n",
    "{{ <expresión> }}\n",
    "```\n",
    "\n",
    "#### Etiquetas para declaraciones.\n",
    "\n",
    "Las declaraciones pueden:\n",
    "\n",
    "* Ejecutarse de forma similar a una expresión.\n",
    "\n",
    "```\n",
    "{% <declaración> %}\n",
    "```\n",
    "\n",
    "* Delimitar un bloque de texto y código.\n",
    "\n",
    "```\n",
    "{% <declaración> %}\n",
    "...\n",
    "...\n",
    "...\n",
    "{% end<declaración> %}\n",
    "```\n",
    "\n",
    "A partir de estas etiquetas, es posible generar código que creará contenidos a utilizando el texto del documento original.\n",
    "\n",
    "**Nota:**\n",
    "En este capítulo se explorarán sólo las etiquetas más representativas, pero La referencia a las etiqueta de *DTL* pueden ser consultadas en https://docs.djangoproject.com/en/3.2/ref/templates/builtins/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## El paquete ```django.template```.\n",
    "\n",
    "Este paquete cuenta con una biblioteca de herramientas que permite crear contenidos a partir de plantillas con código escrito en *DTL*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### La clase  ```Django.template.Template```.\n",
    "\n",
    "Esta es la clase primordial para el manejo de plantillas y permite crear un objeto capaz de ejecutar el código basado en *DTL* a partir de una cadena de caracteres, la cual corresponde al contenido de una plantilla.\n",
    "\n",
    "```\n",
    "Template(<objeto str>)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### La clase  ```django.template.Context```.\n",
    "\n",
    "Esta clase permite crear definir el diccionario de contexto que consumirá la plantilla al ser procesada.\n",
    "\n",
    "```\n",
    "Context(<objeto tipo dict>)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sustitución de datos de contexto en una plantilla."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### El método ```Template.render```.\n",
    "\n",
    "Este método permite sustituir los elementos dentro de una plantilla con los objetos ingresados en el contexto.\n",
    "\n",
    "```\n",
    "<plantilla>.render(context=<contexto>)\n",
    "```\n",
    "\n",
    "Donde:\n",
    "\n",
    "* ```plantilla```es una instancia de ```django.template.Template.\n",
    "* ```contexto```es una instancia de ```django.template.Context."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**\n",
    "\n",
    "En un shell de Django ejecutar lo siguiente:\n",
    "\n",
    "``` python\n",
    "from django.template import Template, Context\n",
    "saludo = '¡Hola, {{ nombre }}'\n",
    "plantilla = Template(saludo)\n",
    "contexto = Context({'nombre': 'mundo'})\n",
    "plantilla.render(context=contexto)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuración de las plantillas en un proyecto.\n",
    "\n",
    "El archivo ```tutorial/tutorial/settings.py``` contiene una sección que define la configuración de las plantillas de forma similar a lo siguiente:\n",
    "\n",
    "``` python\n",
    "TEMPLATES = [{'BACKEND': 'django.template.backends.django.DjangoTemplates',\n",
    "  'DIRS': [],\n",
    "  'APP_DIRS': True,\n",
    "  'OPTIONS': {'context_processors': ['django.template.context_processors.debug',\n",
    "    'django.template.context_processors.request',\n",
    "    'django.contrib.auth.context_processors.auth',\n",
    "    'django.contrib.messages.context_processors.messages']}}]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configuración del directorio de plantillas.\n",
    "\n",
    "La lista correspondiente al nombre ```DIRS``` contiene la lista de directorios a los que puede consultar Django en busca de una plantilla."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**\n",
    "\n",
    "El archivo ```src/17/settings.py``` contiene la siguiente configuración de directorios:\n",
    "\n",
    "``` python\n",
    "'DIRS': [BASE_DIR + '/templates/'],\n",
    "```\n",
    "\n",
    "En el que ```BASE_DIR``` corresponde al directorio base del proyecto de *Django*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda sustituirá al archivo ```tutorial/tutorial/settings.py``` con el archivo ```src/17/settings.py```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para las plataformas basadas en GNU/linux y MacOS X."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cp src/17/settings.py tutorial/tutorial/settings.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para la plataforma Windows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!copy src\\17\\settings.py tutorial\\tutorial\\settings.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pycat tutorial/tutorial/settings.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La nueva configuración puede ser vista de la siguiente manera, siendo el valor de ```BASE_DIR``` la ruta donde se encuentra el directorio ```tutorial```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from tutorial.tutorial import settings"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "settings.BASE_DIR"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "settings.TEMPLATES[0]['DIRS']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### El directorio ```templates```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para las plataformas basadas en Linux y MacOS X."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "!mkdir tutorial/templates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para la plataforma Windows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!mkdir tutorial\\templates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## El módulo ```django.template.loader``` .\n",
    "\n",
    "Este módulo permite cargar documentos que contiene una plantillas e incluso procesarlos.\n",
    "\n",
    "### La función ```django.template.loader.get_template()```. \n",
    "\n",
    "Esta función permite cargar una plantilla a partir de un archivo que se encuentre dentro de las rutas predefinidas en la configuración de *Django*.\n",
    "\n",
    "``` python \n",
    "get_template('<archivo>')\n",
    "\n",
    "```\n",
    "\n",
    "### La función ```django.template.loader.select_template()```. \n",
    "\n",
    "La cual permite cargar la primera plantilla dentro de una ruta predefinida que encuentra dentro de una lista.\n",
    "\n",
    "``` python \n",
    "select_template(['<archivo 1 >', '<archivo 2 >'... '<archivo n >'] )\n",
    "\n",
    "```\n",
    "\n",
    "### La función ```django.template.loader.render_to_string()```. \n",
    "\n",
    "La cual permite cargar una plantilla dentro de una ruta predefinida y procesarla utilizando un objeto tipo *dict* como contexto.\n",
    "\n",
    "``` python \n",
    "render_to_string('<archivo>', <contexto>)\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**\n",
    "\n",
    "El archivo ```src/17/ejemplo.html``` contiene el siguiente texto, el cual mezcla código *HTML* con código *DTL*:\n",
    "\n",
    "```html\n",
    "<!DOCTYPE html>\n",
    "<html>\n",
    "    <header>\n",
    "        <meta charset=\"UTF-8\">\n",
    "        <title>{{ titulo }}</title>\n",
    "    </header>\n",
    "    <body>\n",
    "        {% block cuerpo %}\n",
    "        <h1>¡Hola, {{ nombre }}!</h1>\n",
    "        {% endblock %}\n",
    "    </body>\n",
    "</html>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda copiará el archivo ```src/17/ejemplo.html``` al directorio ```tutorial/templates```, el cual fue definido en ```settings.py``` como un directorio de plantillas."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para las plataformas basadas en GNU/Linux y MacOS X."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cp src/17/ejemplo.html tutorial/templates/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para la plataforma basada en Windows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!copy src\\17\\ejemplo.html tutorial\\templates\\"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "%pycat tutorial/templates/ejemplo.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* En un shell de *Django* ejecute el siguiente código:\n",
    "\n",
    "``` python\n",
    "from django.template.loader import render_to_string\n",
    "contexto = {'titulo':'Página de prueba', 'nombre':'extraño'}\n",
    "print(render_to_string(\"ejemplo.html\", contexto))\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* El resultado será:\n",
    "``` html\n",
    "<!DOCTYPE html>\n",
    "<html>\n",
    "    <header>\n",
    "        <meta charset=\"UTF-8\">\n",
    "        <title>Página de prueba</title>\n",
    "    </header>\n",
    "    <body>\n",
    "\n",
    "        <h1>¡Hola, extraño!</h1>\n",
    "\n",
    "    </body>\n",
    "</html>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Publicación de una plantilla como resultado de una función de vista."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "La función ```django.shortcuts.render``` permite que una función de vista envíe a un cliente un documento creado a partir de una plantilla y un contexto específico:\n",
    "\n",
    "``` python\n",
    "render(request, <plantilla>, context=<contexto>)\n",
    "```\n",
    "Donde:\n",
    "\n",
    "* ```plantilla``` es el nombre del archivo que contiene a la plantilla y que debe de estar localizado en algún directorio configurado para acceder a estas.\n",
    "* ```context``` es un objeto de tipo *dict* que contiene el contexto.\n",
    "* ```content-type``` es un parámetro opcional que indica el tipo de contenido del que se trata.\n",
    "* ```status``` corresponde al mensaje de estado que se eviará junto con el contenido. El valor por defecto es ```200```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "El archivo ```src/17/views.py``` contiene, entre otras, a la función ```saluda()```, la cual corresponde al siguiente código:\n",
    "\n",
    "``` python \n",
    "def saluda(request, nombre):\n",
    "    contexto = {\"titulo\":\"Prueba de plantilla\", \"nombre\": nombre}\n",
    "    return render(request, 'ejemplo.html', contexto)\n",
    "```\n",
    "\n",
    "Esta función realizará lo siguiente: \n",
    "* Obtendrá una cadena de caracteres correspondiente al segmento final de la URL ```main/claves/``` siempre que sea alfanumérico.\n",
    "* Cargará al archivo ```tutorial/templates/ejemplo.html``` como una plantilla.\n",
    "* Procesará la plantilla con el contexto dado.\n",
    "* Enviará el contenido a un cliente."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda sustiruirá al archivo ```tutorial/main/views.py``` con el archivo ```src/17/views.py```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para las plataformas basadas en GNU/Linux y MacOS X."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cp src/17/views.py tutorial/main/views.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Para la plataforma basada en Windows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!copy src\\17\\views.py tutorial\\main\\views.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pycat tutorial/main/views.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Inicie el servidor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%cd tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**ADVERTENCIAS:** \n",
    "\n",
    "* Al ejecutar la siguiente celda el servidor se inciará desde la notebook, por lo que para ejecutar cualquier otra celda es necesario interrumpir la ejecución del kernel.\n",
    "\n",
    "* Asegúrese que no haya otro servicio escuchando en el puerto *8000*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python manage.py runserver 0.0.0.0:8000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cualquier URL que al final de ```main/claves/``` contenga caracteres alfanuméricos, regresará un documento HTML generado mediante la función saluda.\n",
    "\n",
    "* El elemento ```<title>``` del código *HTML* contiene el texto ```Prueba de plantilla```. \n",
    "* El segmento de la URL capturado se deplegará en un mensaje de saludo.\n",
    "\n",
    "http:https://localhost:8000/main/claves/Juan"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: center\"><a rel=\"license\" href=\"http:https://creativecommons.org/licenses/by/4.0/\"><img alt=\"Licencia Creative Commons\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by/4.0/80x15.png\" /></a><br />Esta obra está bajo una <a rel=\"license\" href=\"http:https://creativecommons.org/licenses/by/4.0/\">Licencia Creative Commons Atribución 4.0 Internacional</a>.</p>\n",
    "<p style=\"text-align: center\">&copy; José Luis Chiquete Valdivieso. 2020.</p>"
   ]
  }
 ],
 "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.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}