Una guía simple para la API de etiquetas rápidas de WordPress

Spanish (Español) translation by Luis Chiabrera (you can also view the original English article)

Para la versión 4.0, existen 18 APIs integradas en WordPress. Todas son extremadamente importantes en diferentes aspectos de Wordpress, y juntas ellas ayudan a WordPress a ser el sistema de manejo de contenido mas flexible del mundo.

Una de estas APIs es la API de Etiquetas rápidas, la cual permite a desarrolladores de complementos y temas agregar botones al modo Texto ( usualmente llamado el modo HTML) del editor de WordPress. En este tutorial, vamos a aprender qué es la API de Etiquetas rápidas, y como usar la API para crear nuevos botones para el editor de HTML.

¿Qué es la API de etiquetas rápidas?

A pesar de que sirve para más, Wordpress es usualmente utilizado como un "sistema de manejo de contenido" y Wordpress tiene que dejar a los usuarios manejar el contenido de manera fácil y eficiente. Es por eso que Wordpress viene con TinyMCE, uno de los mejores editores WYSIWYG ( "Lo Que Ves Es Lo Que Tienes" en español) de todos los tiempos, e indiscutiblemente el editor más apropiado para WordPress. TinyMCE ofrece una sencilla experiencia a la hora de editar contenido para los usuarios, que simultáneamente muestra el contenido casi como una vista previa exacta a lo que ellos publicarán.

Pero algunos usuarios no les gusta ver eso. De hecho, algunos usuarios preferirían ver el código fuente del contenido para asi poder tener el control total sobre lo que ellos van a publicar. O tal vez el usuario estaría en el " Editor visual" y quiere chequear y verificar el código fuente. Ahí es cuando el "editor HTML" entra en juego. EL modo HTML del editor de WordPress muestra el código fuente del contenido, y nada más.

Existen botones en la parte superior del editor HTML, los cuales llamamos "botones de Etiqueras rápidas", y nos permiten editar el contenido sin tener que cambiarnos otra vez al editor Visual. Usando la API de Etiquetas rápidas, podemos crear nuevos botones en conjunto con los que ya existen.

Usando la API de Etiquetas rápidas

Usar la API de Etiquetas rápidas es muy sencillo porque, mientras que el archivo quicktags.js central tiene mucho mas, tenemos( y deberíamos) usar solo una función: QTags.addButton().

Si quieres pasar el script como un archivo separado(el cual es el uso recomendado), deberías usar el fragmento de código mostrado a continuación:

<?php

function load_my_quicktags() {

    // Load the `my-quicktags.js` file with the `QTags.addButton()` functions.
    wp_enqueue_script( 'my-quicktags', 'http://the.url/to/my-quicktags.js', array( 'quicktags' ) );

}

add_action( 'admin_enqueue_scripts', 'load_my_quicktags' );

?>

Pero si no tienes otra opción sino imprimir en línea, lo puedes hacer con el siguiente fragmento de código:

<?php

function load_my_quicktags_inline() {

    if ( wp_script_is( 'quicktags' ) ) { ?>
    
        <script>
        
            // The `QTags.addButton()` functions go here.
        
        </script>
    
    <?php }

}

add_action( 'admin_print_footer_scripts', 'load_my_quicktags_inline' );

?>

Muy fácil, ¿verdad? Date cuenta que usamos la acción admin_print_footer_scripts esta vez.

Parámetros de `QTags.addButton()`

La función QTags.addButton() tiene ocho parámetros:

QTags.addButton( 
    id, 
    display, 
    arg1, 
    arg2, 
    access_key, 
    title, 
    priority, 
    instance
);

id(cadena,requerido): Un ID único el cual va a ser el valor ID del HTML para el boton de Etiqueta Rápida. (Ten en mente que el valor del ID para cada botón sera precedido automáticamente con la cadena 'qt_content_'.)
display(cadena,requerido): Texto a mostrar en el botón.
arg1(cadena o función, requerido): Una etiqueta inicial a insertar, o el nombre de la función de retorno.
arg2(cadena,opcional): La etiqueta final a insertar de ser necesario.
access_key (cadena, opcional): Llave de acceso para el botón.
title (cadena, opcional): El valor HTML title para el botón.
priority (entero, opcional): El lugar donde tu botón irá—1 a 9 para el primer lugar, 11 a 19 para el segundo lugar, 21 a 29 para el tercer lugar, y así sucesivamente.
instance (cadena, opcional): Una instancia específica de Etiquetas rápidas para mostrar el botón solo allí, si hay mas de una instancia de Etiquetas rápidas en la página. (Si esto no está establecido, el botón sera agregado en todas las instancias.)

Uso básico: Creando botones simples

Las API de Etiquetas rápidas pueden parecer aterradoras y complicadas al principio (especialmente si tu conocimiento de JavaScript es débil como yo) pero como verás justo ahora, no hay nada de qué preocuparse acerca de escribir pequeños pedazos de código para crear botones de Etiquetas rápidas.

Empecemos con algo sencillo: Supón que vas a agregar dos botones de shortcode— un shortcode cerrado primero, y otro shortcode autocerrado después. Esto es lo que debes hacer:

QTags.addButton(
    'info-box', 
    'info box', 
    '[infobox]', 
    '[/infobox]'
);

Ves que fácil es esto? Todo lo que tienes que hacer es establecer un ID, un nombre de botón, y las cadenas a imprimir cuando se clickea el botón. También puedes no establecer el segundo argumento (cuarto parámetro) e imprimir el shorcode autocerrado.

QTags.addButton(
    'signature', 
    'signature', 
    '[signature]'
);

Eso es todo lo que se necesita saber acerca del uso básico de los botones de Etiqueta rápida!

Uso avanzado: Funciones de retorno activables

Por supuesto, no todos los botones de Etiqueta rápida son creados de igual manera. Puedes crear botones de Etiqueta rápida autocerrables y de cierre simple con facilidad, pero podrías necesitar un botón que pueda requerir un poco más de trabajo. Ahí es cuando las funciones JavaScript entran al juego.

Vamos a mostrar ejemplos sencillos de esto, pero está de parte de tu imaginación el crear botones de Etiqueta rápida complicados con funciones JavaScript.

Ahora, hagamos dos ejemplos rápidos. El primero es el clásico botón alert:

QTags.addButton(
    'alert', 
    'alert', 
    my_alert
);

function my_alert() {
    alert( 'Hello Quicktag!' );
}

Como puedes adivinar, muestra un mensaje de "Hello Quicktag!" Ahora hagamos algo con un mensaje:

QTags.addButton( 
    'my_prompt', 
    'alert', 
    my_prompt
);

function my_prompt() {
    var my_class = prompt( 'Enter a class name:', '' );
    
    if ( my_class ) {
        QTags.insertContent('<div class="' + my_class +'"></div>');
    }
}

Este es un poco complicado: Te pide escribir un nombre de clase, e imprime un div con la clase que especificaste.

Conclusión

Como dije antes, la API parece un poco intimidante. Pero como puedes ver, usarla es bien sencillo—incluso usándola para activar funciones de retorno. El modo HTML tiene usuarios muy dedicados, y apreciarían mucho que pusieras uno o dos botones cuando estas desarrollando un tema o un complemento.

¿Qué opinas sobre la API de Etiquetas rápidas? ¿Considerarías usarla, o tienes algo más que agregar a este tutorial? Dinos que piensas comentando debajo. Y si te gustó el artículo, no olvides compartirlo con tus amigos!