carhop__plugins__PROD-DEV/plugins/dynamiques-thumbnail-focal-point/README.md

# Plugin Dynamiques Focal Point

Plugin WordPress pour ajouter un point focal personnalisable aux images mises en avant (thumbnails).

## Installation

1. Activer le plugin dans l'administration WordPress
2. Le plugin fonctionne automatiquement avec :
      - **L'éditeur Gutenberg** : un panneau React apparaît dans la sidebar
      - **L'éditeur classique (avec ACF)** : le focal point picker s'intègre directement dans la meta box "Image mise en avant"

## Caractéristiques techniques

- ✅ Utilise le composant officiel `FocalPointPicker` de WordPress
- ✅ Interface React pour une expérience utilisateur moderne
- ✅ **S'intègre directement dans la meta box native de thumbnail** (pas de meta box séparée !)
- ✅ Compatible avec tous les post types supportant les thumbnails
- ✅ Fonctionne avec ACF et l'éditeur classique
- ✅ Sauvegarde automatique dans les post meta

## Utilisation dans l'éditeur

### Avec l'éditeur Gutenberg

Après avoir défini une image mise en avant pour votre article/page :

1. Ouvrez le panneau "Point focal de la miniature" dans la sidebar
2. Cliquez sur l'image pour définir le point focal
3. Le point focal sera sauvegardé automatiquement

### Avec l'éditeur classique (ou avec ACF)

Après avoir défini une image mise en avant :

1. Allez dans la meta box **"Image mise en avant"** (celle qui est native à WordPress)
2. Le focal point picker apparaît automatiquement **en dessous de l'image**
3. Cliquez sur l'image pour définir le point focal (utilise le composant React `FocalPointPicker`)
4. Enregistrez votre article/page pour sauvegarder le point focal

**Avantages** :

- 🎯 Tout est au même endroit - pas besoin de chercher une autre meta box
- 🚀 Interface native et familière
- ⚡ Rechargement automatique si vous changez l'image mise en avant

## Utilisation dans le thème

### Récupérer les valeurs du focal point

```php
<?php
$focal_point = get_post_meta(get_the_ID(), 'thumbnail_focal_point', true);

if ($focal_point && is_array($focal_point)) {
    $x = $focal_point['x'] ?? 0.5; // Valeur entre 0 et 1
    $y = $focal_point['y'] ?? 0.5; // Valeur entre 0 et 1

    // Convertir en pourcentage
    $x_percent = ($x * 100) . '%';
    $y_percent = ($y * 100) . '%';
}
?>
```

### Exemple 1 : Appliquer le focal point avec object-position

```php
<?php
$focal_point = get_post_meta(get_the_ID(), 'thumbnail_focal_point', true);
$object_position = '50% 50%'; // Valeur par défaut (centre)

if ($focal_point && is_array($focal_point)) {
    $x_percent = ($focal_point['x'] * 100);
    $y_percent = ($focal_point['y'] * 100);
    $object_position = $x_percent . '% ' . $y_percent . '%';
}
?>

<div class="post-thumbnail">
    <?php
    the_post_thumbnail('large', [
        'style' => 'object-fit: cover; object-position: ' . esc_attr($object_position) . ';'
    ]);
    ?>
</div>
```

### Exemple 2 : Utiliser le focal point comme background-position

```php
<?php
$focal_point = get_post_meta(get_the_ID(), 'thumbnail_focal_point', true);
$bg_position = '50% 50%';

if ($focal_point && is_array($focal_point)) {
    $x_percent = ($focal_point['x'] * 100);
    $y_percent = ($focal_point['y'] * 100);
    $bg_position = $x_percent . '% ' . $y_percent . '%';
}

$thumbnail_url = get_the_post_thumbnail_url(get_the_ID(), 'large');
?>

<div class="post-thumbnail-bg"
     style="background-image: url(<?php echo esc_url($thumbnail_url); ?>);
            background-position: <?php echo esc_attr($bg_position); ?>;
            background-size: cover;">
</div>
```

### Exemple 3 : Fonction helper réutilisable

Ajoutez cette fonction dans votre `functions.php` :

```php
<?php
/**
 * Obtenir le focal point d'un post
 *
 * @param int|null $post_id ID du post (null pour le post courant)
 * @return array Tableau avec 'x' et 'y' (valeurs entre 0 et 1)
 */
function get_thumbnail_focal_point($post_id = null) {
    if (!$post_id) {
        $post_id = get_the_ID();
    }

    $focal_point = get_post_meta($post_id, 'thumbnail_focal_point', true);

    // Valeurs par défaut (centre de l'image)
    if (!$focal_point || !is_array($focal_point)) {
        return ['x' => 0.5, 'y' => 0.5];
    }

    return [
        'x' => $focal_point['x'] ?? 0.5,
        'y' => $focal_point['y'] ?? 0.5
    ];
}

/**
 * Obtenir le focal point formaté pour CSS
 *
 * @param int|null $post_id ID du post (null pour le post courant)
 * @return string Format "50% 50%" pour object-position ou background-position
 */
function get_thumbnail_focal_point_css($post_id = null) {
    $focal_point = get_thumbnail_focal_point($post_id);
    $x_percent = ($focal_point['x'] * 100);
    $y_percent = ($focal_point['y'] * 100);

    return $x_percent . '% ' . $y_percent . '%';
}
?>
```

Puis dans vos templates :

```php
<div class="post-thumbnail">
    <?php
    the_post_thumbnail('large', [
        'style' => 'object-fit: cover; object-position: ' . get_thumbnail_focal_point_css() . ';'
    ]);
    ?>
</div>
```

## Support des post types

Le plugin enregistre automatiquement les métadonnées du focal point pour tous les post types publics qui supportent les images mises en avant (thumbnails).

## Données sauvegardées

Les données sont sauvegardées dans les post meta sous la clé `thumbnail_focal_point` au format :

```json
{
	"x": 0.5,
	"y": 0.5
}
```

Où `x` et `y` sont des nombres décimaux entre 0 et 1 :

- `x: 0` = gauche, `x: 0.5` = centre, `x: 1` = droite
- `y: 0` = haut, `y: 0.5` = milieu, `y: 1` = bas