WordPress: Objets de personnalisation | Manuel du développeur de thème

[*]
WordPress: Objets de personnalisation | Manuel du développeur de thème

[*]

L’API Personnaliser est orientée objet. Il existe quatre principaux types d’objets de personnalisation : les panneaux, les sections, les paramètres et les commandes. Les paramètres associent des éléments d’interface utilisateur (contrôles) aux paramètres enregistrés dans la base de données. Les sections sont des conteneurs d’interface utilisateur pour les contrôles, afin d’améliorer leur organisation. Les panneaux sont des conteneurs pour les sections, permettant de regrouper plusieurs sections.

Chaque objet Customizer est représenté par une classe PHP et tous les objets sont gérés par l’objet Customize Manager, WP_Customize_Manager.

Graphique montrant la relation entre chaque type d'objet de personnalisation

Pour ajouter, supprimer ou modifier n’importe quel objet Customizer, et pour accéder au Customizer Manager, utilisez le customize_register accrocher:

function themeslug_customize_register( $wp_customize ) {
  // Do stuff with $wp_customize, the WP_Customize_Manager object.
}
add_action( 'customize_register', 'themeslug_customize_register' );

Le gestionnaire de personnalisation fournit les méthodes add_, get_ et remove_ pour chaque type d’objet Customizer ; chacun fonctionne avec un identifiant. Les méthodes get_ permettent de modifier directement les paramètres spécifiés lors de l’ajout d’un contrôle.

add_action('customize_register','my_customize_register');
function my_customize_register( $wp_customize ) {
  $wp_customize->add_panel();
  $wp_customize->get_panel();
  $wp_customize->remove_panel();

  $wp_customize->add_section();
  $wp_customize->get_section();
  $wp_customize->remove_section();

  $wp_customize->add_setting();
  $wp_customize->get_setting();
  $wp_customize->remove_setting();

  $wp_customize->add_control();
  $wp_customize->get_control();
  $wp_customize->remove_control();
}

Remarque : les thèmes ne doivent généralement pas modifier les sections et panneaux principaux avec les méthodes get, car les thèmes ne doivent pas modifier les fonctionnalités principales et indépendantes du thème. Les plugins sont encouragés à utiliser ces fonctions si nécessaire. Les thèmes ne doivent pas « réorganiser » les sections de personnalisation qui ne sont pas ajoutées par le thème.

Les paramètres gèrent la prévisualisation en direct, l’enregistrement et la désinfection de vos objets de personnalisation. Chaque paramètre est géré par un objet de contrôle. Plusieurs paramètres sont disponibles lors de l’ajout d’un nouveau paramètre :

$wp_customize->add_setting( 'setting_id', array(
  'type' => 'theme_mod', // or 'option'
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
  'default' => '',
  'transport' => 'refresh', // or postMessage
  'sanitize_callback' => '',
  'sanitize_js_callback' => '', // Basically to_json.
) );

Alerte: Important: Faire ne pas utilisez un ID de paramètre qui ressemble à widget_*, sidebars_widgets[*], nav_menu[*], ou nav_menu_item[*]. Ces modèles d’ID de paramètre sont réservés respectivement aux instances de widget, aux barres latérales, aux menus de navigation et aux éléments de menu de navigation. Si vous devez utiliser « widget » dans votre ID de paramètre, utilisez-le comme suffixe au lieu d’un préfixe, par exemple « homepage_widget”.

Il existe deux principaux types de paramètres : les options et les modifications de thème. Les options sont stockées directement dans la table wp_options de la base de données et s’appliquent au site quel que soit le thème actif. Les thèmes doivent rarement, voire jamais, ajouter des paramètres du type d’option. Les mods thématiques, en revanche, sont spécifiques à un thème particulier. La plupart des options de thème devraient être theme_mods. Par exemple, un plugin CSS personnalisé pourrait enregistrer un paramètre CSS de thème personnalisé en tant que theme_mod, permettant à chaque thème d’avoir un ensemble unique de règles CSS sans perdre le CSS lors du changement de thème puis du retour.

personnaliser-thème-mods-options

Exemple de type de paramètre d’option Theme_mod vs.

Il est généralement très important de définir la valeur par défaut du paramètre ainsi que son rappel de nettoyage, ce qui garantira qu’aucune donnée dangereuse n’est stockée dans la base de données. Utilisation typique du thème :

