CarbonFields est une bibliothèque open-source pour WordPress qui permet de créer des champs personnalisés pour les différents type de contenu de WordPress (Option du thème, contenu, taxonomie, élément de menu...) à l'aide de méthodes simples qui permettent de grandement simplifier le code nécessaire.
Installation
La librairie peut être chargée via composer
composer require htmlburger/carbon-fieldsOu en le téléchargeant sous forme de plugin et en mettant le contenu de l'archive dans le dossier plugin. Ensuite, vous pouvez charger CarbonField dans votre fichier functions.php.
use Carbon_Fields\Container;
use Carbon_Fields\Field;
add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );
function crb_attach_theme_options() {
// Exemple de code pour créer un champs d'option
Container::make( 'theme_options', __( 'Theme Options' ) )
->add_fields( array(
Field::make( 'text', 'crb_text', 'Text Field' ),
) );
}
// Si vous utilisez la version "plugin", vous pouvez supprimer cette partie
add_action( 'after_setup_theme', 'crb_load' );
function crb_load() {
require_once( 'vendor/autoload.php' );
\Carbon_Fields\Carbon_Fields::boot();
}Utilisation
Une fois installé et initialisé vous pouvez utiliser les différentes classes offertes par CarbonFields pour générer vos champs.
- La classe
Carbon_Fields\Containerpermet de définir un groupe de champs. C'est cette classe qui permettra de définir où on veut afficher nos champs (`post_meta', 'theme_options', 'user_meta'...) - La classe
Carbon_Fields\Fieldpermet de définir un champ.
Voici quelques exemples :
use \Carbon_Fields\Container;
use \Carbon_Fields\Field;
// Crée une nouvelle entrée dans le menu de l'admin WordPress
Container::make('theme_options', 'Option du theme')
->add_tab('Pied de page', [
Field::make('text', 'facebook_url', 'URL Facebook'),
Field::make('text', 'twitter_url', 'URL Twitter'),
Field::make('text', 'youtube_url', 'URL Youtube'),
])
->add_tab('Apparence', [
Field::make('color', 'bg_color', 'Couleur de fond'),
]);
// Ajoute des champs à un type de contenu particulier
Container::make('post_meta', 'Information sur le bien')
->where('post_type', '=', 'property')
->add_fields([
Field::make("select", "property_category", "Achat ou location ?")
->set_default_value('rent')
->set_options([
'rent' => 'Location',
'buy' => 'Achat'
]),
Field::make("text", "surface", "Surface")
->set_attribute('type', 'number'),
// Un champs complex permet de créer un répéteur
Field::make('complex', 'property_options', 'Options')
->add_fields([
Field::make('text', 'name', 'Nom de l\'option'),
Field::make('checkbox', 'available', 'Disponible ?')
])
->set_layout('tabbed-vertical')
->set_header_template('<%- name %> <%- available ? "✅" : "❌" %>')
]);Si vous voulez plus d'exemples n'hésitez pas à faire un tour sur la documentation de CarbonFields.
Bloc gutenberg
Vous pouvez aussi créer des blocs gutenberg depuis CarbonFields :
use \Carbon_Fields\Block;
use \Carbon_Fields\Container;
Block::make('Mon nouveau bloc')
->add_fields([
Field::make( 'text', 'heading', 'En tête'),
Field::make( 'image', 'image', 'Image'),
Field::make( 'rich_text', 'content', 'Contenu'),
])
->set_render_callback( function ($fields, $attributes, $inner_blocks) {
?>
<div class="block">
<div class="block__heading">
<h1><?= esc_html( $fields['heading'] ); ?></h1>
</div>
<div class="block__image">
<?= wp_get_attachment_image( $fields['image'], 'full' ); ?>
</div>
<div class="block__content">
<?= apply_filters( 'the_content', $fields['content'] ); ?>
</div>
</div>
<?php
});Champ personnalisé
Si vous ne trouvez pas votre bonheur dans les champs préconçus. Vous pouvez étendre CarbonFields pour créer votre propre champs.
On commence par créer une classe (nommé XXX_Field) qui contiendra la logique de notre champs.
use \Carbon_Fields\Field\Field;
use \Carbon_Fields\Value_Set\Value_Set;
class Demo_Field extends Field {
public function __construct($type, $name, $label){
// Dans le cas d'un champs composé de plusieurs propriétés, on déclare le type et la valeur par défaut
$this->set_value_set(new Value_Set(Value_Set::TYPE_MULTIPLE_PROPERTIES, ['firstname' => '', 'lastname' => '']));
parent::__construct($type, $name, $label);
}
// Charge le JavaScript nécessaire à l'enregistrement de l'interface du champs
public static function admin_enqueue_scripts()
{
// Adaptez le chemin en fonction de votre situation
$rootUrl = \Carbon_Fields\Carbon_Fields::directory_to_url(dirname(__FILE__));
wp_enqueue_script('carbon-field-demo', $rootUrl . '/demo.js', ['carbon-fields-core']);
}
}Côté JS il faudra créer un composant React pour rendre l'interface.
// cf.vendor contient les dépendances nécessaires
// On importe la fonction de rendu react provenant de WordPress
const h = cf.vendor['@wordpress/element'].createElement;
// Le nom du champs est en minuscule et sans le _Field.
window.cf.core.registerFieldType('demo', function ({id, value, name}) {
// On peut écrire du JSX si on a l'outils pour le convertir en JavaScript
return h('div', {}, [
h('input', {id, defaultValue: value.firstname, name: `${name}[firstname]`}),
h('input', {id, defaultValue: value.lastname, name: `${name}[lastname]`})
])
})Ensuite on va enregistrer notre champs.
\Carbon_Fields\Carbon_Fields::extend(Demo_Field::class, function ($container) {
return new Demo_Field(
$container['arguments']['type'],
$container['arguments']['name'],
$container['arguments']['label'],
);
});Et on pourra l'utiliser dans nos différents Container.
// Le nom du champs est en minuscule et sans le _Field.
Field::make('demo', 'property_demo', 'Champs de démonstration')
