Exemple concret & complet d’implémentation d’une extension WordPress

Nov 23	Exemple concret & complet d’implémentation d’une extension WordPress Développement, PHP, Web Ajouter un commentaire
	http://codex.wordpress.org/

Commençons par le plus simple, dans le fichier JavaScript, j’ajoute le code suivant qui va permettre d’afficher ou de masquer un élément HTML (une aide contextuelle dans la page des options que nous créerons ensuite) :

1
2
3
4
5
6
7
8

// To show/hide an additional help
function switchVisibility(eltId) {
var elt = document.getElementById(eltId);
if(elt.style.display == 'block')
elt.style.display = 'none';
else
elt.style.display = 'block';
}

Puis le code PHP, dans son intégralité et incluant de très nombreux commentaires afin de détailler la raison de la présence de telle ou telle ligne :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198

<?php
/*
Plugin Name: Random Number Generator
Plugin URI: https://blogs.wittwer.fr/whiler/
Description: Generates a random number (for instance, useful to avoid browsers links cache)
Version: 0.0.1
Author: Whiler
Author URI: https://william.wittwer.fr/
*/

// Interdit les appels directs à la page
if (!function_exists("get_option")) {
echo 'SIG'; // Silence is golden
die;
}

// Clé utilisée pour le tag à détecter dans les articles/pages/commentaires [random-number] (not a constant... users can maybe update it in a future release)
$random_number_generator_key = 'random-number';

// Charge le fichier de traduction s'il existe
load_plugin_textdomain('random_number_generator', '', '/random_number_generator/languages');

/**
* Fonction qui récupère et valide les paramètres avant de les renvoyer par référence
* @param integer &$random_number_generator_from Valeur minimale
* @param integer &$random_number_generator_to Valeur maximale
* @param string &$random_number_generator_format Format utilisé pour l'affichage
*/
function get_data(&$random_number_generator_from, &$random_number_generator_to, &$random_number_generator_format) {
// Récupération des paramètres depuis les options de WP
$random_number_generator_from = get_option('random_number_generator_from');
$random_number_generator_to = get_option('random_number_generator_to');
$random_number_generator_format = get_option('random_number_generator_format');
// Validation de la cohérence des valeurs
if (($random_number_generator_from == $random_number_generator_to) || ($random_number_generator_from > $random_number_generator_to)) {
$random_number_generator_from = 0;
$random_number_generator_to = mt_getrandmax();
}
if (($random_number_generator_format == null) || (trim($random_number_generator_format) == '')) {
$random_number_generator_format = "%x";
}
}

/**
* Fonction appelée à l'activation de l'extension
*/
function random_number_generator_install() {
// Ajout des valeurs par défaut
add_option('random_number_generator_from', 0);
add_option('random_number_generator_to', mt_getrandmax());
add_option('random_number_generator_format', "%x");
}