$wp_customize->add_setting( 'accent_color', array(
  'default' => '#f72525',
  'sanitize_callback' => 'sanitize_hex_color',
) );

Utilisation typique du plug-in :

$wp_customize->add_setting( 'myplugin_options[color]', array(
  'type' => 'option',
  'capability' => 'manage_options',
  'default' => '#ff2525',
  'sanitize_callback' => 'sanitize_hex_color',
) );

Notez que le Customizer peut gérer les options stockées sous forme de tableaux à clés pour les paramètres utilisant le type d’option. Cela permet de stocker plusieurs paramètres dans une seule option qui n’est pas un mod de thème. Pour récupérer et utiliser les valeurs de vos options de personnalisation, utilisez get_theme_mod() et get_option() avec l’identifiant du paramètre :

function my_custom_css_output() {
  echo '="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"';
  echo '="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"';
}
add_action( 'wp_head', 'my_custom_css_output');

Notez que le deuxième argument de get_theme_mod() et get_option() est la valeur par défaut, qui doit correspondre à la valeur par défaut que vous avez définie lors de l’ajout du paramètre.

Haut ↑

Les contrôles sont le principal objet Customizer pour la création de l’interface utilisateur. Plus précisément, chaque contrôle doit être associé à un paramètre, et ce paramètre enregistrera les données saisies par l’utilisateur du contrôle dans la base de données (en plus de les afficher dans l’aperçu en direct et de les nettoyer). Des contrôles peuvent être ajoutés par le gestionnaire de personnalisation et fournissent un ensemble robuste d’options d’interface utilisateur avec un minimum d’effort :

$wp_customize->add_control( 'setting_id', array(
  'type' => 'date',
  'priority' => 10, // Within the section.
  'section' => 'colors', // Required, core or custom.
  'label' => __( 'Date' ),
  'description' => __( 'This is a date control with a red border.' ),
  'input_attrs' => array(
    'class' => 'my-custom-class-for-js',
    'style' => 'border: 1px solid #900',
    'placeholder' => __( 'mm/dd/yyyy' ),
  ),
  'active_callback' => 'is_front_page',
) );

Le paramètre le plus important lors de l’ajout d’un contrôle est son type – cela détermine le type d’interface utilisateur que le personnalisateur affichera. Core propose plusieurs types de contrôles intégrés :

  • éléments avec n’importe quel type autorisé (voir ci-dessous)
  • checkbox
  • textarea
  • radio (passez un tableau de valeurs à clé => étiquettes au choices argument)
  • select (passez un tableau de valeurs à clé => étiquettes au choices argument)
  • dropdown-pages (Utilisez le allow_addition argument pour permettre aux utilisateurs d’ajouter de nouvelles pages à partir du contrôle)

Pour tout type d’entrée pris en charge par le html input élément, transmettez simplement la valeur de l’attribut type au paramètre type lors de l’ajout du contrôle. Cela permet la prise en charge de types de contrôle tels que text, hidden, number, range, url, tel, email, search, time, date, datetime, et week, en attente de la prise en charge du navigateur.

Les contrôles doivent être ajoutés à une section avant d’être affichés (et les sections doivent contenir des contrôles à afficher). Cela se fait en spécifiant le paramètre de section lors de l’ajout du contrôle. Voici un exemple d’ajout d’un contrôle textarea de base :

$wp_customize->add_control( 'custom_theme_css', array(
  'label' => __( 'Custom Theme CSS' ),
  'type' => 'textarea',
  'section' => 'custom_css',
) );

Et voici un exemple de contrôle de plage de base (curseur). Notez que la plupart des navigateurs n’afficheront pas la valeur numérique de ce contrôle car le type d’entrée de plage est conçu pour des paramètres où la valeur exacte n’est pas importante. Si la valeur numérique est importante, envisagez d’utiliser le type de nombre. Les input_attrs Le paramètre mappera un tableau d’attributs à clé => valeurs aux attributs de l’élément d’entrée, et peut être utilisé à des fins allant du texte d’espace réservé à data- Données référencées JavaScript dans des scripts personnalisés. Pour les contrôles de nombre et de plage, il nous permet de définir les valeurs minimales, maximales et de pas.

$wp_customize->add_control( 'setting_id', array(
  'type' => 'range',
  'section' => 'title_tagline',
  'label' => __( 'Range' ),
  'description' => __( 'This is the range control description.' ),
  'input_attrs' => array(
    'min' => 0,
    'max' => 10,
    'step' => 2,
  ),
) );

Contrôles personnalisés de base Contrôles personnalisés de base

Si aucun des types de contrôle de base ne correspond à vos besoins, vous pouvez facilement créer et ajouter des contrôles personnalisés. Les contrôles personnalisés sont expliqués plus en détail plus loin dans cet article, mais ce sont essentiellement des sous-classes de la base WP_Customize_Control objet qui autorise tout balisage html arbitraire et toute fonctionnalité dont vous pourriez avoir besoin. Core propose plusieurs contrôles personnalisés intégrés qui permettent aux développeurs d’implémenter facilement de riches fonctionnalités basées sur JavaScript. Un champ de sélection de couleurs peut être ajouté comme suit :

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'color_control', array(
  'label' => __( 'Accent Color', 'theme_textdomain' ),
  'section' => 'media',
) ) );

4.1 et 4.2 ont également ajouté la prise en charge de tout type de contenu multimédia, avec le contrôle Media. Le contrôle des médias implémente le gestionnaire de médias natif, permettant aux utilisateurs de sélectionner des fichiers dans leur bibliothèque ou d’en télécharger de nouveaux. En précisant le mime_type paramètre lors de l’ajout du contrôle, vous pouvez demander à la bibliothèque multimédia d’afficher un type spécifique tel que des images ou de l’audio :

$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'image_control', array(
  'label' => __( 'Featured Home Page Image', 'theme_textdomain' ),
  'section' => 'media',
  'mime_type' => 'image',
) ) );
$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'audio_control', array(
  'label' => _( 'Featured Home Page Recording', 'theme_textdomain' ),
  'section' => 'media',
  'mime_type' => 'audio',
) ) );

Notez que les paramètres associés à WP_Customize_Media_Control enregistrer l’ID de pièce jointe associé, tandis que tous les autres contrôles liés aux médias (enfants de WP_Customize_Upload_Control) enregistrez l’URL du fichier multimédia dans le paramètre. Plus d’informations sont disponibles sur Make Core.

De plus, 4.3 a introduit le WP_Customize_Cropped_Image_Control, qui fournit une interface pour recadrer une image après l’avoir sélectionnée. Ceci est utile pour les cas où un rapport hauteur/largeur particulier est nécessaire.

Haut ↑

Les sections sont des conteneurs d’interface utilisateur pour les contrôles Customizer. Bien que vous puissiez ajouter des contrôles personnalisés aux sections principales, si vous disposez de plusieurs options, vous souhaiterez peut-être ajouter une ou plusieurs sections personnalisées. Utilisez le add_section méthode de l’objet WP_Customize_Manager pour ajouter une nouvelle section :

$wp_customize->add_section( 'custom_css', array(
  'title' => __( 'Custom CSS' ),
  'description' => __( 'Add custom CSS here' ),
  'panel' => '', // Not typically needed.
  'priority' => 160,
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
) );

Vous devez uniquement inclure les champs dont vous souhaitez remplacer les valeurs par défaut. Par exemple, la priorité par défaut (ordre d’apparition) est généralement acceptable, et la plupart des sections ne devraient pas nécessiter de texte descriptif si vos options sont explicites. Si vous souhaitez modifier l’emplacement de votre section personnalisée, les priorités des sections principales sont ci-dessous :

TitreidentifiantPriorité (Ordre)
Titre et slogan du sitetitle_tagline20
Couleurscouleurs40
Image d’en-têteheader_image60
Image de fondimage de fond80
Menus (Panneau)nav_menus100
Widgets (Panneau)widgets110
Page d’accueil statiquepage_frontale_statique120
défaut160
CSS supplémentaireCSS personnalisé200

Dans la plupart des cas, des sections peuvent être ajoutées avec seulement un ou deux paramètres spécifiés. Voici un exemple d’ajout d’une section pour les options relatives au pied de page d’un thème :

// Add a footer/copyright information section.
$wp_customize->add_section( 'footer' , array(
  'title' => __( 'Footer', 'themename' ),
  'priority' => 105, // Before Widgets.
) );

Haut ↑

