Champs personnalisés

Elementum utilise Carbon Fields pour la gestion des champs personnalisés, avec une intégration simplifiée pour une meilleure expérience de développement.

Création de champs personnalisés

La méthode recommandée : addContainerFields

Pour ajouter des champs à votre type de contenu, utilisez la méthode addContainerFields dans votre classe de post type. Cette approche offre plusieurs avantages :

1. Enregistrement automatique des conteneurs dans le système
2. Préfixage automatique des noms de champs
3. Récupération simplifiée des valeurs dans les templates

app/PostTypes/MyPostType.php

use Carbon_Fields\Field;

public function createFields()
{
    $this->addContainerFields('Informations', [
        Field::make('text', 'mypost_price', 'Prix')
            ->set_attribute('type', 'number')
            ->set_attribute('step', '0.01')
            ->set_help_text('Prix en euros'),

        Field::make('checkbox', 'mypost_is_featured', 'Mise en avant')
            ->set_option_value('yes')
    ], sidebar: true);
}

Positionner un container en sidebar

Depuis 26.0.8.7, addContainerFields() accepte un argument nommé sidebar :

• sidebar: false (par défaut) : container dans la zone principale
• sidebar: true : container affiché dans la colonne droite de Gutenberg (set_context('side'))

$this->addContainerFields('Informations', [
    Field::make('text', 'mypost_price', 'Prix')
], sidebar: true);

Pourquoi utiliser addContainerFields ?

1. Préfixage automatique : Les noms de champs sont automatiquement préfixés avec l'identifiant du post type
2. Organisation : Les champs sont regroupés dans des conteneurs logiques
3. Performance : Chargement optimisé des champs
4. Maintenance : Meilleure lisibilité et organisation du code

Récupération des valeurs dans un template Twig

{# Récupération de tous les champs d'un conteneur #}

<article>
    <h2>{{ post.title }}</h2>

    <div class="price">
        Prix : {{ post.get_field('mypost_price')|number_format(2, ',', ' ') }} €
    </div>

    {% if post.get_field('mypost_is_featured') %}
        <span class="badge">Mise en avant</span>
    {% endif %}
</article>

Récupération d'un champ hors déclaration

Par défaut, getField() retourne null si le champ demandé n'est pas déclaré dans la configuration du CPT. Le paramètre $force = true contourne cette vérification et lit directement la meta WordPress.

// Retourne null si 'legacy_field' n'est pas déclaré dans addContainerFields
$value = $post->getField('legacy_field');

// Retourne la valeur quoi qu'il arrive
$value = $post->getField('legacy_field', '', force: true);

Utile pour lire des metas créées en dehors d'Elementum (migration, plugin tiers, champ hérité).

Bonnes pratiques

• Utilisez toujours addContainerFields au lieu des méthodes natives de Carbon Fields
• Groupez les champs liés dans des conteneurs logiques
• Utilisez des préfixes cohérents pour les noms de champs
• Documentez vos champs avec set_help_text() quand nécessaire

Types de champs disponibles

Elementum supporte tous les types de champs de Carbon Fields. Consultez la documentation officielle pour la liste complète.

---

Note importante : Bien que vous puissiez utiliser directement les méthodes de Carbon Fields, l'utilisation de addContainerFields est fortement recommandée pour une meilleure intégration avec le système de post types d'Elementum.