WordPress hwk Blog ACF: Ajouter des Options Personnalisées aux Groupes de Champs

ACF: Ajouter des Options Personnalisées aux Groupes de Champs

16 December 2017

Les paramètres personnalisés de groupes de champs sont un fantastique moyen d’améliorer le confort d’utilisation et d’administration d’ACF. Le plugin nous permet d’ajouter à peut prêt tous les champs disponible dans sa librairie. Son utilisation? Pouvoir par exemple automatiser l’ajout de groupes de champs dans un contenu flexible.

Création de champs dans les réglages d’ACF

Pour ajouter proprement nos champs nous allons utiliser l’action acf/render_field_group_settings. Celle-ci intervient juste après les réglages de base de ACF (Actif, Style, Position etc…). A noter que certains champs n’ont pas tous les arguments disponible. Par exemple l’upload d’image ou de fichier ne permet pas de filtrer le mime_type ou encore la taille minimale/maximale.

Malheureusement les champs de type group, clone, flexible_content ne sont pas fonctionnels, mais il y a tout de même de quoi s’amuser avec le reste! Pas moins de 32 champs pour pimenter les réglages de vos champs personnalisés. J’ai listé ci-dessous les champs avec leurs arguments disponibles. Les arguments commentés sont non-fonctionnels.

