Advertisement
  1. Code
  2. Creative Coding

La API de reescritura: los conceptos básicos

by
Read Time:13 minsLanguages:

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

Esta es la primera parte de una serie de dos partes que analiza la API de reescritura de WordPress. En este tutorial, veremos cómo funcionan las reescrituras y los métodos básicos disponibles para crear reglas de reescritura personalizadas.


¿Qué es la reescritura?

WordPress, como todos los sistemas de gestión de contenido, decide qué contenido mostrar en función de las variables (generalmente llamadas variables de consulta) que se le pasan. Por ejemplo: https://example.com/index.php?category=3 le dice a WordPress que estamos buscando publicaciones en una categoría con un ID de 3 y http://example.com/index.php?feed=rss le dice a WordPress que queremos la fuente del sitio en formato RSS.

Desafortunadamente esto puede dejarnos con URL bastante feas:

Aquí es donde entra en juego la reescritura de WordPress. Nos permite reemplazar lo anterior con:

Lo que ahora no sólo es mucho más legible (y memorable) sino también más amigable con el SEO. Esto es, en pocas palabras, lo que hace la reescritura.


¿Cómo funciona?

Ahora http://example.com/portoflio/wordpress/my-fancy-plugin no existe como directorio o como archivo. Entonces, ¿cómo ofrece WordPress el contenido correcto? Cuando WordPress recibe un 'enlace permanente bonito' como el anterior, necesita convertirlo en algo que comprenda, es decir, un objeto de consulta. Dicho de modo más sencillo, tiene que tomar la URL bonita y asignar las partes adecuadas a la variable de consulta correcta. Entonces, para nuestro ejemplo:

  • post_type se configura en 'portafolio'
  • portfolio-taxonomy se configura en 'wordpress'
  • portfolio se configura en 'my-fancy-plugin' (el nombre de la publicación)

Entonces WordPress sabe que estamos buscando publicaciones de tipo 'portfolio', en el término de taxonomía 'portfolio-taxonomy' 'wordpress' con el nombre 'my-fancy-plugin'. (Como habrás adivinado, los dos primeros son en realidad redundantes). WordPress luego realiza esa consulta, elige la plantilla adecuada con la que mostrar los resultados y luego se la muestra al espectador. Pero claramente WordPress no sólo adivina cómo interpretar las URL, hay que decirle...

Comienza con .htaccess

Suponiendo que puedas y hayas habilitado bonitos enlaces permanentes en tu Configuración -> Página de enlaces permanentes (consulta el Codex para conocer los requisitos mínimos; para WordPress en servidores Nginx existe este plug-in), entonces las cosas comienzan con el archivo .htaccess. Desempeña un papel sencillo y a la vez significativo. WordPress incluye algo similar a lo siguiente en este archivo:

Esto simplemente comprueba si el archivo o el directorio realmente existe; y si lo hace, simplemente lo lleva allí. Por ejemplo:

Simplemente te llevaría el archivo adjunto PNG 'mi-imagen.png'. Pero, como en el caso de:

Donde el directorio no existe, te lo llevas a tu archivo de WordPress index.php. Es este archivo el que inicia WordPress.

Interpretar la URL

En este punto, WordPress aún no sabe lo que buscas. Después de una carga inicial de WordPress y su configuración, activa el método parse_request de la clase WP (ubicado en el archivo class-wp.php). Es este método el que toma /portoflio/wordpress/my-fancy-plugin y lo convierte en un objeto de consulta comprensible de WordPress (casi, en realidad configura la matriz query_vars y después $wp->query_posts convierte esto en una consulta).

En resumen, esta función compara la URL recibida (/portoflio/wordpress/my-fancy-plugin) con una matriz de 'expresiones regulares'. Esta es la matriz de reescritura, y se verá algo así:

Las claves de esta matriz son expresiones regulares, y la URL recibida se compara con cada una de ellas hasta que coincida con el patrón de la URL recibida. El valor correspondiente es cómo se interpreta la dirección URL. La matriz $matches coincide con los valores capturados (indexados a partir de 1) de la coincidencia.

Por ejemplo, visitando www.example.com/blog/tag/my-tag, WordPress buscará el primer patrón que coincida con 'tag/my-tag'. Con la matriz anterior, coincide con el tercer patrón: tag/([-/]+)/?$. Esto le dice a WordPress que interprete la URL como www.example.com/blog/index.php?tag=my-tag y correspondientemente se notifica el archivo 'my-tag'.

Por supuesto, WordPress te permite personalizar esta matriz, y el resto de este tutorial está dedicado a mostrarte cómo hacerlo.


Personalización de las reglas de reescritura

Configuración -> Enlaces permanentes

Tu primer punto de contacto debe ser la página de configuración de 'Enlace permanente'. Esta página te permite modificar las reglas para el tipo de publicación 'post' predeterminado y las taxonomías de 'category' y 'tags'. La opción 'predeterminada' tiene bastantes enlaces permanentes deshabilitados, pero puedes seleccionar de una lista de estructuras predefinidas o crear una estructura personalizada. Ten en cuenta que las estructuras personalizadas no deben contener la URL del sitio. WordPress te permite alterar tu estructura de enlaces permanentes agregando etiquetas proporcionadas como %postname% (nombre de la publicación), %year% (el año en que se publicó la publicación) y %author% (el autor de la publicación). Una estructura de enlaces permanentes como:

Produciría un enlace de publicación como:

La documentación de estas opciones se puede encontrar en el Codex de WordPress. (Más adelante te mostraré cómo crear tus propias etiquetas personalizadas).

Sin embargo, las opciones proporcionadas son bastante limitadas. En este tutorial me centraré en las funciones proporcionadas por WordPress que ofrecen un mayor control sobre las estructuras de enlaces permanentes y cómo se interpretan. No hablaré sobre las opciones de reescritura disponibles para los tipos de publicaciones personalizadas o taxonomías, ya que esto se tratará en la parte 2.

¿Por qué eliminar las reglas de reescritura?

Después de cualquier modificación de las reglas de reescritura (por ejemplo, usando uno de los siguientes métodos o registrando un tipo de publicación personalizada o taxonomía), es posible que las nuevas reglas no entren en vigencia. Esto se debe a que necesitas eliminar las reglas de reescritura. Esto se puede hacer de dos maneras:

  • Simplemente visita la Configuración -> Enlace permanente
  • Llama a flush_rewrite_rules() (tratado en la parte 2)

¿Qué hace esto? Recuerda que el método parse_request compara la solicitud con una matriz de reescritura. Esta matriz vive en la base de datos. Al eliminar las reglas de reescritura, se actualiza la base de datos para reflejar tus cambios y, hasta que lo hagas, no se reconocerán. Pero parse_request también escribe en el archivo .htaccess. Esto hace que sea una operación costosa. Entonces, aunque no trataré el uso de flush_rewrite_rules() hasta la parte 2, te daré esta advertencia: No llames a flush_rewrite_rules en cada carga de página. Los plug-ins solo deben llamar a esto cuando el plug-in está activado y desactivado.

Agregar regla de reescritura

El add_rewrite_rule te permite agregar reglas adicionales a la matriz de reescritura. Esta función acepta tres argumentos:

  • regla: una expresión regular con la que comparar la URL de la solicitud
  • reescribir: la cadena de consulta utilizada para interpretar la regla. La matriz $matches contiene las coincidencias capturadas y comienza desde el índice '1'.
  • posición:  'top' o 'bottom'. Dónde colocar la regla: en la parte superior de la matriz de reescritura o en la parte inferior. WordPress escanea desde la parte superior de la matriz hasta la parte inferior y se detiene tan pronto como encuentra una coincidencia. Para que tus reglas tengan prioridad sobre las reglas existentes, querrás configurar esto en 'top'. El valor predeterminado es 'bottom'.

Nota: si utilizas add_rewrite_rule varias veces, cada uno con la posición 'top'; la primera llamada tiene prioridad sobre las llamadas subsiguientes.

Supongamos que nuestras publicaciones tienen una fecha de evento asociada a ellos y queremos tener esta estructura: www.example.com/blog/the-olympics-begin/2012-07-27 interpretado como www.example.com/blog/index.php?postname=the-olympics-begin&eventdate=2012-07-27 entonces podemos agregar esta regla de la siguiente manera:

Lo siguiente interpretaría www.example.com/olympics/2012/rowing como www.example.com/index.php?p=17&olymyear=2012&game=rowing

Si no estás seguro de tus expresiones regulares, puede que esta introducción y esta herramienta te resulten útiles.

Agregar etiqueta de reescritura

Puedes pensar que el valor de eventdate (2012-07-27 en el ejemplo anterior), olymyear y game puede ser accesible desde el interior de WordPress a través de la get_query_var (de la misma manera que get_query_var('paged') obtiene el número de página en el que se encuentra). Sin embargo, WordPress no reconoce automáticamente la variable eventdate a pesar de que se interpreta como una variable GET. Hay un par de maneras de hacer que WordPress reconozca variables personalizadas. Una es usar el filtro query_vars como se muestra en la sección 'Agregar punto final personalizado' así. Alternativamente, podemos ir un paso más allá y usar add_rewrite_tag para registrar una etiqueta personalizada como el valor predeterminado %postname% y %year%

Esta función acepta tres argumentos:

  • nombre de etiqueta: (con el porcentaje inicial y el final) por ejemplo: %eventdate%
  • regex: Expresión regular para validar el valor, por ejemplo, '([0-9]{4}-[0-9]{2}-[0-9]{2})'
  • consulta: (opcional) Cómo se interpreta la etiqueta, por ejemplo, 'eventdate='. Si se proporciona, debe terminar con un '='.

get_query_var('eventdate') no solo devolverá el valor de la fecha en la URL, sino que también puedes usar la etiqueta %eventdate% en la configuración -> Enlaces permanentes (junto con el valor predeterminado %year%, %postname%, etc.) y WordPress lo interpretará correctamente. Desafortunadamente, al generar el enlace permanente de una publicación, WordPress no sabe cómo reemplazar %eventdate% con el valor apropiado: por lo que nuestros enlaces permanentes terminan como:

Necesitamos reemplazar %eventdate% por un valor adecuado, y podemos hacerlo usando el filtro post_link. (En este ejemplo, asumiré que el valor se almacena en un campo personalizado 'eventdate').

En la parte 2 de esta serie hablaré sobre las etiquetas personalizadas para tipos de publicaciones personalizadas.

Agregar punto final personalizado

Los puntos finales son etiquetas que se anexan a la dirección URL (/trackback/[value] es el más común). Tiene varios usos potenciales: mostrar diferentes plantillas según el valor establecido, notificaciones personalizadas y mostrar publicaciones en diferentes 'formatos' (imprimibles, XML, JSON, entre otros).

Puedes crear puntos finales con add_rewrite_endpoint. Esta función acepta dos argumentos:

  • nombre: El nombre del punto final, por ejemplo, 'json', 'form', entre otros.
  • dónde: máscara de punto final que especifica dónde se debe agregar el punto final. Esta debe ser una de las constantes EP_ * que se enumeran a continuación (o una combinación que use operadores bit a bit). Al registrar tipos de mensajes personalizados, puedes crear una máscara para ese tipo de mensaje:

Las máscaras de punto final predeterminadas son:

  • EP_PERMALINK - para enlaces permanentes de publicaciones
  • EP_ATTACHMENT – para archivos adjuntos
  • EP_DATE – para archivos de fechas
  • EP_YEAR – para archivos del año
  • EP_MONTH – para archivos mensuales
  • EP_DAY – para archivos del 'día'
  • EP_ROOT – para la raíz del sitio
  • EP_COMMENTS – para comentarios
  • EP_SEARCH – para búsquedas
  • EP_CATEGORIES – para categorías
  • EP_TAGS – para etiquetas
  • EP_AUTHORS – para el archivo de las publicaciones del autor
  • EP_PAGES – para páginas
  • EP_ALL – para todo

Los puntos finales son extremadamente flexibles, puedes usarlos con operadores bit a bit, por lo que, por ejemplo, puedes agregar un punto final para publicar y paginar enlaces con EP_PERMALINK | EP_PAGES.

Por ejemplo, los puntos finales pueden ser útiles para los envíos de formularios. Supongamos que tenemos una página de formulario de contacto con el nombre contact-form y con el enlace permanente: www.example.com/contact y queremos las URL:

  • www.example.com/contact/submission/success ; para reflejar un envío exitoso del formulario
  • www.example.com/contact/submission/error ; para reflejar un envío de formulario sin éxito

Esto se puede hacer con los puntos finales. El siguiente es un ejemplo muy sencillo de cómo usar puntos finales, por lo que el formulario es increíblemente básico en sus comprobaciones (y de hecho no hace nada con los datos). Normalmente, un formulario como este funcionaría mejor en un plug-in, usando códigos cortos, pero para los fines de este ejemplo, crea una página con la siguiente plantilla y el resto del código que puedes poner en tu functions.php

(En caso de que te estés preguntando, la miel se refiere a este método muy básico de captura de spam descrito aquí. Ciertamente no es infalible, pero el procesamiento adecuado de formularios y la protección contra correo no deseado están fuera de tema aquí). Ahora creamos nuestro punto final:

Luego, añadimos nuestra variable 'form' a la matriz de variables reconocidas:

Por último, proporcionamos un controlador de formulario, que procesará los datos, enviará el formulario y luego lo redirigirá de nuevo a la página de contacto con el valor de punto final relevante anexado.

Por supuesto, incluso este ejemplo podría mejorarse en gran medida proporcionando mensajes de error más detallados que transmitan el motivo del error.

Agregar una fuente personalizada

Con bonitos enlaces permanentes habilitados, WordPress produce automáticamente URL bonitas para la fuente de tu sitio: www.example.com/feed/rss. La función add_feed te permite crear una fuente personalizada, que si los enlaces permanentes bonitos están habilitados, también tendrá una URL "bonita". Esta función acepta dos argumentos:

  • nombre de la fuente: El nombre de la fuente tal como aparecerá en feed/[feed-name]
  • devolución de llamada de la fuente: la función responsable de mostrar el contenido de la fuente.

Lo siguiente está pensado como un ejemplo de add_feed y proporciona una fuente personalizada muy básica.

Después de eliminar los enlaces permanentes, la fuente estará disponible en www.example.com/feed/events.


Comprobación de las reglas de reescritura

Una vez que hayas agregado algunas de tus propias reglas de reescritura (y las hayas eliminado), probablemente querrás comprobar si están funcionando correctamente, y si no lo están, averiguar en qué están fallando. Para esto, recomiendo claramente el plug-in Monkeyman Rewrite Analyzer, un plug-in gratuito disponible en el repositorio de WordPress. Una vez activado, este complemento añade una página a la sección "Herramientas", que enumera todas las reglas de reescritura.

También puedes probar las reglas dándole una URL de ejemplo, y el plug-in filtrará las reglas para mostrar solo patrones coincidentes e indicando cómo WordPress interpretaría la URL.

Diviértete y mantente atento a la Parte 2, ¡próximamente!

Ten en cuenta: Actualmente hay un error en nuestro resaltador de sintaxis que muestra "empty()" como "emptyempty()". Por consiguiente, no olvides ajustar el código.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.