Comprender los códigos cortos de WordPress

Si ha estado usando WordPress durante algún tiempo, probablemente ya haya usado algunos códigos abreviados.

Los códigos abreviados son pequeños fragmentos útiles que le permiten insertar algún tipo de funcionalidad especial en su contenido que de otro modo no sería posible. Como ejemplo: muchas galerías de imágenes y complementos deslizantes le brindan un código abreviado que simplemente puede insertar en su contenido en cualquier lugar que desee para que aparezcan las imágenes adecuadas allí. Los códigos cortos generalmente se ven así:

[example shortcode]

En otras palabras: los códigos abreviados hacen que suceda algo especial dondequiera que se coloquen en el texto.
Pero no está limitado a códigos cortos predefinidos; ¡Puedes definir códigos abreviados personalizados para hacer lo que quieras! Pueden ser simples, complejos o cualquier cosa intermedia.

En esta serie, comenzaremos con un shortcode simple y avanzaremos hacia algunos ejemplos más complejos (¡e incluso más útiles!).

Nota: trabajaremos principalmente con PHP aquí, específicamente en el archivo functions.php de su tema. Si no está utilizando un tema secundario (o un tema personalizado/de inicio que se puede editar sin temor a que las actualizaciones sobrescriban sus cambios), querrá crear un tema secundario antes de comenzar.

También tenga en cuenta: no necesita ningún conocimiento de PHP para leer esta publicación, pero conocer al menos los conceptos básicos ayudará. El código involucrado aquí es bastante simple y hemos intentado que sea lo más fácil posible de copiar y personalizar. Explicaremos cada parte del código a medida que avanzamos, pero si eres completamente nuevo en el tema PHP de WordPress, ten en cuenta que un poco de código incorrecto en tu archivo functions.php puede dañar el sitio.

Un ejemplo útil de código abreviado simple

Digamos que queremos un código abreviado que inyecte una sección especial de información del autor en una publicación, como esta:

En lugar de crear y diseñar el cuadro, la imagen y el texto en el editor visual de WordPress, simplemente crearemos un código abreviado para generar todo eso con un simple fragmento.

(Nota al margen: WordPress tiene mejores formas de trabajar con perfiles de autor, pero nos quedamos con este ejemplo porque demuestra muy bien lo fácil que es usar códigos abreviados para colocar bloques específicos de contenido en una página).

Paso 1: agregue el código abreviado en el archivo functions.php de su tema

Usarás la función add_shortcode para darle un nombre a tu shortcode y decirle a WordPress qué debe hacer cada vez que se use el shortcode. Agregue esta línea al archivo functions.php de su tema:

 [php]add_shortcode( 'author_bio', 'create_author_bio' );[/php]

Realmente no importa dónde esté dentro functions.php , pero para evitar conflictos, recomendamos ponerlo al final. (Sin embargo, si el archivo termina con una etiqueta de cierre ?>, debería ir justo antes de eso, no después).

Antes de continuar, dividamos un poco esa línea, para que entendamos lo que realmente está pasando aquí. Los dos fragmentos de texto, o "argumentos", dentro de los paréntesis no son especiales, en realidad; son solo nombres. Repasemos lo que significa cada uno:

1. El primer argumento: en este caso, author_bio : le dice a WordPress el nombre real de su shortcode. Este será el texto que los usuarios pueden escribir, entre paréntesis, para usar el shortcode. Entonces, con este código tal como está escrito, [author_bio] será nuestro código abreviado para activar nuestro cuadro de biografía del autor.
   Este texto podría ser cualquier cosa, pero siempre es mejor tratar de ser único. De esa manera, no correrá el riesgo de que el nombre de su shortcode entre en conflicto con el de otra persona de otro complemento o tema instalado.
2. El segundo argumento: en este caso, create_author_bio : apunta a WordPress hacia la función PHP real que debe ejecutar cada vez que se usa este shortcode. Crearemos esa función en el próximo paso; por ahora, solo le informamos a WordPress cuál será su nombre. (Este nombre también debe ser único, para evitar conflictos).