<?php
add_action('acf/render_field_group_settings', 'hwk_acf_field_groups_add_settings', 10);
function hwk_acf_field_groups_add_settings($group){
/****************
* Basic
****************/
// Text
// Return: "hwk_text": "foo bar"
acf_render_field_wrap(array(
'label' => __('Texte','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'text',
'name' => 'hwk_text',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_text'])) ? $group['hwk_text'] : '',
'placeholder' => 'placeholder',
'prepend' => 'prefixe',
'append' => 'suffixe',
'maxlength' => 2
));
// Textarea
// Return: "hwk_textarea": "foo bar"
acf_render_field_wrap(array(
'label' => __('Textarea','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'textarea',
'name' => 'hwk_textarea',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_textarea'])) ? $group['hwk_textarea'] : '',
'placeholder' => 'placeholder',
'maxlength' => 2,
'rows' => 8,
'new_lines' => 'wpautop' // wpautop | br | (empty)
));
// Number
// Return: "hwk_number": 1
acf_render_field_wrap(array(
'label' => __('Number','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'number',
'name' => 'hwk_number',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_number'])) ? $group['hwk_number'] : '',
'placeholder' => 'placeholder',
'prepend' => 'prefixe',
'append' => 'suffixe',
'min' => 0,
'max' => 100,
'step' => 1
));
// Range
// Return: "hwk_range": 1
acf_render_field_wrap(array(
'label' => __('Range','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'range',
'name' => 'hwk_range',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_range'])) ? $group['hwk_range'] : 0,
'prepend' => 'prefixe',
'append' => 'suffixe',
'min' => 0,
'max' => 100,
'step' => 1
));
// Mail
// Return: "hwk_email": "[email protected]"
acf_render_field_wrap(array(
'label' => __('Email','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'email',
'name' => 'hwk_email',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_email'])) ? $group['hwk_email'] : '',
'placeholder' => 'placeholder',
'prepend' => 'prefixe',
'append' => 'suffixe'
));
// URL
// Return: "hwk_url": "http://www.google.com"
acf_render_field_wrap(array(
'label' => __('URL','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'url',
'name' => 'hwk_url',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_url'])) ? $group['hwk_url'] : '',
'placeholder' => 'placeholder'
));
// Password
// Return: "hwk_password": "foobar"
acf_render_field_wrap(array(
'label' => __('Password','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'password',
'name' => 'hwk_password',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_password'])) ? $group['hwk_password'] : '',
'placeholder' => 'placeholder',
'prepend' => 'prefixe',
'append' => 'suffixe'
));
/****************
* Content
****************/
// Image
// Return: "hwk_image": 431
acf_render_field_wrap(array(
'label' => __('Image','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'image',
'name' => 'hwk_image',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_image'])) ? $group['hwk_image'] : '',
'preview_size' => 'thumbnail',
//'min_width' => 10,
//'min_height' => 20,
//'max_width' => 100,
//'max_height' => 200,
//'min_size' => 5,
//'max_size' => 50,
//'mime_types' => 'jpg,pdf'
//'return_format' => 'url'
));
// File
// Return: "hwk_file": 432
acf_render_field_wrap(array(
'label' => __('File','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'file',
'name' => 'hwk_file',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_file'])) ? $group['hwk_file'] : '',
'min_size' => 5,
'max_size' => 50
));
// WYSIWYG
// Return: "hwk_wysiwyg": "<strong>Lorem ipsum</strong>"
acf_render_field_wrap(array(
'label' => __('WYSIWYG','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'wysiwyg',
'name' => 'hwk_wysiwyg',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_wysiwyg'])) ? $group['hwk_wysiwyg'] : '',
'tabs' => 'all', // all | visual | text
'toolbar' => 'full', // full | basic
'media_upload' => true // true | false
));
// oEmbed
// Return: "hwk_oembed": "https://www.youtube.com/watch?v=s09Ldx2HdaA"
acf_render_field_wrap(array(
'label' => __('oEmbed','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'oembed',
'name' => 'hwk_oembed',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_oembed'])) ? $group['hwk_oembed'] : '',
'width' => 640,
'height' => 390
));
// Gallery
// Return: "hwk_gallery": ["431","433"]
acf_render_field_wrap(array(
'label' => __('Gallery','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'gallery',
'name' => 'hwk_gallery',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_gallery'])) ? $group['hwk_gallery'] : '',
'min' => 1,
'max' => 5,
'insert' => 'prepend' // prepend |append
));
/****************
* Choices
****************/
// Select
// Return: "hwk_select": ["zero"]
acf_render_field_wrap(array(
'label' => __('Select','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'select',
'name' => 'hwk_select',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_select'])) ? $group['hwk_select'] : '',
'toggle' => false,
'choices' => array(
'zero' =>__('Zero', 'acf'),
'un' =>__('Un', 'acf'),
),
'allow_null' => true, // true | false
'multiple' => true, // true | false
'ui' => true, // true | false
'ajax' => false // true | false
));
// Checkbox
// Return: "hwk_checkbox": ["FooBar"]
acf_render_field_wrap(array(
'label' => __('Checkbox','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'checkbox',
'name' => 'hwk_checkbox',
'key' => 'hwk_checkbox',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_checkbox'])) ? $group['hwk_checkbox'] : '',
'choices' => array(
'zero' =>__('Zero', 'acf'),
'un' =>__('Un', 'acf')
),
'allow_custom' => true, // true | false
'save_custom' => true, // true | false
'toggle' => true, // true | false
'layout' => 'vertical' // vertical | horizontal
));
// Radio
// Return: "hwk_radio": "un"
acf_render_field_wrap(array(
'label' => __('Radio','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'radio',
'name' => 'hwk_radio',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_radio'])) ? $group['hwk_radio'] : '',
'choices' => array(
'zero' =>__('Zero', 'acf'),
'un' =>__('Un', 'acf'),
),
'allow_null' => true, // true | false
'other_choice' => true, // true | false
'save_other_choice' => true, // true | false
'layout' => 'vertical' // vertical | horizontal
));
// Bouton Group
// Return: "hwk_button_group": "zero"
acf_render_field_wrap(array(
'label' => __('Button Group','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'button_group',
'name' => 'hwk_button_group',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_button_group'])) ? $group['hwk_button_group'] : '',
'choices' => array(
'zero' =>__('Zero', 'acf'),
'un' =>__('Un', 'acf'),
),
'allow_null' => true, // true | false
'layout' => 'horizontal' // vertical | horizontal
));
// True False
// Return: "hwk_true_false": 1
acf_render_field_wrap(array(
'label' => __('True / False','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'true_false',
'name' => 'hwk_true_false',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_true_false'])) ? $group['hwk_true_false'] : '',
'message' => 'Message',
'default_value' => true, // true | false
'ui' => true, // true | false
'ui_on_text' => 'Actif',
'ui_off_text' => 'Inactif'
));
/****************
* Relationnel
****************/
// Link
// Return: "hwk_link": {"title": "Google","url": "http://www.google.com","target": "_blank"}
acf_render_field_wrap(array(
'label' => __('Link','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'link',
'name' => 'hwk_link',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_link'])) ? $group['hwk_link'] : ''
));
// Post Object
// Return: "hwk_post_object": ["4"]
acf_render_field_wrap(array(
'label' => __('Post Object','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'post_object',
'name' => 'hwk_post_object',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_post_object'])) ? $group['hwk_post_object'] : '',
//'post_type' => array('post'), // Bugged
//'taxonomy' => array('category:non-classe'), // Bugged
'allow_null' => true, // true | false
'multiple' => true, // true | false
'ui' => true // true | false
));
// Page Link
// Return: "hwk_page_link": ["5"]
acf_render_field_wrap(array(
'label' => __('Page Link','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'page_link',
'name' => 'hwk_page_link',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_page_link'])) ? $group['hwk_page_link'] : '',
//'post_type' => array('post'), // Bugged
//'taxonomy' => array('category:non-classe'), // Bugged
'allow_null' => true, // true | false
'allow_archives' => true, // true | false
'multiple' => true // true | false
));
// Relationship
// Return: "hwk_relationship": ["4","5"]
acf_render_field_wrap(array(
'label' => __('Relationship','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'relationship',
'name' => 'hwk_relationship',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_relationship'])) ? $group['hwk_relationship'] : '',
//'post_type' => array('page'), // Bugged
//'taxonomy' => array('category:non-classe'), // Bugged
'filters' => array(
'search',
'post_type',
'taxonomy'
),
'elements' => array(
'featured_image'
),
'min'=> 1,
'max'=> 2
));
// Taxonomy
// Return multiple=true: "hwk_taxonomy": ["1","3"]
// Return multiple=false: "hwk_taxonomy": "1"
acf_render_field_wrap(array(
'label' => __('Taxonomy','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'taxonomy',
'name' => 'hwk_taxonomy',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_taxonomy'])) ? $group['hwk_taxonomy'] : '',
'taxonomy' => 'category',
'field_type' => 'checkbox', // checkbox | radio | multi_select (bugged) | select (bugged)
'allow_null' => true, // true | false
'add_term' => true, // true (bugged) | false
'save_terms' => true, // true | false
'load_terms' => true, // true | false
'multiple' => true // true | false
));
// User
// Return multiple=true: "hwk_user": ["1","2"]
// Return multiple=false: "hwk_user": "1"
acf_render_field_wrap(array(
'label' => __('User','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'user',
'name' => 'hwk_user',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_user'])) ? $group['hwk_user'] : '',
//'role' => array('editor'),
'allow_null' => true, // true | false
'multiple' => true // true | false
));
/****************
* jQuery
****************/
// Google Map
// Return: "hwk_google_map": {"address": "X621, Hangjin Qi, Eerduosi Shi, Neimenggu Zizhiqu, Chine","lat": "40.18782406112183","lng": "107.29687929153442"}
acf_render_field_wrap(array(
'label' => __('Google Map','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'google_map',
'name' => 'hwk_google_map',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_google_map'])) ? $group['hwk_google_map'] : '',
'center_lat' => '',
'center_lng' => '',
'zoom' => 1,
'height' => 200
));
// Date Picker
// Return: "hwk_date_picker": 20171219
acf_render_field_wrap(array(
'label' => __('Date Picker','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'date_picker',
'name' => 'hwk_date_picker',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_date_picker'])) ? $group['hwk_date_picker'] : '',
'display_format' => 'd/m/Y',
'first_day' => 1 // 0 | 1 (Lundi) | 2 | 3 | 4 | 5 | 6
));
// Date Time Picker
// Return: "hwk_date_time_picker": "2017-12-19 15:00:00"
acf_render_field_wrap(array(
'label' => __('Date Time Picker','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'date_time_picker',
'name' => 'hwk_date_time_picker',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_date_time_picker'])) ? $group['hwk_date_time_picker'] : '',
'display_format' => 'd/m/Y g:i a',
'first_day' => 1 // 0 | 1 (Lundi) | 2 | 3 | 4 | 5 | 6
));
// Time Picker
// Return: "hwk_time_picker": "17:29:49"
acf_render_field_wrap(array(
'label' => __('Time Picker','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'time_picker',
'name' => 'hwk_time_picker',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_time_picker'])) ? $group['hwk_time_picker'] : '',
'display_format' => 'g:i a'
));
// Color Picker
// Return: "hwk_color_picker": "#81d742"
acf_render_field_wrap(array(
'label' => __('Color Picker','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'color_picker',
'name' => 'hwk_color_picker',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_color_picker'])) ? $group['hwk_color_picker'] : ''
));
/****************
* Disposition
****************/
// Message
acf_render_field_wrap(array(
'label' => __('Message','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'message',
'name' => 'hwk_message',
'prefix' => 'acf_field_group',
'message' => 'Message',
'new_lines' => 'wpautop', // wpautop | br | (empty)
'esc_html' => true // true | false
));
// Accordion
acf_render_field_wrap(array(
'label' => __('Accordion','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'accordion',
'name' => 'hwk_accordion',
'key' => 'hwk_accordion',
'prefix' => 'acf_field_group',
'open' => false, // true | false
'multi_expand' => false, // true | false
'endpoint' => 0
));
// Tab
acf_render_field_wrap(array(
'label' => __('Tab','acf'),
'type' => 'tab',
'name' => 'hwk_tab_tab',
'key' => 'hwk_tab_tab',
'prefix' => 'acf_field_group',
'placement' => 'left', // top | left
'endpoint' => 0
));
}

Compatible avec les plugins ACF

Vous pouvez en effet utiliser des champs personnalisés crées par un plugin. Dans cet exemple, nous allons ajouter le champ de l’excellent plugin: Advanced Custom Field Font Awesome.

<?php
add_action('acf/render_field_group_settings', 'hwk_acf_field_groups_add_settings_fa', 10);
function hwk_acf_field_groups_add_settings_fa($group){
// Font Awesome
// Return: "hwk_fontawesome": "fa-500px"
acf_render_field_wrap(array(
'label' => __('Font Awesome','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'font-awesome',
'name' => 'hwk_fontawesome',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_fontawesome'])) ? $group['hwk_fontawesome'] : '',
'allow_null' => true, // true | false
'show_preview' => false // true | false
));
}

Aller plus loin: Créer sa propre metabox

Si vous avez avez beaucoup de champs supplémentaires, il serait judicieux de carrément créer sa propre metabox afin de bien les séparer de la metabox “Réglages” de ACF. Pour cela, nou sallons utiliser le hook acf/field_group/admin_head. Il semble assez générique, mais pourtant celui-ci intervient juste après la création des metaboxes de conditions et réglages.

<?php
add_action('acf/field_group/admin_head', 'hwk_acf_field_groups_add_metabox');
function hwk_acf_field_groups_add_metabox(){
add_meta_box('acf-field-group-options-plus', __('Options supplémentaires', 'acf'), function(){
global $field_group;
if(!acf_is_field_group_key( $field_group['key']))
$field_group['key'] = uniqid('group_');
$group = $field_group;
acf_render_field_wrap(array(
'label' => __('Texte','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'text',
'name' => 'hwk_text',
'prefix' => 'acf_field_group',
'value' => (isset($group['hwk_text'])) ? $group['hwk_text'] : '',
'placeholder' => 'placeholder',
'prepend' => 'prefixe',
'append' => 'suffixe',
'maxlength' => 2
));
//
?>
<script type="text/javascript">
if(typeof acf !== 'undefined'){
acf.postbox.render({
'id': 'acf-field-group-options-plus',
'label': 'left'
});
}
</script>
<?php
}, 'acf-field-group', 'normal', 'high');
}

Créer des onglets ou accordéons

L’utilisation des onglets ou accordéons dans les metaboxes requiert un argument supplémentaire: key. Vous pouvez utiliser ici la même valeur que l’argument name.

<?php
add_action('acf/render_field_group_settings', 'hwk_acf_field_groups_add_settings_tabs', 10);
function hwk_acf_field_groups_add_settings_tabs($group){
// Tab
acf_render_field_wrap(array(
'label' => __('Basic','acf'),
'type' => 'tab',
'name' => 'hwk_tab_basic',
'key' => 'hwk_tab_basic',
'prefix' => 'acf_field_group',
'placement' => 'top',
'endpoint' => 0
));
// Accordion
acf_render_field_wrap(array(
'label' => __('Accordion','acf'),
'instructions' => __('Instructions','acf'),
'type' => 'accordion',
'name' => 'hwk_accordion',
'key' => 'hwk_accordion',
'prefix' => 'acf_field_group',
'open' => false, // true | false
'multi_expand' => false, // true | false
'endpoint' => 0
));
}

Récupérer les valeurs

Afin de travailler avec nos nouveaux paramètres personnalisés, nous allons devoir récupérer l’objet du groupe de champs. Pour cela nous avons à disposition quelques fonctions plutôt pratique, comme par exemple acf_get_field_group($group_key).

Il y a différents moyens de récupérer la clé du groupe de champs. Le plus simple est de passer par l’administration d’un groupe de champs et d’afficher son identifiant via les options d’affichage en haut à droite. Un group_key devrait ressembler à group_5a365d05760bb.

Les valeurs de nos champs personnalisés sont stockés directement dans l’objet du groupe, au niveau du titre, des conditions d’affichage etc… Afin de récupérer cet objet depuis une page, nous pouvons nous servir de la fonction get_field_object($field), qui fonctionne de la même manière que le fameux get_field($field). Au lieu de retourner simplement une donnée, get_field_object($field) nous retourne tout l’objet du champs spécifié (son titre, sa logique conditionnelle etc) mais aussi, et surtout, son parent. Notre fameuse clé de groupe.

Ainsi, nous pouvons créer une fonction afin de directement récupérer notre objet de groupe en passant par un de ses champs.

<?php
function hwk_acf_get_group_by_field($field, $post_id = null){
if(!$post_id)
$post_id = get_the_ID();
if(!$post_id)
$post_id = get_queried_object_id();
if( ($field = get_field_object($field, $post_id)) && isset($field['parent']) && ($group = acf_get_field_group($field['parent'])) )
return $group;
return;
}
$group = hwk_acf_get_group_by_field('champs_texte');
$group['hwk_image'];

Ce qui aura comme résultat:

Array
(
[ID] => 0
[key] => group_5a365d05760bb
[title] => Mon Groupe
[fields] => Array
(
)
[location] => Array
(
[0] => Array
(
[0] => Array
(
[param] => post_type
[operator] => ==
[value] => post
)
)
)
[menu_order] => 0
[position] => acf_after_title
[style] => default
[label_placement] => top
[instruction_placement] => label
[hide_on_screen] =>
[active] => 1
[description] =>
[_valid] => 1
[hwk_text] => Mon champs texte
[hwk_textarea] =>
[hwk_number] =>
[hwk_range] => 0
[hwk_email] =>
[hwk_url] =>
[hwk_password] =>
[hwk_image] =>
[hwk_file] =>
[hwk_wysiwyg] =>
[hwk_oembed] =>
[hwk_gallery] =>
[hwk_fontawesome] =>
[hwk_select] =>
[hwk_checkbox] =>
[hwk_radio] =>
[hwk_button_group] =>
[hwk_true_false] => 1
[hwk_link] => Array
(
[title] =>
[url] =>
[target] =>
)
[hwk_post_object] =>
[hwk_page_link] =>
[hwk_relationship] =>
[hwk_taxonomy] =>
[hwk_user] =>
[hwk_google_map] => Array
(
[address] =>
[lat] =>
[lng] =>
)
[hwk_date_picker] =>
[hwk_date_time_picker] =>
[hwk_time_picker] =>
[hwk_color_picker] =>
[modified] => 1513532661
[local] => json
)


Konrad Chmielewski

Evangeliste WordPress & Full Stack Developer depuis 10 années.