Estoy haciendo un pequeño tutorial de cómo me lo he montado para crear un plugin de WordPress: simterm. El plugin inserta un shortcode que nos permite simular una ventana de terminal (sea el SO que sea) y hacer como que se escriben cosas y el sistema nos da la respuesta. Es perfecto para nuestros tutoriales y si seguís este blog, seguro que lo habéis visto miles de veces.
Esta es la tercera parte, enfocada a recursos y shortcodes. Podéis acceder desde aquí a:
- Primera parte. Introducción y conceptos básicos de plugins de WordPress y algunas manías personales.
- Segunda parte. Enfocada a la pantalla de configuración de nuestro plugin.
Vayamos al grano.
Tabla de contenidos
Insertar recursos en la web
Cuando queremos insertar archivos JS y CSS dentro de una web hecha en WordPress, como para todo, tenemos dos formas:
- A pelo, es decir, insertando el código HTML:
. Aunque esto es muy feo y muy poco recomendable ya que puede romper la estructura del HTML resultante, resultar lento para el usuario y puede que las dependencias no se gestionen correctamente (¿cuántos archivos js dependen de que jQuery se haya cargado antes? y eso de esta forma no está garantizado)
- Utilizando funciones específicas de WordPress. Esta será la forma recomendada para que nada se rompa. Y la que contaré en este post
Insertar scripts
Aunque hay varios métodos para insertar recursos Javascript y CSS en una web hecha en WordPress, algunas formas muy complicadas. Aunque si no queremos complicarnos la vida podemos usar wp_enqueue_script(). Esta función introduce nuestro script en una cola que se podrá incluir en el <head> o justo antes de que acabe el </body&ft;. Permite además gestionar en cierto modo la versión del script que se utiliza. Eso será bueno ya que si nuestro servidor permite que el usuario guarde archivos en caché local (vamos, que el usuario se queda con los JS y los CSS para no tener que descargarlos cuando está navegando por nuestra web) lo va a utilizar de forma eficiente.
Sin más dilación, la forma en la que tenemos que utilizar esto sería:
1 | wp_enqueue_script($identificador, $src, $dependencias, $version, $footer); |
Es decir:
- $dentificador: Será un identificador único de nuestro script, ningún otro script que cargue este wordpress puede llamarse igual. Esto nos ayuda con la gestión de dependencias. Si por ejemplo el Javascript que incluimos es una biblioteca genérica (underscore, angular, plugins de jQuery, etc), podemos utilizar como identificador el nombre de esta biblioteca. Esto será bueno porque si varios plugins utilizan la biblioteca al mismo tiempo sólo se incluirá una vez, evitando conflictos. Por otro lado, si el archivo Javascript es nuestro, o muy específico del plugin podemos utilizar como nombre «nombreplugin-nombrescript» para garantizar que el nombre es único. En mi caso (que pondré más adelante, los identificadores se llaman «simterm-shoryourterms» y «simterm-launcher».
- $src: Es la URL del recurso que vamos a incluir. Es decir, el Javascript en cuestión. Esta ruta debería ser absoluta para evitar muchos problemas en el caso en el que el blog no esté en el directorio raíz del dominio. Por ejemplo, podríamos poner aquí: «/wp-content/plugins/simterm/js/simterm.js» perfectamente, y funcionaría en muchos sitios. Pero si nuestro blog lo colocamos en www.dominio.com/blog/ ya no funcionaría correctamente. Para ello podemos utilizar la función plugins_url() de la siguiente forma:1
2<?php
echo plugins_url('js/simterm.js', __FILE__);De esta forma, la función cogerá la URL correspondiente al fichero actual del plugin y le añadirá js/simterm.js; solucionando cualquier problema que pueda presentar la ruta en el futuro.
- $dependencias: Esto será un array con los identificadores de todos los scripts de los que dependa el javascript que estamos encolando. De esta forma, cuando se vaya a añadir definitivamente el script en la página, las dependencias se añadirán antes, incluso las dependencias de las dependencias… de esta forma evitamos este tipo de conflictos.
- $version: Una cadena de caracteres con la versión del script que vamos a añadir, false (o nada) si queremos coger la versión que tiene WordPress (si la tiene), o null si no queremos añadir versión.
- $footer: Es un booleano que, si vale false, añadiremos el script en la cabecera, y si vale true, lo añadiremos antes de cerrar body. También depende del momento en el que hagamos la inclusión del script, si ya tenemos la salida iniciada, es recomendable añadirlo en el footer.
Si por el contrario, sólo queremos que WordPress conozca la existencia del script, sin añadrlo atomáticamente y, si algún módulo lo incluye como dependencia se incluya automáticamente, podemos utilizar de la misma manera wp_register_script().
Insertar estilos CSS
Casi casi de la misma forma que insertamos Javascripts podemos insertar estilos, sólo que esta vez no se añaden en el footer, el último argumento de wp_enqueue_style() es $media, que especifica para qué dispositivo, orientación, o tamaño de pantalla está pensado este CSS. Por defecto ‘all’.
Ejemplo en simterm
En el plugin simterm, esto se ha hecho de la siguiente forma:
1 2 3 4 | wp_enqueue_script('simterm-showyourterms', plugins_url('js/show-your-terms.min.js',__FILE__), array(), '20160705', true); wp_enqueue_script('simterm-launcher', plugins_url('js/simterm.js',__FILE__), array('simterm-showyourterms'), '20160705', true); wp_enqueue_style('simterm-showyourtermscss', plugins_url('css/show-your-terms.min.css', __FILE__), array(), '20160705', 'all'); wp_enqueue_style('simterm-extracss', plugins_url('css/simterm.css', __FILE__), array(), '20160705', 'all'); |
Inserto dos JS y dos CSS, para mantener compatibilidad con el script original, inserto el JS y el CSS originales tal cual están en el repositorio (tengo mi propio fork en GitHub, con algunas modificaciones), por otro lado hay un JS y un CSS para adaptar a WordPress estos archivos (son un pequeño cambio, pero me gusta tenerlo todo separado).
Por otro lado, para los números de versión he utilizado la fecha en formato YYYYMMDD (añomesdía), y los scripts los he situado en directorios css/ y js/ dentro del mismo directorio del script.
Creación del shortcode
El funcionamiento del plugin será el siguiente. En medio de un post, escribimos:
[simterm]
$ comando
salida del comando
$ comando 2
Bienvenido al comando 2
> El comando 2 permite al usuario una entrada de texto adicional
El comando 2 proporciona una respuesta.
Fin del comando 2
[/simterm]
El shortcode será simterm. WordPress utiliza este tipo de códigos cortos que nos ayudan a escribir texto predefinido e insertar bloques predefinidos dentro de los posts (tal y como hago, por ejemplo para insertar bloques de código), o como hacen muchas webs para insertar un texto para enviar por Twitter directamente.
El shortcode del ejemplo anterior se traducirá por esto:
Lo primero es decirle a WordPress que vamos a insertar un shortcode. Esto lo hacemos así:
1 2 |
Donde el segundo argumento será el callback que se ejecutará cada vez que se encuentre este shortcode. El shortcode será simterm. El callback puede ser el nombre de una función como string o un array tipo (clase, función) como en el caso anterior. Esta línea, yo la he incluido en la inicialización del plugin, directamente en aquella función Init() que expliqué en la primera parte, pero perfectamente puede estar a pelo escrito en el PHP principal de tu plugin.
La función del shortcode tendrá una forma parecida a esta:
1 2 3 4 | function simterm_shortcode($atts, $content="") { return "Lo que queremos poner de vuelta"; } |
Si el shortcode tiene esta forma:
[[code atributo1=valor1 atributo2=valor2]contenido[/code]]
En $atts recibiremos los atributos y en $content recibiremos el contenido. Con esto ya tenemos lo suficiente para generar una salida en consecuencia que devolveremos en el return de la función. En mi caso, yo he decidido cargar aquí los JS y los CSS, para no incluir nada que no se necesite en la página del post. Además, como valor de retorno, he cargado una vista que se encargará de generar el código HTML necesario para representar el terminal. Podéis echarle un vistazo al código en GitHub. Ya que creé una clase aparte para procesar cada línea de entrada, y hay algunas cosas que poco tienen que ver con WordPress.
En este punto, consulto las opciones que tengo almacenadas por el plugin que modificarán el comportamiento.
En la práctica podemos incluir tantos shortcodes como queramos, el sistema de gestión de shortcodes es bastante eficiente y depende más del número de shortcodes que incluyamos en el post en cuestión que del número de shortcodes que podemos introducir. Aunque es muy recomendable que las funciones que procesan estos shortcodes estén lo más optimizadas posible y dependan lo menos posible de recursos externos ya que influirán en el tiempo de carga del post, y eso puede ser malo para nuestros usuarios.
Siguiente parte
Aunque con esto hay para hacer un plugin básico, todavía quedan algunos aspectos interesantes que podemos incluir, como por ejemplo la localización de nuestro plugin, para que los mensajes estén en el idioma del usuario. El post sale el 5 de septiembre.
Pingback: Cómo crear un plugin para WordPress. Making of de SimTerm: insertar recursos JS/CSS y shortcodes (tercera parte) | PlanetaLibre /
An impressive share! I’ve just forwarded this onto a friend who has been conducting a little homework on this.
And he in fact ordered me lunch because I stumbled upon it for him… lol. So allow me to reword this…. Thank YOU for the meal!! But yeah, thanx for spending the time to discuss this issue here on your blog.
Greda.org
I am so happy to come across this piece of write up, very much advanced my understanding to the next top level. Great job and continue to do same.
jolibet casino