L’API Customizer Panels a été introduite dans 4.0 et permet aux développeurs de créer une couche de hiérarchie supplémentaire au-delà des contrôles et des sections. Plus que de simplement regrouper des sections de contrôles, les panneaux sont conçus pour fournir des contextes distincts au personnalisateur, tels que la personnalisation de widgets, de menus ou peut-être à l’avenir, la modification de publications. Il existe une distinction technique importante entre les objets section et panneau.

Les thèmes ne doivent pas enregistrer leurs propres panneaux dans la plupart des cas. Les sections font ne pas doivent être imbriqués sous un panneau, et chaque section doit généralement contenir plusieurs contrôles. Des contrôles doivent également être ajoutés aux sections fournies par le noyau, comme l’ajout d’options de couleur à la section des couleurs. Assurez-vous également que vos options sont aussi rationalisées et efficaces que possible ; voir la philosophie . Les panneaux sont conçus comme des contextes pour des fonctionnalités entières telles que des widgets, des menus ou des publications, et non comme des wrappers pour des sections génériques. Si vous devez absolument utiliser Panels, vous constaterez que l’API est presque identique à celle des sections :

$wp_customize->add_panel( 'menus', array(
  'title' => __( 'Menus' ),
  'description' => $description, // Include html tags such as 

. 'priority' => 160, // Mixed with top-level-section hierarchy. ) ); $wp_customize->add_section( $section_id , array( 'title' => $menu->name, 'panel' => 'menus', ) );

Les panneaux doivent contenir au moins une section, qui doit contenir au moins un contrôle, pour être affichés. Comme vous pouvez le voir dans l’exemple ci-dessus, les sections peuvent être ajoutées aux panneaux de la même manière que les contrôles sont ajoutés aux sections. Cependant, contrairement aux contrôles, si le paramètre Panel est vide lors de l’enregistrement d’une section, il sera affiché dans le contexte de personnalisation de niveau supérieur, car la plupart des sections ne doivent pas être contenues dans un panneau.

Haut ↑

Les contrôles, sections et panneaux personnalisés peuvent être facilement créés en sous-classant les objets PHP associés à chaque objet Customizer : WP_Customize_Control, WP_Customize_Section, et WP_Customize_Panel (cela peut aussi être fait pour WP_Customize_Setting, mais les paramètres personnalisés sont généralement mieux mis en œuvre à l’aide de types de paramètres personnalisés, comme indiqué dans la section suivante). Voici un exemple de contrôle personnalisé de base :

class WP_New_Menu_Customize_Control extends WP_Customize_Control {
  public $type = 'new_menu';
  /**
  * Render the control's content.
  */
  public function render_content() {
  ?>
    
  

En sous-classant la classe de contrôle de base, vous pouvez remplacer n'importe quelle fonctionnalité par une fonctionnalité personnalisée ou utiliser la fonctionnalité principale en fonction de vos besoins. La fonction la plus courante à remplacer est render_content() car il vous permet de créer une interface utilisateur personnalisée à partir de zéro avec HTML. Cependant, les contrôles personnalisés doivent être utilisés avec prudence, car ils peuvent introduire une interface utilisateur incompatible avec l'interface utilisateur principale environnante et causer de la confusion pour les utilisateurs. Les objets Custom Customizer peuvent être ajoutés de la même manière que les contrôles, sections et panneaux par défaut sont ajoutés :

$wp_customize->add_control(
  new WP_Customize_Color_Control(
    $wp_customize, // WP_Customize_Manager
    'accent_color', // Setting id
    array( // Args, including any custom ones.
      'label' => __( 'Accent Color' ),
      'section' => 'colors',
    )
  )
);

Les paramètres transmis lors de l'ajout de contrôles sont mappés sur des variables de classe au sein de la classe de contrôle, vous pouvez donc en ajouter et en utiliser des personnalisés lorsque certaines parties de votre objet personnalisé sont différentes selon les différentes instances.

Lors de la création de contrôles, de sections ou de panneaux personnalisés, il est fortement recommandé de référencer le code principal afin de bien comprendre les fonctionnalités disponibles qui peuvent être remplacées. Core inclut également des exemples d'objets personnalisés de chaque type. Cela peut être trouvé dans wp-includes/class-wp-customize-control.php, wp-includes/class-wp-customize-section.php et wp-includes/class-wp-customize-panel.php. Il existe également une API JavaScript pour chaque type d'objet Customizer, qui peut être étendue avec des objets personnalisés ; voir la section API JavaScript Customizer pour plus de détails.

Haut ↑

Normes d'interface utilisateur du personnalisateur Normes d'interface utilisateur du personnalisateur

Les contrôles, sections et panneaux de personnalisation personnalisés doivent, dans la mesure du possible, correspondre aux pratiques de base de l'interface utilisateur. Cela inclut de s'appuyer sur les normes de wp-admin, telles que l'utilisation du .button et .button-primary cours, par exemple. Il existe également quelques normes spécifiques au personnalisateur (à partir de 4.7).

  • Les couleurs de fond blanches sont utilisées seul pour indiquer la navigation et les éléments exploitables (tels que les entrées)
  • Le général #eee la couleur d'arrière-plan offre un contraste visuel avec les éléments blancs
  • 1px #ddd les bordures séparent les éléments de navigation des marges d'arrière-plan et les uns des autres
  • 15px d'espacement est prévu entre les éléments où la séparation visuelle est souhaitée
  • 4px les bordures sont utilisées sur un côté d'un élément de navigation pour afficher le survol ou le focus, avec une couleur de #0073aa
  • Utilisations du texte de personnalisation color: #555d66, avec #0073aa pour les états de survol et de focus sur les éléments de navigation

Haut ↑

Par défaut, le Customizer prend en charge l'enregistrement des paramètres en tant qu'options ou modifications de thème. Mais ce comportement peut être facilement écrasé pour enregistrer et prévisualiser manuellement les paramètres en dehors de la table wp_options de la base de données , ou pour appliquer une autre gestion personnalisée. Pour commencer, spécifiez un type autre que option ou theme_mod lors de l'ajout de votre paramètre (vous pouvez utiliser à peu près n'importe quelle chaîne) :

$wp_customize->add_setting( $nav_menu_setting_id, array(
  'type' => 'nav_menu',
  'default' => $item_ids,
) );

Le paramètre ne sera plus enregistré ou prévisualisé lorsque sa valeur est modifiée dans le contrôle associé. Maintenant, vous pouvez utiliser le customize_update_$setting->type et customize_preview_$setting->type actions pour mettre en œuvre des fonctionnalités d'enregistrement et de prévisualisation personnalisées. Voici un exemple d'enregistrement de la propriété order d'un élément de menu à partir du projet Menu Customizer (la valeur du paramètre est un tableau ordonné d'ID de menu) :

function menu_customizer_update_nav_menu( $value, $setting ) {
  $menu_id = str_replace( 'nav_menu_', '', $setting->id );
  // ...
  $i = 0;
  foreach( $value as $item_id ) { // $value is ordered array of item ids.
    menu_customizer_update_menu_item_order( $menu_id, $item_id, $i );
  $i++;
  }
}
add_action( 'customize_update_nav_menu', 'menu_customizer_update_nav_menu', 10, 2 );

Et voici comment le même plugin implémente la prévisualisation des éléments du menu de navigation (notez que cet exemple nécessite PHP 5.3 ou supérieur) :

function menu_customizer_preview_nav_menu( $setting ) {
  $menu_id = str_replace( 'nav_menu_', '', $setting->id );
  add_filter( 'wp_get_nav_menu_items', function( $items, $menu, $args ) use ( $menu_id, $setting ) {
    $preview_menu_id = $menu->term_id;
    if ( $menu_id == $preview_menu_id ) {
      $new_ids = $setting->post_value();
      foreach ( $new_ids as $item_id ) {
        $item = wp_setup_nav_menu_item( $item );
        $item->menu_order = $i;
        $new_items[] = $item;
        $i++;
      }
      return $new_items;
    } else {
      return $items;
    }
  }, 10, 3 );
}
add_action( 'customize_preview_nav_menu', 'menu_customizer_preview_nav_menu', 10, 2 );

[*]

All the CMS Templates You Could Ask For.

WordPress: Objets de personnalisation | Manuel du développeur de thème

2M+ items from the worlds largest marketplace for CMS TemplatesEnvato Market.


[*]
WordPress: Objets de personnalisation | Manuel du développeur de thème
[*]#Objets #personnalisation #Manuel #développeur #thème