> For the complete documentation index, see [llms.txt](https://akyos.gitbook.io/book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://akyos.gitbook.io/book/wordpress/plugins/acf.md).

# ACF

### Introduction

{% hint style="success" %}
Quand utiliser un champ ACF ? 
{% endhint %}

Les champs ACF permettent d'ajouter des données supplémentaires administrables à un contenu ou type de contenu.

{% hint style="info" %}
Il faut toujours utiliser au maximum les champs proposées par Wordpress en priorité. Ne pas override des champs déjà existants.
{% endhint %}

Exemple : un bien immobilier a un nom, une image, un prix, un bouton qui renvoie vers un formulaire de contact générique et doit afficher s'il est vendu ou non.

| Champs Wordpress | Champs ACF             | Statique dans le code |
| ---------------- | ---------------------- | --------------------- |
| Nom              | Prix (number)          | Bouton formulaire     |
| Image            | Etat vendu (truefalse) |                       |

### Utilisation des champs ACF

<table><thead><tr><th>Champs ACF</th><th>Utilisation</th></tr></thead><tbody><tr><td><pre><code>RadioButton
</code></pre></td><td>Sélectionner une valeur unique parmi une liste de choix</td></tr><tr><td><pre><code>Select
</code></pre></td><td>Sélectionner une ou plusieurs valeurs parmi une liste de choix</td></tr><tr><td><pre><code>TrueFalse
</code></pre></td><td>Définit un état binaire</td></tr><tr><td><pre><code>Relationship
</code></pre></td><td>Définit des relations entre 2 contenus (à privilégier par rapport à <strong>Post Object)</strong></td></tr><tr><td><pre><code>Repeater
</code></pre></td><td>Permet de créer un groupe de champs combinés pour un contenu nécessitant plusieurs données.</td></tr></tbody></table>

### Layout fields

En plus d'ajouter de donner la possibilité d'insérer de nouvelles données, des champs ACF existent pour épurer et rendre plus ergonomique l'interface, ce sont les layout fields.

{% hint style="info" %}
Exemple : séparer la gestion du contenu et la gestion du style
{% endhint %}

{% hint style="warning" %}
Il est important de penser aux utilisateurs finaux (les clients) lors de la création des champs ACF pour que cela soit le plus simple et clair possible.
{% endhint %}

<table><thead><tr><th>Layout fields</th><th>Utilisation</th></tr></thead><tbody><tr><td><pre><code>Accordion
</code></pre></td><td>Organiser les champs en panneaux pliables</td></tr><tr><td><pre><code>Tab
</code></pre></td><td>Créer des onglets</td></tr><tr><td><pre><code>Group
</code></pre></td><td>Grouper plusieurs champs qui correspondent à un même contenu</td></tr><tr><td><pre><code>FlexibleContent
</code></pre></td><td>Utile pour moduler plusieurs groupes de champs ACF dans une même page et de les organiser de façon dynamique</td></tr></tbody></table>

### Structure

Les champs ACF sont gérés avec l'API Extended ACF : <https://github.com/vinkla/extended-acf>

{% hint style="success" %}
Structure dossier ACF
{% endhint %}

```
├── CustomFields
├── GroupsFields
├─ template-{slug}.php
├─ theme-options.php
```

<details>

<summary>CustomFields</summary>

Le dossier CustomFields comporte des champs ACF custom permettant d'ajouter de nouvelles fonctionnalités.

Exemple : Sélecteur de gradient / Sélecteur d'icones / Sélecteur de styles

</details>

<details>

<summary>GroupsFields</summary>

Le dossier GroupsFields contient dans chaque fichier un ensemble de champs ACF qui peuvent être appelé en 1 appel.

Cela permet de factoriser des déclarations de champs qui seraient nécessaires à plusieurs endroits

Exemple :&#x20;

Un group "Title" comportant 2 champs ACF (Text et Button)

En appelant `Title::make()`, on déclare directement 2 champs&#x20;

```php
return Group::make($label, $id)->fields([
            Text::make('Valeur', 'value'),
            ButtonGroup::make('Balise', 'tag')->choices([
                'h1' => 'H1',
                'h2' => 'H2',
                'h3' => 'H3',
                'h4' => 'H4',
                'h5' => 'H5',
                'p' => 'p',
                'span' => 'span',
            ]),
        ])->layout($layout);
```

</details>

<details>

<summary>template-{slug}.php</summary>

Créer un fichier dédié pour les champs ACF présent sur un style de template avec le slug du template

Ex : `template-home.php`

</details>

<details>

<summary>theme-options.php</summary>

Déclaration de tous les champs présent dans les options du thème

</details>

### Post type et taxonomie

{% hint style="info" %}
Déclaration champs ACF des posts type et taxonomy
{% endhint %}

La déclaration des posts type ainsi que leurs taxonomies s'effectue dans le fichier `app/posts_type.php`&#x20;

Voir : [Wrapper PostType / Taxonomy](/book/wordpress/akyos-x-core/wrappers/posttype-taxonomy.md)

```php
// Utilisation du wrapper PostType::class

PostType::register('slug', 'title', 'title-plural', 'url-rewrite', 'icon', true, true)
    ->fields([ Text::make('Example', 'exemple'), ])
    ->taxonomies([
        Taxonomy::register('slug', 'title', 'title-plural', 'url-rewrite')
            ->fields([ Text::make('Example', 'exemple'), ])
        ->make()
    ])
->make();
```

### Page d'options

Le plugin ACF permet également d'avoir un ou plusieurs page d'options pour définir des champs personnalisés globaux, accessibles partout sur le site.

{% hint style="info" %}
Une page d'option est disponible de base dans le thème
{% endhint %}

Les pages d'options sont utilisées pour :&#x20;

* Les informations du header (logo, logo mobile, tagline, CTA)
* Les informations du footer (réseaux sociaux, coordonnées)
* Des paramètres de thème (couleur, nombre de colonnes pour le footer)
* Du contenu statique présent sur tout le site (un catalogue à télécharger, une image de fond..)

```php
//theme-options.php

if (function_exists('register_extended_field_group')) {
    register_extended_field_group([
        'title' => 'Options du thème',
        'style' => 'default',
        'fields' => [
        	
            Tab::make('Topbar'),
            Text::make("Tagline", 'topbar_tagline'),

            Tab::make('Général'),
            Image::make("Logo chefcut", 'logo')->returnFormat('id'),
            Image::make("Logo hydroprocess", 'hp_logo')->returnFormat('id'),
            Link::make("Page contact", 'contact_link'),
            Url::make("facebook", 'facebook'),
            Url::make("instagram", 'instagram'),
            Url::make("linkedin", 'linkedin'),
            Url::make("youtube", 'youtube'),
            Image::make("Fond page login", 'bg_page_login')->returnFormat('url'),

            Tab::make('Mapmonde'),
            Repeater::make("Points", 'points')
                ->fields([
                    Text::make("Latitude", 'lat'),
                    Text::make("Longitude", 'lng'),
                    WysiwygEditor::make("Description", 'csontent'),
                ]),

            Tab::make('Archive'),
            Text::make('Nom de la page archive "Biliothèque"', 'program_title')
        ],
        'location' => [
            Location::where('options_page', '===', THEME_OPTION),
        ],
    ]);
}
```