/**
* Fonction affichant la page de réglage des options
*/
function random_number_generator_optionsPage() {
get_data($random_number_generator_from, $random_number_generator_to, $random_number_generator_format);
?>
<div class="wrap">
<h2><?php /*Tr.: Settings page title / %s: Plugin name*/ printf(str_replace('%s', '<strong>%s</strong>', __('%s Options', 'random_number_generator')), 'Random Number Generator'); ?></h2>
<form method="post" action="options.php">
<?php wp_nonce_field('update-options'); ?>
<table class="form-table">
<tr valign="top">
<th colspan="2" scope="row">
<?php global $random_number_generator_key; printf(__('Simply replace the tag %s by a random number.', 'random_number_generator'), "<code>[$random_number_generator_key]</code>"); ?><br/>
<span class="description"><?php printf(__('Used to avoid browsers cache by inserting a random number. For instance, %1$s generates %2$s.', 'random_number_generator'), "<code><a href="https://".__('my_url', 'random_number_generator')."?[$random_number_generator_key]"></code>", "<code><a href="https://".__('my_url', 'random_number_generator')."?".random_number_generator_shortcode_handler().""></code>"); ?></span>
</th>
</tr>
<tr valign="top">
<th scope="row" style="text-align: right;">
<?php _e('From:', 'random_number_generator') ?>
</th>
<td>
<input type="text" name="random_number_generator_from" value="<?php echo $random_number_generator_from; ?>" />
<a class="button" title="<?php _e('Dispay more details', 'random_number_generator') ?>" onclick="javascript:switchVisibility('random_number_generator_from_help');"><?php /*Tr.: Button caption for help*/ _e('?', 'random_number_generator'); ?></a>
<span id="random_number_generator_from_help" style="text-align: left; display: none;"> <?php printf(__('Lowest integer value to be returned (default: <code>%d</code>).', 'random_number_generator'), 0); ?></span>
</td>
</tr>
<tr valign="top">
<th scope="row" style="text-align: right;">
<?php _e('To:', 'random_number_generator'); ?>
</th>
<td>
<input type="text" name="random_number_generator_to" value="<?php echo $random_number_generator_to; ?>" />
<a class="button" title="<?php _e('Dispay more details', 'random_number_generator') ?>" onclick="javascript:switchVisibility('random_number_generator_to_help');"><?php _e('?', 'random_number_generator'); ?></a>
<span id="random_number_generator_to_help" style="text-align: left; display: none;"> <?php printf(__('Highest integer value to be returned (default: <code>%d</code>).', 'random_number_generator'), mt_getrandmax()); ?></span>
</td>
</tr>
<tr valign="top">
<th scope="row" style="text-align: right;">
<?php _e('Format:', 'random_number_generator') ?>
</th>
<td>
<input type="text" name="random_number_generator_format" value="<?php echo $random_number_generator_format; ?>" />
<a class="button" title="<?php _e('Dispay more details', 'random_number_generator') ?>" onclick="javascript:switchVisibility('random_number_generator_format_help');"><?php _e('?', 'random_number_generator'); ?></a>
<span id="random_number_generator_format_help" style="text-align: left; display: none;"> <?php printf(__('Random number produced according to the formatting string above (default: <code>%s</code>).', 'random_number_generator'), '%x'); ?><br/>
<?php printf(__('See %s documentation for a description of format.', 'random_number_generator'), '<a href="'.__('https://www.php.net/manual/en/function.sprintf.php', 'random_number_generator').'" target"_blank" title="'.__('Visit PHP: sprintf - Manual page', 'random_number_generator').'">sprintf()</a>'); ?></span>
</td>
</tr>
</table>
<input type="hidden" name="action" value="update" />
<input type="hidden" name="page_options" value="random_number_generator_from,random_number_generator_to,random_number_generator_format" />
<?php settings_fields( 'random_number_generator' ); ?>
<p class="submit">
<input type="submit" class="button-primary" value="<?php _e('Save Changes', 'random_number_generator') ?>" />
</p>
</form>
</div>
<?php
}

/**
* Fonction ajoutant un lien pour la page des options dans la liste des extensions
* @param string $links Lien en cours
* @param string $file Extension en cours
* @return HTML
*/
function random_number_generator_plugin_action_links($links, $file) {
if ($file == plugin_basename(dirname(__FILE__).'/random_number_generator.php')){
//Le commentaire ci-dessous est extrait par Poedit pour être mis dans les commentaires afin d'aider à la traduction
//Tr.: Below the plugin name, in the plugin page
$settings_link = "<a href='options-general.php?page=random_number_generator/random_number_generator.php'>".__('Settings','random_number_generator')."</a>";
array_unshift( $links, $settings_link );
}
return $links;
}

/**
* Fonction ajoutant les scripts nécessaires dans les réglages de l'extension
*/
function random_number_generator_scripts() {
wp_enqueue_script('random_number_generator_script1', WP_PLUGIN_URL.'/'.str_replace(".php",".js",plugin_basename(__FILE__)));
// wp_enqueue_script('random_number_generator_script2', 'my2ndScript', array('jquery', 'jquery-ui-tabs'));
}

/**
* Fonction ajoutant un lien dans le menu Réglages pour la page des options de l'extension
*/
function random_number_generator_settings_menu() {
if (function_exists('add_submenu_page')) {
//Tr.: Settings menu plugin caption
$random_number_generator_settings_page = add_submenu_page('options-general.php',__('Rand#Gen.','random_number_generator'), __('Rand#Gen.','random_number_generator'), "install_plugins", __FILE__, 'random_number_generator_optionsPage');
// Ajoute les scripts JavaScript utilisés par les pages d'administration de l'extension
add_action( "admin_print_scripts-$random_number_generator_settings_page", 'random_number_generator_scripts' );
}
}

/**
* Fonction qui répertorie les paramètres de l'extension et les méthodes de callback(validation)
*/
function register_random_number_generator_settings() { // whitelist options
register_setting( 'random_number_generator', 'random_number_generator_from', 'intval' ); // Valeur entière uniquement
register_setting( 'random_number_generator', 'random_number_generator_to', 'intval' );
register_setting( 'random_number_generator', 'random_number_generator_format', 'wp_filter_nohtml_kses' ); // HTML interdit
}

/**
* Fonction renvoyant un chiffre aléatoire
* @return HTML
*/
function random_number_generator_shortcode_handler() {
// $atts ::= array of attributes
// $content ::= text within enclosing form of shortcode element
// $code ::= the shortcode found, when == callback name
// examples: [my-shortcode]
// [my-shortcode/]
// [my-shortcode foo='bar']
// [my-shortcode foo='bar'/]
// [my-shortcode]content[/my-shortcode]
// [my-shortcode foo='bar']content[/my-shortcode]

// Récupère les différentes options
get_data($random_number_generator_from, $random_number_generator_to, $random_number_generator_format);
// Génération aléatoire
mt_srand();
// Renvoie un nombre aléatoire
return sprintf($random_number_generator_format, mt_rand($random_number_generator_from, $random_number_generator_to));
}

// Ajout du hook pour détecter/remplacer le mot-clé lorsqu'il est utilisé
add_shortcode($random_number_generator_key, 'random_number_generator_shortcode_handler');

// Si on est administrateur
if (is_admin()) {
// Méthode à appeler lors de l'activation de l'extension
register_activation_hook(__FILE__, "random_number_generator_install");
// Méthode à appeler lors de la génération du menu d'admin
add_action('admin_menu', 'random_number_generator_settings_menu');
// Méthode à appeler lors de l'accès à l'administration
add_action('admin_init', 'register_random_number_generator_settings' );
// Méthode à appeler lors de l'affichage des liens d'action sur la page des extensions installées
add_filter('plugin_action_links', 'random_number_generator_plugin_action_links', 10, 2);
}

?>

Si certaines parties restent floues, n’hésitez pas à laisser un commentaire et j’essayerai de vous répondre…

Une fois le tout sauvegardé, on peut aller dans l’interface d’administration de WordPress afin d’activer notre extension qui devrait apparaitre dans la liste :

Nouvelle extension désactivée

On clique alors sur le lien pour l’activer afin d’obtenir ceci :

Nouvelle extension activée

On peut ensuite alors, au choix, allez la tester en ajoutant la balise dans un article, [random-number], pour constater le résultat obtenu (par exemple, 34d1ed6b), ou naviguer dans les pages d’administration pour voir le nouveau menu, dans Réglages, ou cliquer sur l’action Settings présente après l’activation de l’extension.

Si l’on n’a commis aucune erreur, tout devrait normalement fonctionner. Si une erreur a été commise et empêche la compilation du script, l’activation échouera en indiquant un message d’erreur.