Entonces, si ayuda, podría pensar en el código de esta manera:

 [php]add_shortcode( 'when_you_see_THIS_shortcode', 'do_THIS' );[/php]

Si está interesado en obtener más detalles esenciales, consulte la entrada del Codex add_shortcode .

Paso 2: Cree la función para manejar el código abreviado

¡Ahora necesitamos hacer la función que acabamos de nombrar!

Ya que le dijimos a WordPress en el último paso que el nombre de nuestra función es create_author_bio, nuestro código ahora debería verse así, una vez que hayamos agregado la nueva función:

 [php]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ //Code goes here! }[/php]

Puede notar que esta función en realidad no hace nada todavía; todo lo que hay dentro es un comentario. Nos encargaremos de eso en el siguiente paso. Por ahora, solo queremos señalar que en realidad solo hay dos piezas aquí: el registro del código abreviado y la función que sucede cada vez que se usa. WordPress PHP puede parecer intimidante, ¡pero en realidad es así de simple!

Nota al margen: no importa si la función create_author_bio viene después de la función add_shortcode o antes. El orden no es importante en este caso.

Paso 3: Haz que la función haga algo

¡Ahora todo lo que queda es hacer que nuestra función haga lo que queremos!

Una función como esta podría hacer cualquier cosa, pero sin importar qué, eventualmente debería devolver un solo valor (como una cadena de texto o un número). Ese valor podría ser de cualquier longitud o complejidad, pero lo que devuelva la función es lo que aparecerá donde se use nuestro shortcode.

Para nuestros propósitos, esto será solo un HTML simple. Aquí está el marcado para agregar nuestra imagen de autor y biografía dentro de un elemento <aside> con una clase personalizada (pero no coloque esto en ningún lado todavía; solo lo estamos viendo como una vista previa por el momento):

 [html]<aside class="author-bio-box"></span> <img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"> <p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p> <p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p> </aside>[/html]

Eventualmente, usaremos esa clase autor-bio-box en la primera línea para diseñar la biografía con CSS. (Usaremos una clase en lugar de una ID, en caso de que desee agregar más de un código abreviado de autor para el contenido escrito por varios autores). Pero recuerde, ¡esto podría ser cualquier cosa que queramos poner en la página!

¡Ahora, todo lo que tenemos que hacer es hacer que la función de nuestro shortcode devuelva el HTML anterior!

Dado que el archivo functions.php solo debe contener... bueno, funciones de PHP (y también para el orden), hemos eliminado los saltos de línea y los espacios entre los elementos HTML que acabamos de mirar y los metimos en una cadena (dentro de comillas simples) . Pero funcionalmente, sigue siendo el mismo fragmento HTML que acabamos de ver arriba, y así es como debería verse nuestro código PHP final:

 [html]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ return '<aside class="author-bio-box"><img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"><p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p><p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p></aside>'; }[/html]

¡Hemos terminado con PHP! Una vez que hayamos guardado nuestro archivo functions.php con el código final anterior, cualquier autor puede simplemente ingresar [author_bio] en cualquier página o publicación, ¡y el HTML anterior aparecerá en el lugar del código abreviado!

Además, lo realmente genial es: si alguna vez necesitamos actualizar nuestra biografía, ¡no necesitaremos editar cada lugar donde aparece! En cambio, todo lo que tenemos que hacer es editar el código en nuestro archivo functions.php , y se actualizará en todas partes a la vez. Listo, ¿eh?

Sin embargo, para aprovechar al máximo esto, probablemente querremos agregar un estilo especial al cuadro de biografía.

Paso 4: Agrega algo de CSS

El shortcode no es genial sin algo de estilo, ¡así que vamos a agregarlo! Es posible que deba ajustar un poco algunos de los valores, según las fuentes de su propio sitio (la de la imagen de arriba es Fanwood Text) y las reglas de CSS que ya existen. ¡O quizás quieras probar algo diferente!

