# Extensió WordPress de Gestió Monedes

## Ubicació

- Carpeta del plugin: `wordpress-plugin/gestio-monedes-wp`
- ZIP instal·lable: `wordpress-plugin/gestio-monedes-wp.zip`

## Objectiu

Aquest plugin converteix el projecte `gestio_monedes` en una extensió reutilitzable per a WordPress.
Permet connectar WordPress amb el catàleg de monedes existent i treballar amb tres fonts de dades:
MariaDB, CSV i XML.

## Requisits que compleix

- És capaç de llegir la informació des de MariaDB.
- És capaç de llegir la informació des d'un arxiu CSV.
- És capaç de llegir la informació des d'un arxiu XML.
- És capaç d'introduir noves dades a MariaDB.
- És capaç d'introduir noves dades a un arxiu CSV.
- És capaç d'introduir noves dades a un arxiu XML.
- És capaç de mostrar les imatges de les monedes.
- És capaç de filtrar les dades per criteris de cerca.

## Funcionalitats principals

- pàgina d'administració pròpia dins de WordPress
- diagnòstic visual de les fonts MariaDB, CSV i XML
- configuració de connexió MariaDB
- configuració de rutes de fitxer CSV i XML
- vista prèvia enriquida de la font activa amb targetes i resum contextual
- formulari d'inserció de noves monedes
- resolució d'imatges per URL absoluta, ruta relativa o placeholder
- shortcode de frontend: `[gestio_monedes_llistat]`
- filtres per nom, país, any d'emissió i rang de valor
- filtre específic per mostrar només monedes amb imatge
- ordenació per nom, valor, any o darrera actualització
- límit visible configurable al frontend
- selector de font de dades al frontend quan el shortcode no fixa una font concreta

## Instal·lació a WordPress

### Opció 1. Des de carpeta local

1. Copia `gestio-monedes-wp` dins de `wp-content/plugins/`.
2. Entra a `Plugins` al panell d'administració de WordPress.
3. Activa `Gestio Monedes WP`.

### Opció 2. Des de ZIP

1. Ves a `Plugins > Add New Plugin > Upload Plugin`.
2. Puja `gestio-monedes-wp.zip`.
3. Instal·la'l i activa'l.

## Configuració inicial

1. Entra a `Gestió Monedes WP` al panell d'administració.
2. Selecciona la font de dades per defecte.
3. Revisa les credencials MariaDB si vols llegir la base de dades del projecte.
4. Defineix la ruta del CSV o XML si vols treballar amb fitxers.
5. Desa la configuració.

Per a aquest entorn, el plugin ja ve preconfigurat per llegir la base de dades del projecte
`gestio_monedes` i per resoldre les imatges des de `https://fmehmood.cat/gestio_monedes/uploads/`.

## Ús del shortcode

Shortcode bàsic:

```text
[gestio_monedes_llistat]
```

Shortcode indicant la font:

```text
[gestio_monedes_llistat source="mariadb" title="Catàleg de monedes"]
```

Valors admesos a `source`:

- `mariadb`
- `csv`
- `xml`

## Criteris de filtre disponibles

El formulari frontend permet filtrar per:

- font de dades
- nom
- país
- any d'emissió
- valor mínim
- valor màxim
- només monedes amb imatge
- ordenació
- límit visible

## Inserció de noves dades

Des del panell del plugin es pot inserir una nova moneda indicant:

- destinació: `MariaDB`, `CSV` o `XML`
- nom
- país
- valor
- any d'emissió
- descripció
- imatge

## Gestió d'imatges

El camp `imatge` admet:

- una URL absoluta: `https://...`
- una ruta que comenci per `/`
- un nom de fitxer simple: `moneda.jpg`

Si s'indica només el nom del fitxer, el plugin el resol automàticament contra la `URL base d'imatges`
configurada a l'administració.

## Fitxers principals del plugin

- `gestio-monedes-wp.php`: bootstrap del plugin
- `includes/class-gmwp-plugin.php`: panell d'administració, configuració i shortcode
- `includes/class-gmwp-source-manager.php`: lectura, filtres i inserció a MariaDB/CSV/XML
- `assets/admin.css`: estils de l'administració
- `assets/front.css`: estils del catàleg frontend