Introducción a Advanced Custom Fields

En este tutorial, voy a mostrarte los conceptos básicos del uso del plugin Advanced Custom Fields (ACF). ACF es un plugin bastante extenso, por lo que este artículo no explicará absolutamente todo lo que ofrece, pero debería ser suficiente para empezar a añadir tus propios metadatos y mostrarlos dentro de tu tema.

En el momento en el que este tutorial ha sido escrito, existen dos versiones de ACF: 4 y 5. Este artículo se basa en la versión 4, pero también es aplicable si estás utilizando la versión 5.

¿Qué son los campos personalizados avanzados?

Advanced Custom Fields es una interfaz de usuario para añadir campos personalizados, o metadatos, a WordPress. Los campos personalizados te permiten ampliar tus entradas o páginas con más datos. Echemos un vistazo a un escenario común:

Tienes un tipo de entrada denominada movie y quieres adjuntar una puntuación de diez a la parte inferior de cada una de tus reseñas, junto con otros datos. Ahora, podrías poner estos datos dentro de tu entrada, pero ¿qué pasa si más tarde quieres usar estos datos de otra manera? Tal vez quieras mover la puntuación por encima de tu opinión; en este caso, tendrías que editar manualmente cada reseña de película y mover manualmente esta calificación, esto no es muy buena idea.

WordPress tiene funciones integradas para crear campos personalizados, pero solo incluyen funcionalidad básica y requieren que los campos se creen programáticamente. ACF tiene muchos tipos de campos integrados, algunos de los cuales incluyen:

• Texto
• Correo electrónico
• Editor WYSIWYG
• Imagen
• Archivo
• Casilla de selección
• Selector de fecha
• Selector de color

Además de tener campos integrados, ACF te proporciona una selección de reglas que se pueden utilizar para determinar dónde se muestran los campos dentro de tu administrador de WordPress. Esto es realmente útil para mantener tu área de administración lo más limpia posible. Por ejemplo, puedes mostrar un grupo de campos personalizados solo si el tipo de entrada es reviews y la plantilla de página es featured review.

Empezar

Antes de empezar a añadir algunos campos, debes instalar el plugin ACF. Para ello, desde el escritorio de WordPress dirígete a Plugins > Añadir nuevo. En la pantalla Añadir plugin, busca Advanced Custom Fields y haz clic en Instalar. Asegúrate de activar el plugin, si se ha instalado correctamente, ahora deberías ver un menú de Campos personalizados dentro de tu administrador de WordPress.

Manteniendo la temática de un sitio web de revisión de películas, vamos a crear algunos campos relevantes. Para seguir con este tutorial, necesitarás un tipo de entrada personalizada llamada movie. Para aprender a crear tipos de entradas, dirígete a este otro gran artículo de Tuts+. Dicho esto, los métodos que se muestran aquí funcionarán para muchos otros tipos de campos personalizados, y la lógica para crear y mostrar campos seguirá siendo la misma.

Creación de grupos de campos

Los grupos de campos son exactamente lo que dicen: grupos de campos. Usando el ejemplo de un tipo de entrada llamada movie, es posible que deseemos incluir los siguientes datos:

• año de lanzamiento
• director
• calificación de cero a diez
• Enlace a IMDb

Estos campos pertenecen lógicamente a un grupo, ya que todos están relacionados con el mismo tipo de entrada. Usando los campos anteriores, podemos empezar a pensar en qué tipos de campo podríamos necesitar para estos datos.

• año de lanzamiento: número
• director: texto
• calificación de diez: número
• Enlace IMDb: texto (no existe ningún tipo de campo para url)

Para comenzar a añadir un grupo de campos, haz clic en el menú Campos personalizados dentro de tu escritorio de WordPress. Ahora, haz clic en el botón Añadir nuevo. Ahora se te presentará la pantalla Añadir nuevo grupo de campos. Antes de hacer cualquier otra cosa, vamos a dar un nombre a nuestro grupo de campos escribiendo en el cuadro de título: he llamado al mío Movie Data.

A continuación, podemos agregar todos nuestros campos. Haz clic en el botón Añadir campo para empezar. Ahora verás un formulario que tiene los siguientes campos:

• Etiqueta de campo es el nombre que aparece al editar. Me parece útil comenzar con el mismo prefijo en cada uno de mis campos, por ejemplo, Movie Year, Movie Director, etc.
• Nombre de campo es el nombre que usarás en el código para mostrarlo. Después de escribir la etiqueta de campo, esto debería cumplimentarse automáticamente. Esta es una única palabra, sin espacios, pero se permiten guiones y guiones bajos. Por ejemplo, Movie Year como etiqueta de campo se convertiría en movie_year como nombre de campo.
• Tipo de campo es un campo de texto básico (aunque ACF también ofrece opciones más avanzadas).
• Las Instrucciones de campo son instrucciones que los autores pueden ver al añadir los datos en la pantalla de edición, por ejemplo, "El año de la película siempre debe ser la fecha de lanzamiento en EE. UU.".
• ¿Requerido? es una botón de opción en donde eliges sí o no. Elegir "sí" significa que el campo debe cumplimentarse para poder guardarlo en la pantalla de edición posterior.
• Valor por defecto es el valor que aparecerá automáticamente al crear una nueva entrada.
• El Marcador de texto aparece en el campo de entrada en la pantalla de edición.
• Anteponer define lo que aparece antes del campo de entrada en la pantalla de edición.
• Anexar define lo que aparece después del campo de entrada en la pantalla de edición.
• El formato te da dos opciones: "Convertir HTML en etiquetas" (el valor predeterminado) o "sin formato". Convertir HTML en etiquetas significa que cualquier HTML dentro de tu entrada se representará en la pantalla; sin formato significa que cualquier HTML será ignorado.
• Límite de caracteres nos permite limitar la cantidad de caracteres para un campo de entrada. Por ejemplo, en nuestra entrada year debemos limitar los caracteres a cuatro.
• La Lógica condicional es una característica más avanzada que no veremos en este artículo.

Todos estos campos se muestran para el tipo de campo de texto: en algunos otros tipos de campos, es posible que algunas de estas opciones no se muestren o que haya algunas opciones adicionales. Como también vamos a usar el tipo de campo numérico, hay algunas opciones adicionales disponibles para nosotros:

• Valor Mínimo es el valor de número mínimo que se puede permitir en el campo. Para nuestro campo de puntuación de diez sería razonable establecer esto en uno, ya que no vamos a calificar nada como cero.
• Valor Máximo es el valor numérico máximo que se puede permitir en el campo. Una vez más, podríamos usar esto para nuestro campo de puntuación de diez y establecer el valor como diez, ya que no queremos que este valor sea superior.
• Tamaño del Paso define el valor por el que un número aumenta cuando se presiona una flecha. En el caso de la calificación de la película, sería una buena idea establecer esto como uno.

Así es como configuré mis campos:

• Etiqueta del campo: Movie Year (Año de la película)
• Nombre del campo: movie_year
• Tipo de campo: Rango
• ¿Requerido?: Sí
• Valor Mínimo: 1900
• Valor Máximo: 2050

Ten en cuenta aquí los valores mínimo y máximo: los configuré para añadir una validación muy básica, ya que es poco probable que tengamos una película anterior a 1900 y una más reciente que 2050 en la vida útil del sitio web.

• Etiqueta de campo: Movie Director (Director de cine)
• Nombre del campo: movie_director
• Tipo de campo: Texto
• ¿Requerido?: Sí
• Formato: Sin formato

Dado que vamos a formatear nuestra salida en nuestro HTML, no queremos que los editores puedan agregar HTML aquí que pueda interferir con nuestro diseño. Por lo tanto, aquí elegimos "sin formato".

• Etiqueta del campo: Movie Score (Puntuación de la película)
• Nombre del campo: movie_score
• Tipo de campo: Número
• ¿Requerido?: Sí
• Valor Mínimo: 1
• Valor Máximo: 10
• Tamaño del Paso: 1

Una vez más, tenemos un valor mínimo y máximo establecido aquí para añadir alguna validación; nuestras puntuaciones son de diez, por lo que no queremos que los editores sean capaces de insertar una puntuación más alta que esta. Del mismo modo, no queremos que se inserten puntuaciones inferiores a uno.

• Etiqueta del campo: Movie IMDb Link (enlace a IMDb)
• Nombre del campo: movie_imdb_link
• Tipo de campo: Texto
• Instrucciones del campo: Pega aquí la URL de IMDb completa. Por ejemplo, http://www.imdb.com/title/tt2015381/
• ¿Requerido?: Sí
• Formato: Sin formato

Añadí algunas instrucciones de campo a este campo de entrada, porque no hay ningún tipo de campo para URL, y por tanto es difícil de validar. Las instrucciones deben facilitar a los editores la comprensión del uso del campo.

Una vez que hayas añadido todos los campos, asegúrate de hacer clic en el botón Actualizar. Una vez que hayas hecho clic en esto, volverás a la página Editar grupo de campos. Hay algunas cosas más que tenemos que hacer en esta pantalla para que tus campos funcionen correctamente.

Debajo del área de campo hay un cuadro llamado Ubicación, que nos permite controlar dónde se muestran nuestros campos personalizados. Solo queremos que nuestros campos personalizados se muestren si el tipo de entrada es movie. En el primer menú desplegable, selecciona Post Type, en la segunda lista desplegable la selección es igual a y en la tercera selecciona movie.

Lo último que tenemos que hacer aquí es establecer dónde aparecerá nuestro campo personalizado en la pantalla de edición. Para ello, desplázate hacia abajo un poco más hasta la sección Ajustes. Esto nos permite elegir dónde aparecerá la caja meta de los campos personalizados y de qué tipo es, y nos da la opción de ocultar otras cosas en nuestra pantalla de edición.

Las opciones son las siguientes:

• Número de orden: si tienes varios grupos de campos, se crean en orden de más bajo a más alto.
• La Posición tiene tres opciones:
• Lateral
• Alta (después del título)
• Normal (después del contenido)
• Estilo: estándar o directo (ver imagen a continuación para apreciar la diferencia entre estos).
• Esconder en pantalla: esta es una lista de casillas de verificación que te permiten ocultar cosas que puede que no necesites, como etiquetas, categorías o comentarios.

Las opciones que yo utilicé son las siguientes:

• Posición: Lateral
• Estilo: Estándar

El resto lo dejé con sus valores predeterminados.

Puedes comprobar que los campos se muestran correctamente creando una nueva entrada (en este caso en el tipo de entrada movie). Si todo ha funcionado bien, entonces verás tu metabox. Ahora es un buen momento para añadir algunos datos de prueba.

Añadir campos a tu tema

Ahora que has creado tus grupos de campos y tienes algunos datos de prueba, puedes comenzar a mostrar los datos dentro de tu tema o tema hijo.

Puedes utilizar la función estándar de WordPress get_post_meta() con ACF, pero se recomienda que utilices las propias funciones de ACF, ya que este formateará los valores dependiendo del tipo de campo que hayas creado. Vamos a usar la función the_field() de ACF. Esta función muestra el campo personalizado y toma un parámetro del nombre del campo, por ejemplo:

<?php the_field('field_name'); ?>

Abordemos nuestros metadatos. Vamos a tener toda esta información en un solo div.

1

    <div class="reviews-meta"> <ul> <li><?php _e('Year of release', 'movie'); ?>: <?php the_field('movie_year'); ?></li> <li><?php _e('Director', 'movie'); ?>: <?php the_field('movie_director'); ?></li> <li><?php _e('Rating', 'movie'); ?>: <?php the_field('movie_score'); ?>/10</li> <li><a href="<?php the_field('movie_imdb'); ?>" target="_blank"><?php _e('View on IMDb', 'movie'); ?></a></li> </ul> </div>

2

Este código es bastante simple: estamos usando la función _e para internacionalizar nuestras cadenas y hacer eco de ellas, y luego usando el método de ACF the_field() para hacer eco del valor del campo que creamos. Todo esto se ha puesto en una lista desordenada, dentro de un elemento div con una clase reviews-meta, por lo que podemos apuntarlo con nuestro CSS.

Entonces, ¿adónde va este código? En este caso, es mejor crear una nueva plantilla para el tipo de entrada. Para ello, haz una copia del archivo single.php de tu tema y asígnale el nombre single-nombre-del-post.php, en nuestro caso single-movie.php. Cada single.php tendrá un aspecto diferente, pero todos deberían tener una cosa en común: un bucle de WordPress. Tu bucle de WordPress debería tener un aspecto similar al siguiente:

1

    <?php while ( have_posts() ) : the_post(); ?> <?php get_template_part( 'content', 'single' ); ?> <?php endwhile; ?>

2

Los campos personalizados pueden ir fuera del bucle, y dónde los coloques exactamente depende del aspecto que quieres que tenga la página. En mi caso (usando el tema predeterminado Twenty Fourteen), los he puesto justo bajo el bucle y aplicado un estilo básico a la clase CSS .reviews-meta.

Conclusión

Hemos cubierto los conceptos básicos del plugin Advanced Custom Fields. Es decir, hemos añadido algunos campos y ahora los estamos mostrando en nuestro sitio. Sin embargo, hay mucho más en ACF, y solo acabamos de arañar la superficie. Hay muchos más tipos de campos que puedes usar, así como características más avanzadas, como la lógica condicional.

Por favor, no dudes en dejar cualquier pregunta, comentario, ¡y opinión en general a través del siguiente formulario!