Este CSS podría copiarse en el archivo style.css de su tema (hijo), o si está ejecutando WordPress 4.7 o superior (¡lo cual debería ser!), puede simplemente pegar este CSS en el cuadro "CSS adicional" en Personalizar pantalla:

 [css].author-bio-box { background: #d4ead9; padding: 2em; overflow: auto; font-family: Fanwood Text; font-size: 1.2em; line-height: 1.4em; } .author-bio-box img { float: left; max-width: 128px; height: auto; margin: 0 1em 0 0; } .author-bio-box > p:first-of-type:first-letter { font-size: 3.1em; line-height: 1; float: left; margin-bottom: -.2em; } .author-bio-box > p:last-of-type { margin: 0; }[/css]

Ahora las cosas deberían verse mucho mejor. ¡Pero siéntete libre de jugar con el CSS para hacer que el cuadro del autor sea tuyo y que se sienta como en casa en tu sitio!

Recomendado: hacer que la función sea "conectable"

Esto no es específico de los códigos abreviados y no es estrictamente necesario para que el código funcione, pero es una buena práctica y este es un buen momento para mencionarlo.

Primero, un poco de información sobre cómo funciona PHP :

¿Recuerdas cómo llegamos a nombrar nuestra función create_author_bio nosotros mismos? Bueno, no hay nada especial en el nombre create_author_bio; podríamos haber nombrado fácilmente a nuestra función como quisiéramos (aunque es mejor si el nombre de la función le da al menos una pequeña pista sobre lo que hace, razón por la cual elegimos create_author_bio ).

Pero aquí está la cosa: si dos funciones de PHP tienen el mismo nombre, el resultado será un error fatal que evitará que el sitio se cargue, ya que PHP no tendrá idea de qué función es la correcta. PHP no adivina, por lo que simplemente se detiene.

Y no es solo nuestro código del que debemos preocuparnos; un sitio de WordPress puede usar código de docenas o incluso cientos de desarrolladores diferentes, según los complementos y temas instalados. Si el mismo nombre de función se usa dos veces, ¡todo falla!

Eso es malo y, obviamente, queremos asegurarnos de que eso nunca suceda.

Podemos hacer eso haciendo que nuestra función sea "conectable"; es decir, decirle a WordPress que no cree nuestra función si ya existe otra con el mismo nombre. Es elegantemente simple; simplemente envolvemos nuestro código existente dentro de esta sencilla declaración condicional:

 [php]if( !function_exists( 'create_author_bio' ) ){ //Our existing PHP goes here! }[/php]

Esa expresión condicional if solo verifica que no exista una función llamada create_author_bio . Todo nuestro código PHP que hemos usado hasta ahora se puede mover dentro de esa declaración, entre las llaves { } .

¡Sin embargo, es mejor nombrar las funciones de la manera más exclusiva posible! Hacer que nuestra función sea conectable solo evita un error fatal. Entonces, si hubiera un conflicto de nombres, nuestro shortcode aún no funcionaría, pero al menos el sitio aún estaría activo y nada más estaría roto.

Conclusión

¡Eso es todo! ¡Espero que hayas disfrutado creando un shortcode de biografía de autor personalizado! Si ha seguido, todo lo que necesita hacer es escribir [author_bio] en cualquier lugar de una página o publicación y aparecerá su código.

Este shortcode se puede adaptar fácilmente para enviar cualquier cosa a una página. Un gif, un bloque personalizado de HTML y/o JavaScript, una imagen o video… ¡lo que quieras!

Sin embargo, si bien este ejemplo es útil si solo necesita generar un único valor estático en la página en algún lugar, no es muy flexible. Siempre devolverá exactamente lo mismo cada vez, y a menudo necesitamos códigos cortos para ser más adaptables que eso.

Buenas noticias: solo hemos cubierto los conceptos básicos de los códigos cortos, ¡y son capaces de mucho, mucho más!