# 📁 Directorio Telefónico con Flask + WTForms

Este es el proyecto final del tutorial **"Formularios en Flask: WTForms, validación y estilos con Bootstrap"** publicado en [Pythones.net](https://pythones.net).

Aplicación web de directorio telefónico construida con Flask que implementa un CRUD completo sobre una base de datos JSON, siguiendo el patrón MVC (Modelo-Vista-Controlador), con plantillas Jinja2, Bootstrap 5 y un formulario de soporte con WTForms y validación.

---

## 🔗 Enlace al tutorial completo

👉 [Formularios en Flask: WTForms, validación y estilos con Bootstrap](https://pythones.net/formularios-en-flask-wtforms-bootstrap/)
_(Abre el post para seguir el paso a paso y entender cada parte del código.)_

---

## 🚀 Requisitos previos

- Python 3.8 o superior instalado.
- `pip` (gestor de paquetes de Python).
- Conexión a internet para descargar las dependencias.

---

## 📦 Instalación y configuración

Sigue estos pasos para poner en marcha la aplicación en tu equipo.

### 1. Clonar o descomprimir el proyecto

Si has descargado el ZIP, descomprímelo en una carpeta de tu elección.

```bash
unzip proyecto-flask-jinja2.zip
cd proyecto-flask-jinja2
```

### 2. Crear y activar un entorno virtual

**En Linux / Mac:**

```bash
python3 -m venv venv
source venv/bin/activate
```

**En Windows (CMD o PowerShell):**

```bash
python -m venv venv
venv\Scripts\activate
```

💡 El entorno virtual aísla las dependencias de este proyecto para evitar conflictos con otros proyectos.

### 3. Instalar las dependencias

Con el entorno virtual activado, ejecuta:

```bash
pip install flask flask-wtf email-validator
```

Esto instalará:

- **Flask** – El microframework web.
- **Flask-WTF** – Integración de WTForms con Flask (incluye protección CSRF).
- **email-validator** – Necesario para el validador `Email()` de WTForms.

### 4. Ejecutar la aplicación

Una vez instaladas las dependencias, inicia el servidor:

```bash
python controlador.py
```

Verás un mensaje similar a:

```
 * Running on http://127.0.0.1:5000
 * Debug mode: on
```

Abre tu navegador y visita: **http://127.0.0.1:5000**

¡Ya estás usando el directorio telefónico!

---

## 🗂️ Estructura del proyecto

```
proyecto-flask-jinja2/
├── controlador.py          # Controlador (rutas y lógica de negocio)
├── models.py                # Modelo (clase Persona y CRUD sobre JSON)
├── forms.py                 # Formularios con WTForms
├── DB/
│   └── base_de_datos.json   # Base de datos en JSON (contactos)
├── templates/                # Plantillas HTML con Jinja2
│   ├── base.html
│   ├── header.html
│   ├── footer.html
│   ├── index.html
│   ├── editar_contacto.html
│   ├── agregar_contacto.html
│   ├── galeria.html
│   └── soporte.html
└── static/                   # Archivos estáticos
    ├── css/
    │   └── style.css
    ├── img/                  # Imágenes (logos, etc.)
    ├── video/                # Videos
    └── js/                   # (opcional) scripts JS
```

---

## 🧪 ¿Qué hace la aplicación?

- 📇 Lista contactos en la página de inicio.
- 👁️ Ver detalles de un contacto individual.
- ✏️ Editar los datos de un contacto.
- ➕ Agregar nuevos contactos.
- 🗑️ Eliminar contactos.
- 🖼️ Galería de imágenes con cards de Bootstrap.
- 📩 Formulario de soporte con validación y protección CSRF (aún sin envío de correo, listo para conectar con Flask-Mail en el próximo post).

---

## ❓ Preguntas frecuentes (FAQ)

**¿Qué hago si veo un error de `ModuleNotFoundError`?**
Asegúrate de que el entorno virtual esté activado y de haber ejecutado `pip install flask flask-wtf email-validator`. Si usas otro sistema operativo, verifica que el comando `python` sea `python3`.

**¿Por qué la tabla se ve sin estilos?**
Comprueba que el servidor esté corriendo sin errores. Si la página devuelve un error 500 (por ejemplo, por una ruta mal escrita), Bootstrap no se cargará. Revisa la terminal para ver el mensaje de error exacto. La mayoría de los problemas se deben a errores de sintaxis en `controlador.py`.

**¿Cómo añado más contactos?**
Puedes hacerlo directamente desde la interfaz web usando el botón "Agregar contacto". También puedes editar el archivo `DB/base_de_datos.json` manualmente (con cuidado de mantener la estructura JSON).

**¿Cómo cambio la clave secreta (`SECRET_KEY`)?**
Edita la línea `app.config['SECRET_KEY']` en `controlador.py` y pon una cadena larga y aleatoria. En producción, usa variables de entorno para no exponerla en el código.

**¿Qué pasa si el formulario de soporte no valida?**
Comprueba que en el template `soporte.html` esté incluido `{{ form.hidden_tag() }}`. Sin el token CSRF, el formulario no se validará.

---

## 📚 Recursos adicionales

- [Documentación oficial de Flask](https://flask.palletsprojects.com/)
- [Documentación de WTForms](https://wtforms.readthedocs.io/)
- [Flask-WTF en Read the Docs](https://flask-wtf.readthedocs.io/)
- [Bootstrap 5](https://getbootstrap.com/)

---

## 📝 Créditos

Este proyecto fue creado por **Mariano Laca** como parte de la serie de tutoriales de [Pythones.net](https://pythones.net).

## 📄 Licencia

Este proyecto es de uso educativo. Puedes usarlo, modificarlo y compartirlo libremente siempre que se mencione la fuente original (Pythones.net).

¡Disfruta aprendiendo Flask! 🐍🚀
