Referencia completa para agregar grupos de campos personalizados avanzados y campos por código
El complemento Campos personalizados avanzados (ACF) admite la configuración completa de campos y grupos mediante código PHP en su tema o complemento. Los beneficios de hacer esto es que todos sus campos estarán disponibles independientemente de la instancia de WordPress en la que esté trabajando (por ejemplo, si necesita cambiar entre local, servidor de prueba y servidor en vivo). Puede configurar todos los campos en el administrador de ACF y usar la herramienta de exportación para exportarlo a PHP.
Sin embargo, si hace esto con frecuencia, puede notar que la exportación PHP de ACF contiene una gran cantidad de código que hace que sus archivos PHP sean innecesariamente largos. En algunos casos, es mejor escribir el código usted mismo, con el mínimo necesario, para obtener un código más limpio en su tema o complemento. Esta guía tiene como objetivo brindarle una referencia completa sobre cómo escribir manualmente agregando campos y grupos ACF en PHP. Tenga en cuenta que no entrará en detalles sobre cada tipo de campo, ya que se supone que ya está familiarizado con los diferentes campos posibles en ACF.
Pero primero; algunas precauciones
Para mantener buenos estándares de código y garantizar que su sitio de WordPress no se bloquee, siempre debe verificar si las funciones o clases que usa su código realmente existen. Especialmente cuando se trata de complementos que pueden desactivarse fácilmente o ni siquiera instalarse en un sitio, siempre debe envolver el código específico de su complemento en una prueba if que verifique si las funciones que usa existen, antes de usarlas.
En cuanto a ACF, puede hacerlo comprobando si existe la clase 'acf'o si existe la función para agregar campos y grupos, 'acf_add_local_field_group'. Envuelva cualquiera de ellos alrededor del código a continuación.
if (function_exists('acf_add_local_field_group')) {
// Your ACF specific code here
}
// OR:
if (class_exists('acf')) {
// Your ACF specific code here
}código esqueleto
Para agregar metaboxes (grupos) y campos, usamos el gancho llamado acf/init. Dentro de la función llamamos a la función acf_add_local_field_group()con una matriz como parámetro. Dentro de esa matriz está la configuración completa del grupo y todos sus campos. Las más importantes son las claves de matriz 'fields'y 'location'. Para la clave de matriz 'fields', proporciona la matriz para todos los campos, y para la clave 'location', proporciona la configuración de dónde debe aparecer el metabox. Esta publicación detallará las posibles opciones que tiene para cada uno de estos a continuación.
Esto es lo mínimo para agregar un grupo, además de los campos y la ubicación:
Cada grupo necesita una clave única, pero el nombre real en sí mismo no importa mucho (para nosotros). Si está agregando más grupos, no olvide cambiar el 'key'campo. El título del metabox se puede establecer en el elemento clave de matriz, lo adivinó, 'title'. Si está agregando varios metaboxes en la misma ubicación (por ejemplo, en la edición posterior), puede controlar cuál viene primero al proporcionar diferentes números en 'menu_order'.
Puede controlar el diseño del metabox proporcionando defaulteller seamlessen formato 'style'. Sin embargo, con el nuevo editor de Gutenberg esto tiene mucha menos importancia. Lo mismo ocurre con la clave 'position'donde en los viejos tiempos podías colocar el metabox debajo del contenido de la publicación ('normal'), al costado ('side') o justo después del título de la publicación ('acf_after_title').
¡Bien! Profundicemos en los dos elementos más interesantes de la matriz; comenzando con la ubicación, que define dónde aparece el metabox.
Ubicación
Esto es todo acerca de lo que pones en la llave 'location'. Pero antes de analizar las posibles opciones, debemos comprender su estructura de matriz.
'location'acepta una matriz con una matriz de elementos en una matriz! Sostener. Sí, porque es posible proporcionar y combinar la lógica AND y OR en la ubicación (por ejemplo, "mostrar en la edición de publicaciones, pero no si el tipo de publicación es ‘libro’", o "mostrar en la pantalla de edición de usuarios y también crear una nueva pantalla de usuario, pero para ambos casos no si el rol actual es autor"). La forma en que significa si es un AND o un OR es estructurando las matrices. Es mucho más fácil mostrar que explicar con palabras:
Así es como combina dos elementos de ubicación con la lógica AND (ambos deben ser verdaderos):
Y esto es para combinar ubicaciones con lógica OR (solo una debe ser verdadera):
¿Ver la diferencia?
Bien, sigamos adelante. Cada opción de ubicación consta de una matriz de tres elementos; 'param'que es donde agregamos todas las diferentes ubicaciones, 'operator', y 'value'. El operador es cómo comparar el valor, y puede ser '=='igual o '!='diferente.
Repasemos las posibles opciones una por una.
Ubicación por tipo de publicación
Establezca el tipo de publicación que desee en 'value'. Tenga en cuenta que no puede proporcionar una matriz de varios tipos de publicaciones, debe combinar varias de estas matrices en una configuración AND.
Ubicación por estado de la publicación
Establezca el estado de publicación deseado como 'value'. Nuevamente, tenga en cuenta que no puede proporcionar una matriz de múltiples estados de publicación, deberá proporcionar cada valor deseado en una configuración AND u OR.
Ubicación por plantilla de página
Esto se muestra solo si la página seleccionada (o el tipo de publicación personalizada con soporte de plantilla de página) ha elegido el nombre de plantilla de página proporcionado.
Ubicación por término taxonómico asignado
Esta ubicación es para cuando una publicación tiene asignado un término específico. Deberá proporcionar el nombre de la taxonomía, dos puntos y el slug del término como valor.
Ubicación por tipo de página
ACF agrupa las propiedades especiales de las páginas como "tipo de página". Se trata principalmente de si la página actual es o no una página principal o secundaria, pero también para las páginas de orientación configuradas como página principal de WordPress o página de blog.
Ubicación: taxonomía
Una ubicación para editar o agregar un término en una taxonomía.
Proporcione el nombre de la taxonomía como 'value'. Tenga en cuenta que no puede proporcionar una matriz de múltiples taxonomías, pero puede proporcionar 'all'para orientar todas las taxonomías.
Ubicación: usuario
Esta ubicación es para agregar o editar un perfil de usuario.
Proporcione 'edit‘ para apuntar solo a la pantalla de edición de usuarios existentes, 'register'para apuntar solo al formulario al registrar un nuevo usuario, o ‘ all'para ambos de los anteriores.
Desde ACF 5.6, también puede agregar grupos de campos a los elementos del menú.
Puede configurar valuepara allaplicar el grupo a todos los elementos del menú, o puede especificar menús por ubicación (ubicaciones registradas en su tema) o por ID de menú. Para uso de ubicación 'location/<name>', por lo que para una ubicación llamada ‘ primary‘ puede establecer un valor 'location/primary'para aplicar su grupo a un menú asignado solo a esta ubicación. Si desea apuntar a un ID de menú específico, establezca el valor en una cadena de ese ID.
Ubicación: widget
ACF incluso le proporciona una ubicación dentro de la configuración del widget sin modificar el código central del widget.
Puede apuntar a todos los widgets con 'all'como 'value', o apuntar a un widget específico. Necesitará saber el "ID interno" del widget con el que están registrados.
Ubicación: página de opciones de ACF (solo Pro)
Con ACF Pro puede usar ACF para configurar páginas de administración personalizadas.
Proporcione el nombre que estableció en acf_add_options_page‘s menu_slugas 'value'.
Ubicación: bloque (solo Pro 5.8+)
ACF Pro (5.8+) tiene una función para agregar bloques de Gutenberg con campos de ACF y controlar su salida con PHP. Bastante ingenioso para aquellos que aún no se han sumergido en agregar bloques personalizados de Gutenberg y el Javascript requerido.
Campos
Ahora estamos entrando en la parte más interesante; los campos mismos. ACF ofrece una (realmente) amplia gama de tipos de campo, y lo reiteraré; esta guía no le muestra qué es cada campo y cómo funcionan o cómo se ven.
En la matriz principal que proporciona 'fields', acf_add_local_field_group()proporciona una matriz donde cada campo es su propia matriz.
El mínimo absoluto requerido para cada campo es el siguiente: un único 'key'que puede ser cualquier cosa que desee y probablemente nunca necesite consultarlo. También necesita 'name'cuál es la clave meta (publicación, usuario, término) en la que se guarda el valor del campo, y esta es la clave a la que se referirá cuando obtenga el valor de los campos. Debe proporcionar un 'label'y finalmente el crucial 'type'que define qué tipo de campo estamos manejando. El resto de los campos depende de 'type'como veremos cuando analicemos cada tipo de campo a continuación.
Este es el código esqueleto para agregar un campo.
Tenga en cuenta que necesitará lo anterior para cada campo, pero para no repetir el mismo código, cada tipo de campo a continuación solo incluirá 'type'y cualquier otro elemento necesario para ese tipo de campo.
Campo: entrada de texto
El campo más simple de todos. Todo lo que realmente necesitamos es:
Pero para personalizar aún más su entrada de texto, también puede proporcionar cualquiera de los siguientes:
Campo: Entrada de número
Campo: área de texto
Campo: Control deslizante de rango
Campo: Contraseña
Igual que la entrada de texto, excepto que todo lo que escriba en él se cubrirá con * como es de esperar en un campo de contraseña.
Campo: Imagen
Selección de una sola imagen.
Campo: Archivo
Similar a la imagen de arriba, excepto que no muestra una vista previa del archivo.
También puede proporcionarlo 'mime_types' => '',y configurarlo, por ejemplo, 'pdf,docx'para que solo permita archivos PDF y DOCX.
Campo: Editor WYSIWYG
WYSIWYG es un editor de "Lo que ves es lo que obtienes", con el que estábamos familiarizados antes de que llegara Gutenberg (TinyMCE).
El parámetro 'media_upload'y 'delay'puede ser 1 (verdadero) o 0 (falso).
Campo: Seleccionar
Campo: casilla de verificación
Tenga en cuenta que 'default_value'puede ser una matriz de múltiples opciones.
Campo: Botón de opción
La configuración 'other_choice'en verdadero agrega un botón de opción adicional con la etiqueta "Otro" con una entrada de texto donde el usuario puede escribir algo.
Campo: Verdadero/falso (alternar)
El 'ui_on_text'y 'ui_off_text'solo es válido si 'ui'es 1, ya que están definiendo lo que debería aparecer en el selector de interfaz de usuario especial.
Campo: Enlace
Le da un botón para ingresar un enlace, ya sea escribiendo o eligiendo contenido en su sitio de WordPress (debe estar familiarizado al agregar un enlace en el editor normal de WordPress).
Campo: Publicar objeto
Da un cuadro de selección donde puede elegir contenido de WordPress. La selección le permite buscar escribiendo y todo el contenido se divide por tipo de publicación. Puede permitir que se elijan varias publicaciones o solo una.
Campo: Relación
Campo: Elija términos en una taxonomía
El selector de términos de taxonomía tiene cuatro "modos" o tipos diferentes donde dos de ellos permiten múltiples opciones.
Campo: Seleccionar usuario
Campo: Google Maps
Tenga en cuenta que debe proporcionar una clave API de GoogleMaps válida a ACF para que este campo funcione, así:
add_filter('acf/fields/google_map/api', function($api) {
$api['key'] = 'YOURAPIKEY';
return $api;
});Campo: Selector de fecha
Campo: Selector de fecha y hora
Campo: Selector de tiempo
Campo: Selector de color
Campo: Galería (solo ACF Pro)
Tipos especiales de campos.
ACF también ofrece algunos tipos de campos que no guardan un valor per se, pero son más para fines organizacionales. Para todos estos establecidos 'name'en una cadena vacía.
Mensaje HTML
Si necesita simplemente imprimir algo de HTML sin que realmente guarde un valor, puede usar type 'message'.
Repetidor (solo ACF Pro)
Un repetidor contiene una serie de campos que se pueden repetir.
El elemento sub_fieldsespera una matriz de campos, tal como configuró los campos arriba.
Conclusión
Esta no es una guía exhaustiva, ya que ACF ofrece una amplia gama de opciones y personalizaciones. Pero debería cubrir las opciones más utilizadas y los casos de uso personalizados. Personalmente, me encuentro refiriéndome a esto con bastante frecuencia cada vez que agrego campos ACF para clientes. E incluso para las opciones más extrañas, esta guía es suficiente para no tener que inflar mis archivos PHP con el código de exportación de ACF. ¡Espero que esto haya sido útil para ti también!