Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Creative Coding

Rewrite API: Tipos de entradas y taxonomías

by
Read Time:18 minsLanguages:

Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)

Esta es la segunda parte de una serie que examina la "API de reescritura" o Rewrite API de WordPress. En la primera parte hicimos un recorrido de parada sobre los conceptos básicos de la API de reescritura de WordPress. En este tutorial veremos los ajustes de reescritura que tenemos a nuestra disposición al registrar un tipo de entrada o taxonomía. Aunque los tipos de entradas y taxonomías personalizadas (a diferencia de las entradas, las categorías y las etiquetas predeterminadas) no se benefician de ninguna interfaz de Ajustes -> Enlace permanente, los ajustes de reescrituras para los tipos personalizados sigue siendo bastante sencilla. También usaremos los métodos introducidos en la primera parte, así que, si aún no lo has hecho, te recomiendo que leas la primera parte sobre la Rewrite API de WordPress Parte uno : Los fundamentos.


Purgar las reglas de reescritura

Cuando registras un tipo personalizado, WordPress también registra reglas de reescritura (en realidad, no del todo, y explicaré por qué en la sección 'Permaestructuras'). Como mencionamos en la primera parte, estas reglas solo se incluirán una vez que las reglas de reescritura hayan sido 'purgadas'. Los temas y plugins pueden forzar este "purgado" llamando a flush_rewrite_rules(). Esto debe, y sólo debería, hacerse una vez durante la activación y nuevamente después durante la desactivación (para hacer limpieza tras de ti).

Obviamente, antes de vaciar las reglas de reescritura, has tenido que añadirlas. Sin embargo, el gancho de inicio (init) en el cual los tipos de entradas deben ser registradas, ya se ha activado y cuando lo estaba, tu plugin o tema aún no había sido activado, por lo tanto, los tipos de entradas y las taxonomías todavía no están registradas. Esto significa que para registrar las reglas de reescritura que vienen con tus tipos de entradas y taxonomías, debes registrarlas "manualmente" durante la activación, antes de purgar las reglas de reescritura. Por lo tanto, esta debería ser tu configuración:

Los temas pueden utilizar los ganchos after_switch_theme para la activación y switch_theme para la desactivación.


Tipos de entradas personalizadas

Al registrar un tipo de entrada con register_post_type uno de los argumentos que tenemos disponibles es el argumento de reescritura. Debe ser una matriz con las siguientes claves:

  • slug – un slug utilizado para identificar el tipo de entrada en las URLs. El slug de la entrada se añade a esto para formar su permalink, por ejemplo, www.ejemplo.com/libros/el-mago-de-oz
  • with_front – verdadero o falso. Si la estructura de permalink de tu entrada comienza con una base constante, como '/blog', esto también puede añadirse a la estructura de permalink de tu tipo de entrada personalizada estableciéndolo en true, por ejemplo, true proporcionaría www.ejemplo.com/blog/libros/ y falso www.ejemplo.com/libros/
  • feeds – verdadero o falso. Si se deben generar reglas de reescritura para el feed en tiempo real, por ejemplo, www.ejemplo.com/libros/feed/rss y www.ejemplo.com/libros/rss. El valor predeterminado es el valor de has_archive.
  • pages – verdadero o falso. Indica si se debe generar una regla para la paginación 'bonita' para el archivo del tipo de entrada, por ejemplo, www.ejemplo.com/libros/page/2 en lugar de www.ejemplo.com/libros?page=2. El valor predeterminado es true.
  • ep_mask – Esto solía ser un argumento independiente: permalink_epmask. A partir de la versión 3.4 cambió a la matriz de reescritura. El valor predeterminado es EP_PERMALINK.

Las claves 'feeds' y 'pages' hacen referencia únicamente a la página de archivo del tipo de entrada (para la que debes haber establecido el argumento has_archive en true). Desde esta matriz de reescritura WordPress gestiona la generación de las reglas de reescritura para tus tipos de entrada automáticamente. Por ejemplo:

Daría las siguientes reglas de reescritura:

  • El permalink del libro (book) 'the-wizard-of-oz': www.example.com/books/the-wizard-of-oz
  • Archivo de todos los libros (books) www.ejemplo.com/books (y www.ejemplo.com/books/page/2)
  • El feed del anterior archivo: www.ejemplo.com/books/feed/rss (y www.ejemplo.com/books/rss)

Taxonomías

La función register_taxonomy() ofrece menos opciones:

  • slug – un slug para identificar la taxonomía, por ejemplo, www.ejemplo.com/genero/historia
  • with_front – Como se explicó más arriba.
  • hierarchical – verdadero o falso. Si se establece en true y la taxonomía es jerárquica, el permalink del término refleja la jerarquía. El valor predeterminado es false.
  • ep_mask – Añadido en la versión 3.4. Consulta la sección EP Mask a continuación.

Las dos primeras opciones son similares a las anteriores. La opción jerárquica le proporciona a los permalinks del término la misma estructura que a las páginas. Por ejemplo, deja que 'History' (Historia) sea un género y 'Military History' (Historia militar) un subgénero. Con el conjunto jerárquico en false, 'Military History' tendrá el permalink:

Mientras que, establecido en true, tendría:

El registro de una taxonomía registra automáticamente los feeds de los términos de taxonomía:

Puedes obtener el permalink del enlace del feed de cualquier término de taxonomía con $feed_link = get_term_feed_link($term_id, $taxonomy, $feed)


Archivos de tipo de entrada

De forma predeterminada, WordPress no crea enlaces permanentes 'bonitos' para los archivos de año, mes o día de tu tipo de entrada personalizada (ni para el archivo del autor, pero vamos a dejar esto por ahora). Mientras tanto:

Proporciona correctamente un archivo de todos los libros publicados en mayo de 2012:

Dará un error 404. Sin embargo, podemos simplemente añadir reglas de reescritura adicionales utilizando los métodos de la API de reescritura disponibles que cubrimos en la primera parte. Un método consiste en añadir la siguiente lista de reglas de reescritura al registrar el tipo de entrada:

Esto puede fácilmente acabar en algo un poco desordenado, especialmente si se tiene en cuenta que tendrías que añadir reglas adicionales si deseas que tus archivos admitan URLs bonitas para tus feeds. Sin embargo, lo anterior ilustra un hecho importante acerca de la adición de reglas personalizadas: el orden en que son añadidas es importante.

Recuerda que estas reglas se añaden a la matriz de reescritura en el orden en que se llama a add_rewrite_rule. Al analizar una solicitud, WordPress utiliza la primera regla de coincidencia. Intenta cambiar el orden en el que se añaden las reglas de archivo de año y mes. Descubrirás que www.ejemplo.com/libros/2012/04/ te lleva al archivo de 2012. Esto se debe a que esa dirección URL coincide con los patrones de los archivos de año y mes, pero el primero se añadió primero. Recuerda añadir siempre primero la regla más específica.

Por otro lado, si añades una regla de reescritura, cuyo regex ya exista como regla, esa regla será reemplazada por la nueva.


Permaestructuras

Hay una manera sencilla de conseguir lo anterior: add_permastruct. Esta función es utilizada por WordPress para crear 'permastructures', a partir de las cuales genera reglas de reescritura (como las anteriores), que manejan la paginación y los feeds. Cuando registras un tipo de entrada personalizada, WordPress no crea automáticamente todas las reglas de reescritura. En su lugar, registra una permaestructura, y sólo cuando se generan las reglas (es decir, cuando están siendo purgadas) WordPress utiliza esas permaestructuras para generar las reglas de reescritura definitivas.

Un ejemplo de una permaestructura es la que utilizas en Ajustes -> Enlaces permanentes. Estos aceptan cualquier slug 'codificado a mano' o cualquier etiqueta que exista de forma predeterminada o haya sido agregada con add_rewrite_tag, algo que cubrimos en la primera parte. Por ejemplo, la permaestructura %year%/%category%/%author% generaría las siguientes reglas de reescritura:

  • www.ejemplo.com/2012/url-reescrita/stephen
  • www.ejemplo.com/2012/url-reescrita/stephen/page/2
  • www.ejemplo.com/2012/url-reescrita/stephen/feed/rss
  • www.ejemplo.com/2012/url-reescrita/
  • www.ejemplo.com/2012/url-reescrita/page/2
  • www.ejemplo.com/2012/url-reescrita/feed/rss
  • www.ejemplo.com/2012/
  • www.ejemplo.com/2012/page/2
  • www.example.com/2012/feed/rss

La función add_permastruct

La función add_permastruct acepta cuatro argumentos:

  • name – Un slug único para identificar tu permaestructura
  • struct – La propia permaestructura, por ejemplo, '%year%/%category%/%author%'
  • with_front – verdadero o falso. Este es el mismo argumento que el que usamos al registrar el tipo de entrada
  • ep_mask – Consulta la sección de la Máscara del PE a continuación

Aquí debemos hacer un par de advertencias sobre el uso de add_permastruct. En primer lugar: querrás asegurarte de que una permaestructura personalizada no entre en conflicto con las reglas de reescritura de WordPress para las entradas y las páginas. Esto puede hacerse anteponiendo a tu permaestructura personalizada algo codificado de forma rígida. Por ejemplo:

En segundo lugar, las reglas se añaden en ese orden, por lo que si tus etiquetas son 'demasiado genéricas', es posible que estas últimas reglas nunca se apliquen. Por ejemplo, la estructura anterior (que puedes comprobar en la página Ajustes -> Enlaces permanentes), generalmente funciona bien, a excepción de:

Se interpreta como la página de entradas del autor '2', en la categoría 'page' en 2012. Si deseas utilizar add_permastruct y tener tus reglas de paginación y feeds en cascada de forma correcta, entonces tendrás que utilizar etiquetas que no sean 'genéricas' (con esto quiero decir que las expresiones regex no son genéricas). %author% y %category% son buenos ejemplos de una etiqueta genérica, ya que normalmente coincidirán con cualquier carácter.

Ejemplo de permaestructura personalizada: Archivos de fecha de tipo entrada

Las etiquetas de año, mes y día, por otro lado, son muy específicas: solo coinciden con enteros positivos de cuatro y dos longitudes, por lo que podemos usar add_permastruct para el archivo de fecha de nuestro tipo de entrada. Debido a la naturaleza específica de las etiquetas de fecha, necesitamos que estas reglas sean añadidas antes de la regla de permalink del tipo de entrada, así que agrega lo siguiente inmediatamente antes de registrar tu tipo de entrada:

En lo anterior, la etiqueta personalizada %book_cpt% actúa como un slug codificado de forma rígida para diferenciar esta permaestructura de otras reglas (como primera advertencia). Las reglas generadas solo se aplicarán si %book_cpt% coincide con 'books' y, en qué caso la parte 'book' se captura e interpreta como el valor para post_type. Ten en cuenta que add_rewrite_tag solo acepta el tercer argumento desde WordPress 3.4. Sin embargo, puedes utilizar la siguiente alternativa:

Una vez configurados los archivos para libro (book), también es posible que

Nos llevaría también al archivo del libro de 2012. Pruébalo, sin embargo, revela que en su lugar nos lleva a la página de archivo las publicaciones del año:

WordPress nos ha redirigido a una página diferente debido a algo conocido como canonicalización.


Redirección canónica

Normalmente hay muchas direcciones URL que podrían apuntar al mismo contenido en tu sitio web. Por ejemplo:

Todos te llevarán a la primera página de tu archivo de 2012. Desde una perspectiva SEO esto no es genial, no podemos suponer que los motores de búsqueda vayan a reconocer estas URLs como un mismo recurso, y estas URLs podrían terminar compitiendo entre sí. Google también puede penalizarte activamente por contenido duplicado, y aunque es bueno para determinar cuándo esta duplicación no es 'maliciosa', sigue recomendando redirigir estas URLs superfluas a una URL "canónica" (o estándar) preferida. A esto se le denomina canonicalización.

Esto no solo ayuda a consolidar rankings como la popularidad de los enlaces, sino que también ayuda a los usuarios. Si usan una URL fea o "incorrecta" (son dirigidos a la URL "correcta") y lo que hay en su barra de direcciones, es a lo que es a lo que vayan a volver con mayor probabilidad.

