Manual de WordPress: Crear un plugin

Un plugin de WordPress es un programa escrito en PHP que añade una serie de características al blog y que utiliza los métodos y puntos de acceso que proporciona la API (Application Program Interface) de WordPress para integrarse en la plataforma.

Veamos el plugin más sencillo, "Hello World 1.0", que consta de dos archivos:
- helloworld.php
- readme.txt
ubicados en el directorio:
wp-content/plugins/helloworld/

1. helloworld.php

   Incluye seis secciones:

   • Información del plugin: aparecerá en el panel de administración de plugins.

     <?php
     /*
     Plugin Name: Hello World
     Plugin URI: https://www.estrellateyarde.org/discover/
         manual-de-wordpress-como-crear-un-plugin
     Description: Hello World es un plugin de ejemplo que imprime un saludo.
         Incluye shortcode. Ha sido programado exclusivamente con fines
         didacticos.
     Version: 1.0
     Author: crash-n-burn
     Author URI: https://www.estrellateyarde.org
     */
     ?>

   • Licencia

     <?php
     /*
     Copyright 2009  crash-n-burn  (email: [email protected])
      
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
      
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
      
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
     */
     ?>

   • Función que se ejecuta al activar el plugin

     Usaremos las dos posibilidades de que disponemos en WordPress para almacenar datos: crear nuestra propia tabla y usar options.

     <?php
     // registrar la funcion que se ejecuta al activar el plugin
     register_activation_hook(__FILE__, 'helloworld_activate');
      
     // funcion que se ejecuta al activar el plugin
     function helloworld_activate() {
         // crear la tabla del plugin e insertar dos registros
         global $wpdb;
         $table_name= $wpdb->prefix."helloworld";
      
         $sql = "CREATE TABLE $table_name (
             `id` mediumint( 9 ) NOT NULL auto_increment,
             `type` tinytext NOT NULL,
             `saludo` tinytext NOT NULL,
             PRIMARY KEY  (`id`)
             )";
         $wpdb->query($sql);
      
         $sql = "INSERT INTO $table_name (`id`, `type`, `saludo`)
             VALUES (1, 'default', 'Hello World')";
         $wpdb->query($sql);
      
         $sql = "INSERT INTO $table_name (`id`, `type`, `saludo`)
             VALUES (2, 'custom', 'Hola Mundo')";
         $wpdb->query($sql);
      
         // añadir la option del plugin
         add_option('helloworld_saludo_type', 'default');
     }
     ?>

   • Función que se ejecuta al desactivar el plugin

     <?php
     // registrar la funcion que se ejecuta al desactivar el plugin
     register_deactivation_hook(__FILE__, 'helloworld_deactivate');
      
     // funcion que se ejecuta al desactivar el plugin
     function helloworld_deactivate() {
         // borrar la tabla del plugin
         global $wpdb;
         $table_name = $wpdb->prefix."helloworld";
      
         $sql = "DROP TABLE $table_name";
         $wpdb->query($sql);
      
         // borrar la option del plugin
         delete_option('helloworld_saludo_type');
     }
     ?>

   • Item en el panel de administración con las opciones del plugin

     <?php
     // crear un item en el panel de administracion
     add_action('admin_menu', 'helloworld_menu');
      
     // crear la pagina de opciones del plugin
     function helloworld_menu() {
         add_options_page('Hello World plugin options', 'Hello World', 8,
             basename(__FILE__), 'helloworld_options');
     }
      
     // funcion que muestra la pagina de opciones del plugin
     function helloworld_options() {
         // comprobar si la peticion procede del form
         global $wpdb;
         $table_name = $wpdb->prefix."helloworld";
         if (isset($_POST['saludo_custom_new'])
             && !empty($_POST['saludo_custom_new'])) {
             $sql = "UPDATE $table_name
                 SET saludo ='{$_POST['saludo_custom_new']}'
                 WHERE type='custom'";
             $wpdb->query($sql);
         }
         if (isset($_POST['saludo_type'])) {
             update_option('helloworld_saludo_type', $_POST['saludo_type']);
         }
      
         // mostrar la pagina de opciones
         $saludo_default = $wpdb->get_var("SELECT saludo
             FROM $table_name
             WHERE type='default'" );
         $saludo_custom = $wpdb->get_var("SELECT saludo
             FROM $table_name
             WHERE type='custom'" );
         $saludo_type = get_option('helloworld_saludo_type');
         if ($saludo_type == "default") {
             $checked_default = "checked";
             $checked_custom = "";
         } else {
             $checked_default = "";
             $checked_custom = "checked";
         }
         echo "<div class='wrap'>\n";
         echo "<h2>Hello World plugin options</h2>\n";
         echo "<form method='post' action=''>\n";
         echo "Display:<br />\n";
         echo "<input type='radio' name='saludo_type' value='default'
             ".$checked_default." /> Message default
             (<b>".$saludo_default."</b>)<br />\n";
         echo "<input type='radio' name='saludo_type' value='custom'
             ".$checked_custom." /> Message custom
             (<b>".$saludo_custom."</b>)<br />\n";
         echo "New Message custom: <input type='text'
             name='saludo_custom_new' /><br />\n";
         echo "<input type='submit' name='update' value='Update' />\n";
         echo "</form>\n";
         echo "</div>\n";
     }
     ?>

     Ésta será la página de opciones del plugin:

     

   • Función del plugin para usar en PHP

     <?php
     // funcion del plugin para usar en PHP, devuelve un string
     function helloworld() {
         // recuperar el saludo
         global $wpdb;
         $table_name = $wpdb->prefix."helloworld";
         $saludo_type = get_option('helloworld_saludo_type');
         $saludo = $wpdb->get_var("SELECT saludo
            FROM $table_name
            WHERE type='$saludo_type'" );
      
         // output del plugin
         return "<p>".$saludo."</p>\n";
     }
     ?>

     Para utilizar el plugin en nuestro código incluiremos la función helloworld() en cualquier template:

     <?php echo helloworld(); ?>

   • Shortcode del plugin para usar en los post

     El sistema shortcode nos permite definir tags que pueden ser usados en nuestros posts, siendo reemplazados por el código generado por el script PHP asociado.

     Recursos

     • Ayuda de WordPress: Shortcode API

     El valor devuelto por return se inserta en el post en lugar del shortcode. No se debe usar echo sino return:

     <?php
     // registrar la funcion que se ejecuta al llamar al shortcode
     add_shortcode('helloworld', 'helloworld_shortcode');
      
     // shortcode del plugin para usar en los post
     function helloworld_shortcode($atts) {
         // el valor devuelto por return se inserta en el post en lugar
         // del shortcode. No se debe usar echo sino return
         return helloworld();
     }
     ?>

     Para utilizar el shortcode en nuestros post incluiremos la etiqueta:

     [helloworld]

2. readme.txt

   README del plugin en el formato estándar de WordPress. Incluye secciones como Description, Installation, FAQs, etc.

   Recursos

   • Ayuda de WordPress: readme.txt
   • Ayuda de WordPress: readme.txt validator

   El contenido de readme.txt será:

   === Hello World ===
   Contributors: crash-n-burn
   Donate link: https://www.estrellateyarde.org/discover/
       manual-de-wordpress-como-crear-un-plugin
   Tags: message, shortcode, i18n
   Requires at least: 2.7
   Tested up to: 2.8
   Stable tag: 1.0
    
   Hello World es un plugin que imprime un saludo. Incluye shortcode.
    
   == Description ==
    
   Hello World es un plugin que imprime un saludo. Incluye shortcode.
   Ha sido programado exclusivamente con fines didacticos.
    
   Caracteristicas:
   * Pagina de opciones.
   * Shortcode.
    
   == Installation ==
    
   1. Upload la carpeta /helloworld al directorio /wp-content/plugins
   2. Activar el plugin en el menu Plugins de WordPress.
   3. Configurar desde la pagina de opciones.
   4. Utilizar <?php echo helloworld(); ?> en PHP.
   5. Utilizar [helloworld] en los post.
    
   == Frequently Asked Questions ==
    
   = Se puede modificar el saludo personalizado? =
    
   Si, el saludo personalizado se puede modificar.
    
   = Se puede modificar el saludo por defecto? =
    
   No, el saludo por defecto no se puede modificar.
    
   == Screenshots ==
    
   1. Screenshot pagina de opciones del plugin.
    
   == Changelog ==
    
   = 1.0 =
   * Shortcode.
   * Pagina de opciones.
    
   == Credits ==
    
   Copyright 2009  crash-n-burn  (email: [email protected])
    
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.
    
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
    
   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

   El WordPress readme.txt validator nos dirá si nuestro readme.txt es correcto: