Comment créer une page de paramètres dans WordPress

Si vous créez un plugin WordPress, vous vous demandez peut-être comment créer une page de paramètres pour celui-ci. WordPress propose-t-il une sorte de mécanisme « standard » pour cela ? Existe-t-il de nouveaux outils ou cadres avec lesquels créer des pages de paramètres modernes ? Est-ce une bonne idée de créer une page de paramètres ? Eh bien, aujourd'hui, nous allons parler de tout cela et je vais répondre à vos questions.

Des décisions, pas des options

WordPress est une plateforme qui vise à démocratiser le web. Cette déclaration, qui sonne très bien mais qui est en même temps très abstraite, est une façon de dire « nous voulons que tout le monde puisse utiliser WordPress ». Et, croyez-le ou non, les pages de paramètres peuvent être, et sont en fait dans de nombreux cas, un obstacle à cela. Vous ne me croyez pas ? Eh bien, WordPress lui-même le dit :

Lors de la prise de décisions, ce sont les utilisateurs que nous considérons en premier. Un bon exemple de cette considération est les options logicielles. Chaque fois que vous donnez une option à un utilisateur, vous lui demandez de prendre une décision. Lorsqu'un utilisateur ne se soucie pas ou ne comprend pas l'option, cela conduit finalement à la frustration. En tant que développeurs, nous pensons parfois que fournir des options pour tout est une bonne chose, vous ne pouvez jamais avoir trop de choix, n'est-ce pas ? En fin de compte, ces choix finissent par être des choix techniques, des choix qui n'intéressent pas l'utilisateur final moyen. Il est de notre devoir en tant que développeurs de prendre des décisions de conception intelligentes et d'éviter de faire peser le poids des choix techniques sur nos utilisateurs finaux.

Philosophie WordPress

Donc, avant de créer une page de paramètres, réfléchissez bien aux options que vous voulez donner à vos utilisateurs, pourquoi vous voulez qu'ils aient accès à ces options et s'il est nécessaire ou utile de le faire.

Filtres comme alternative

Même si je sais que je ne suis pas censé offrir trop d'options à mes utilisateurs, je dois avouer qu'en tant que développeur, ce n'est pas toujours facile pour moi de prendre une décision au lieu d'offrir une option. Il y a des moments où je veux que mes utilisateurs aient la possibilité de choisir , bien que je sois conscient que les options que j'expose sont complexes. Alors que dois-je faire dans ces cas ? Est-ce que je suis les recommandations de WordPress et que je limite mes utilisateurs avancés ?

Heureusement, WordPress offre une solution parfaite à ce dilemme : les filtres . Lorsque vous concevez un plugin et que vous souhaitez que vos utilisateurs (avancés) puissent ajuster son comportement, ne créez pas de page de paramètres ou quelque chose comme ça. Au lieu de cela, rendez votre plugin personnalisable grâce au mécanisme de filtrage de WordPress.

Si vous utilisez des filtres, la plupart de vos utilisateurs bénéficieront d'un comportement par défaut ("décisions", souvenez-vous ?), car ils utiliseront le plug-in avec les valeurs par défaut définies dans vos filtres, tandis que les utilisateurs avancés auront la possibilité de les modifier. décisions via des crochets (et donc vous avez aussi des "options"). Le meilleur des deux mondes!

Paramètres WordPress

Ok, maintenant que nous sommes conscients de l'importance de prendre des décisions pour nos utilisateurs et que nous avons vu comment contourner cette limitation (si nécessaire) grâce à des filtres, il est temps de voir comment nous pouvons créer une page de paramètres dans WordPress. Parce que oui : il y a des moments où nous devons vraiment donner à nos utilisateurs la possibilité de prendre des décisions en fonction de leurs préférences.

API de paramètres dans WordPress

L'API Paramètres a été ajoutée dans WordPress version 2.7. Il s'agit d'un ensemble de fonctions qui standardisent la création de pages de paramètres, vous permettant de définir quelles options sont disponibles, quelle sera l'interface utilisateur pour éditer chacune de ces options (essentiellement, les champs d'un formulaire), et comment valider, enregistrer , et récupérer leurs valeurs.

Je pense que la meilleure façon d'apprendre est à travers des exemples, alors créons notre première page de paramètres en utilisant l'API de paramètres étape par étape.

Création d'une nouvelle page de paramètres

La première chose que vous devez faire pour créer une page de paramètres est (surprise, surprise !) de créer une page pour afficher les paramètres. Pour cela, utilisez simplement la fonction add_options_page lors de l'action admin_menu et enregistrez la page :

 function nelio_add_settings_page() { add_options_page( 'Nelio Plugin Settings', 'Nelio', 'manage_options', 'nelio-example-plugin', 'nelio_render_settings_page' ); } add_action( 'admin_menu', 'nelio_add_settings_page' );

Comme vous pouvez le voir, la seule chose que nous faisons avec cette fonction est d'enregistrer une nouvelle page qui apparaîtra sous le menu Paramètres de WordPress, avec son titre, le nom dans le menu, les autorisations que l'utilisateur doit avoir pour pouvoir y accéder , et sur. Le dernier argument, nelio_render_settings_page , est le nom de la fonction qui sera en charge du rendu de ladite page :

 <?php function nelio_render_settings_page() { ?> <h2>Nelio Plugin Settings</h2> <form action="options.php" method="post"> <?php settings_fields( 'nelio_example_plugin_settings' ); do_settings_sections( 'nelio_example_plugin' ); ?> <input type="submit" name="submit" class="button button-primary" value="<?php esc_attr_e( 'Save' ); ?>" /> </form> <?php }

La page des paramètres elle-même est relativement facile à créer. Il suffit d'ajouter un form dont le contenu sera généré semi-automatiquement par WordPress. D'une part, nous invoquons la fonction settings_fields , qui ajoute essentiellement un nonce dans le formulaire pour le rendre "sûr". Ensuite, nous demandons à WordPress de rendre tous les paramètres que nous avons créés pour notre plugin en utilisant la fonction do_settings_sections . Et, enfin, nous ajoutons simplement le bouton pour soumettre le formulaire.

Paramètres réels dans notre page Paramètres

Ensuite, nous devons enregistrer chacune des options qui feront partie de notre page de paramètres. Pour ce faire, nous allons utiliser deux fonctions : register_setting , qui nous permet d'indiquer le nom avec lequel nous allons enregistrer les paramètres dans la base de données, et add_settings_field , qui ajoute chaque option individuelle :

 function nelio_register_settings() { register_setting( 'nelio_example_plugin_settings', 'nelio_example_plugin_settings', 'nelio_validate_example_plugin_settings' ); add_settings_section( 'section_one', 'Section One', 'nelio_section_one_text', 'nelio_example_plugin' ); add_settings_field( 'some_text_field', 'Some Text Field', 'nelio_render_some_text_field', 'nelio_example_plugin', 'section_one' ); add_settings_field( 'another_number_field', 'Another Number Field', 'nelio_render_another_number_field', 'nelio_example_plugin', 'section_one' ); } add_action( 'admin_init', 'nelio_register_settings' );

L'extrait de code précédent contient quelques éléments qui méritent une attention particulière. D'une part, notez que la fonction register_setting a comme troisième argument : nelio_validate_example_plugin_settings . Il s'agit du nom de la fonction de rappel qui sera appelée pour valider les valeurs que l'utilisateur a sélectionnées (rappelez-vous que vous devez toujours valider et assainir vos champs de formulaire). Cette fonction ressemble à ceci :

 function nelio_validate_example_plugin_settings( $input ) { $output['some_text_field'] = sanitize_text_field( $input['some_text_field'] ); $output['another_number_field'] = absint( $input['another_number_field'] ); // ... return $output; }

où nous récupérons chaque champ soumis à partir de $input et nous le désinfectons dans $output afin que nous sachions avec certitude que, quoi que nous finissions par enregistrer dans la base de données, est valide et correct.

La deuxième chose sur laquelle je voulais vous concentrer est le fait que chacun des champs que nous définissons inclut également une référence de fonction qui indique à WordPress comment chaque champ doit être rendu. Par exemple, les rappels des champs dans notre exemple pourraient ressembler à ceci :

 function nelio_section_one_text() { echo '<p>This is the first (and only) section in my settings.</p>'; } function nelio_render_some_text_field() { $options = get_option( 'nelio_example_plugin_settings' ); printf( '<input type="text" name="%s" value="%s" />', esc_attr( 'nelio_example_plugin_settings[some_text_field]' ), esc_attr( $options['some_text_field'] ) ); } function nelio_render_another_number_field() { $options = get_option( 'nelio_example_plugin_settings' ); printf( '<input type="number" name="%s" value="%s" />', esc_attr( 'nelio_example_plugin_settings[another_number_field]' ), esc_attr( $options['another_number_field'] ) ); }

Essentiellement, tous ces rappels ne font que récupérer la valeur actuelle du champ qu'ils sont censés afficher (avec get_option ) et afficher le code HTML qui permettra à l'utilisateur de définir une valeur ou l'autre (dans cet exemple, un champ d' input de tapez text ou un number ).

Quel est le résultat final, demandez-vous? Ce:

Dernières pensées

Comme vous pouvez le constater, la création d'une page de paramètres est relativement simple. Personnellement, je n'aime pas beaucoup l'ensemble du processus, car c'est assez répétitif et nous devons écrire encore et encore le même code passe-partout… mais c'est quand même facile.

Pour simplifier davantage ce processus, il existe cependant des générateurs de code en ligne avec lesquels, via une interface utilisateur simple, vous pouvez définir les différents champs que vous souhaitez sur votre page de paramètres. Voici quelques exemples :

• API de paramètres WP
• Générateur de pages d'options WordPress

Et, bien sûr, il y a toujours la possibilité de créer une page de paramètres en utilisant des technologies comme React… mais c'est une histoire d'une autre époque, vous ne pensez pas ?

Image sélectionnée par Rima Kruciene sur Unsplash.