Desde 2.1.0 WordPress ha gestionado la redirección canónica, incluso tomando una conjetura educada sobre el contenido buscado si la consulta original devolvió un código 404. Desafortunadamente, en este caso, WordPress está redireccionando a la URL incorrecta. Esto se debe a que la URL que realmente queremos no es entendida de forma nativa por WordPress, y ha ignorado la parte de 'tipo de entrada' de la URL. Afortunadamente, sin embargo, podemos usar el filtro redirect_canonical para solucionar esto.

La función anterior es larga, pero no muy complicada. Podría mejorarse, y sólo está pensada como un ejemplo de lo que se puede hacer con el filtro redirect_canonical. Primero comprueba que los pretty permalinks o 'enlaces permanentes amigables' están estén activados, que estamos tras nuestro archivo "book" (libro) y que no es un feed. A continuación, comprueba a su vez:

  1. ¿Es un archivo de año, mes o día? Si es así, quita la variable 'year' de la cadena de consulta y establece la URL de redirección a www.ejemplo.com/books/[year]
  2. ¿Es un archivo de mes o día? Si es así, quita la variable 'monthnum' de la cadena de consulta y anexa el valor a la URL de redirección: www.ejemplo.com/books/[year]/[monthnum]
  3. ¿Es un archivo de día? Si es así, quita la variable 'day' de la cadena de consulta y añade el valor a la URL de redirección: www.ejemplo.com/books/[year]/[monthnum]/[day]
  4. Por último, si hay una variable paginada, anexa esto a la URL de redirección

Etiquetas en los enlaces de tipo de entrada

Otra característica que no se admite para los tipos de entradas o taxonomías "de forma predeterminada" es el uso de etiquetas en la estructura del enlace permanente. Mientras las etiquetas utilizadas en el 'slug' de la matriz de reescritura (o taxonomía) de un tipo de entrada se interpretan correctamente, WordPress no reemplaza estas etiquetas por sus apropiados valores al generar los enlaces permanentes, necesitamos reemplazarlo nosotros mismos. Sin embargo, el uso de etiquetas como esta también interrumpe la página de archivo del tipo de entrada, por lo que usaremos un método diferente. Por ejemplo, supongamos que queremos que nuestro tipo de entrada personalizada 'book' tenga la siguiente estructura:

Estoy usando el ejemplo de una taxonomía personalizada, pero pueden usarse los mismos métodos para cualquier permaestructura (por ejemplo, incluyendo la fecha, el autor o incluso un campo personalizado). En primer lugar, añadimos la regla de reescritura:

Ahora, www.ejemplo.com/book/fiction/the-wizard-of-oz, por ejemplo, señala el libro 'the-wizard-of-oz' (el-mago-de-oz). Sin embargo, el enlace permanente generado por WordPress todavía genera www.ejemplo.com/book/the-wizard-of-oz. El siguiente paso es alterar el enlace permanente generado.

Hicimos algo similar en la primera parte cuando queríamos usar una etiqueta personalizada en la estructura de enlaces permanentes de la entrada. Después utilizamos el filtro post_link; esta vez usamos el equivalente para los tipos de entradas personalizadas, el filtro post_type_link. Usando este gancho podemos inyectar nuestra estructura en los enlaces permanentes de los libros (books).


Manipular las reescrituras de WordPress

Vamos a ampliar la anterior estructura de enlaces permanentes para conseguir lo siguiente:

  • Un libro específico: www.ejemplo.com/books/[algunos-generos]/[un-libro]
  • Todos los libros de un género: www.ejemplo.com/libros/[algunos-generos]
  • Todos los libros: www.ejemplo.com/libros/

Recuerda que el orden en el que se añaden las reglas de reescritura es importante. Específicamente, las reglas añadidas primero tienen prioridad.

Por lo tanto, primero registramos nuestra taxonomía personalizada 'genero' con:

Esto añade la siguiente permaestructura:

  • Libros en un género: www.ejemplo.com/libros/[algunos-generos]

Después de registrar la taxonomía, registramos nuestro tipo de entrada personalizada de la siguiente manera:

Esto registraría las siguientes reglas:

  • Todos los libros: www.ejemplo.com/libros/ (que queremos)
  • Un libro concreto: www.ejemplo.com/libros/[un-libro] (que no)

Sin embargo, el segundo conflicto con (y que es 'batido' por) la regla que compite y que fue añadida cuando registramos nuestra taxonomía. La estructura resultante es:

  • Libro llamado 'slug' : www.ejemplo.com/libros/ficcion/slug
  • Libros en el género 'slug': www.ejemplo.com/libros/slug
  • Todos los libros: www.ejemplo.com/libros/

EP_Masks

Anteriormente, cuando analizamos el registro de tipos de entradas, taxonomías (o de otro tipo, permaestructuras), WordPress nos permite especificar nuestro propio 'ep_mask'. Entonces, ¿qué son?

En la primera parte analizamos cómo podemos añadir puntos de conexión con add_rewrite_endpoint. El segundo argumento de esa función es una constante (o combinación de constantes mediante operadores bit a bit), que determinan dónde se añade el punto final. Por ejemplo:

Añade la forma de reescritura form(/(.*))?/?$ a cada enlace permanente de página y:

Añade la reescritura json(/(.*))?/?$ a cada enlace permanente de una entrada y página. Por lo tanto, estas constantes especifican una 'ubicación' (es decir, 'al final de un enlace permanente de entrada') y se denominan máscaras de punto final (es decir, endpoint masks, o máscaras ep).

Cuando registras un tipo de entrada, WordPress registra una permaestructura y se asocia con ella una máscara de punto final. A continuación, cuando se generan las reglas de reescritura, también añade las reglas de reescritura de punto de conexión que han sido añadidas a esa máscara de punto final.

Por ejemplo, cuando WordPress registra el tipo de entrada predeterminada 'Page', asocia la máscara de punto final EP_PAGES con la permaestructura de la página. A continuación, las reglas de reescritura de punto de conexión añadidas al EP_PAGES son realmente añadidas a esa permaestructura de página. Al registrar un tipo de entrada, puedes especificar tu propia máscara de punto final o utilizar una existente. De forma predeterminada, es EP_PERMALINKS, lo que significa que las reglas de reescritura de punto de conexión que se añaden a EP_PERMALINKS se añaden a las reglas de reescritura del tipo de entrada personalizada.

Por supuesto, es posible que no desees que se añadan reglas de punto de conexión para el tipo de entrada (en cuyo caso puedes usar la máscara de punto de conexión EP_NONE), o puedes añadir algunas reglas de reescritura de punto de conexión solo al tipo de entrada personalizada. Para ello, primero debes crear una máscara de punto final, que no es más que una constante que satisface lo siguiente:

  1. El valor de la constante es un número positivo y una potencia de 2: 2x (por ejemplo, 2097152 a 221)
  2. Este valor es único

El poder de requerir 2 es necesario porque WordPress utiliza lógica binaria para determinar dónde se deben añadir las reglas de punto final. Desafortunadamente, esto es casi imposible de comprobar, así que el mejor consejo es añadir máscaras de punto final sólo cuando sea necesario y asignarle un valor muy alto (por ejemplo, 221). En el momento de escribir 20 hasta 213 son utilizados por Núcleo.

Define tu máscara de punto final justo antes de registrar tu tipo de entrada o taxonomía:

(Nota: Lo anterior utiliza argumentos de WordPress 3.4. Si estás utilizando una versión anterior, tendrás que utilizar permalink_epmask ahora en desuso.). A partir de WordPress 3.4 también puedes especificar una máscara de punto final al registrar una taxonomía.


Sumario

En este tutorial he cubierto los conceptos básicos de la API de reescritura para tipos de entradas y taxonomías, y también algunos temas más avanzados. La gestión de reescrituras de WordPress es (necesariamente) complejo y la mejor manera de entenderlo es profundizar en el código fuente y probarlo usando lo que has aprendido y un plugin de analizador de reescritura.

Hay un par de tickets abriéndose camino a través del desarrollo de WordPress Trac en este momento, relacionados con la API de reescritura. En el futuro vemos una forma mucho más fácil y libre de conflictos para entregar máscaras de punto final.

Advertisement
Did you find this post useful?
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.