Custom ACF

Un plugin de WordPress ligero y de código abierto para crear y gestionar campos personalizados — una alternativa desde cero a Advanced Custom Fields (ACF).

Características

• Constructor de Grupos de Campos (Field Group Builder) — Crea grupos de campos con una interfaz de administración de arrastrar y soltar.
• Múltiples Tipos de Campos — Campos de Texto, Imagen y Galería listos para usar.
• Motor de Reglas de Ubicación (Location Rules Engine) — Controla qué tipos de contenido (post types) muestran cada grupo de campos mediante lógica es igual a / no es igual a.
• Integración con la Biblioteca de Medios — Los campos de Imagen y Galería utilizan la biblioteca nativa de WordPress.
• Gestión Nativa de Post Types — Registra Custom Post Types directamente desde el plugin, eliminando dependencias de plugins externos y conflictos de orden de carga.
• Integración con Elementor Pro — Los campos están disponibles como Dynamic Tags en cualquier widget de Elementor (texto, imagen, galería/carrusel). Resuelve correctamente el contexto del post en el frontend.
• API para Desarrolladores — Funciones de plantilla sencillas: get_custom_field() y the_custom_field().
• Sin Tablas Personalizadas — Todos los datos se guardan en las tablas estándar wp_posts y wp_postmeta.
• Desinstalación Limpia — Elimina todos los datos del plugin al desinstalarlo.

Requisitos

• WordPress 5.0+
• PHP 8.0+

Instalación

Método 1: Subir el archivo ZIP a través del Escritorio de WordPress (Recomendado)

1. Descarga el repositorio como archivo ZIP desde GitHub (haz clic en el botón verde Code y selecciona Download ZIP).
2. Ve al panel de administración (Escritorio) de tu WordPress.
3. Dirígete a Plugins → Añadir nuevo plugin.
4. Haz clic en el botón Subir plugin en la parte superior de la página.
5. Selecciona el archivo ZIP descargado y haz clic en Instalar ahora.
6. Una vez instalado, haz clic en Activar plugin.

Método 2: Instalación Manual vía FTP o Servidor Local

1. Descarga el repositorio como archivo ZIP desde GitHub.
2. Extrae el archivo ZIP y renombra la carpeta extraída a custom-acf.
3. Sube la carpeta custom-acf al directorio de tu instalación de WordPress en /wp-content/plugins/.
4. Inicia sesión en el panel de administración de tu WordPress, ve a Plugins → Plugins instalados y haz clic en Activar bajo Custom ACF.

Método 3: A través de la Línea de Comandos de Git

1. Abre tu terminal y navega hasta el directorio de plugins de tu WordPress:

   cd /ruta/a/wordpress/wp-content/plugins/

2. Clona el repositorio en una carpeta llamada custom-acf:

   git clone https://github.com/tu-usuario/custom-acf.git custom-acf

3. Dirígete a Plugins → Plugins instalados en el panel de administración de tu WordPress y haz clic en Activar bajo Custom ACF.

Uso

1. Crear un Grupo de Campos

1. Ve a Campos Personalizados (Custom Fields) → Grupos de campos (Field Groups) → Añadir nuevo.
2. Dale un título al grupo de campos (ej. "Detalles del Producto").
3. En la sección Campos (Fields), haz clic en Añadir Campo para crear campos:
   • Etiqueta del Campo (Field Label) — Nombre legible mostrado a los editores (ej. "Imagen del Producto").
   • Nombre del Campo (Field Name) — La clave meta utilizada en el código, auto-generada a partir de la etiqueta (ej. imagen_del_producto). También puedes escribir una clave personalizada.
   • Tipo de Campo (Field Type) — Elige entre Texto, Imagen o Galería.
4. Puedes arrastrar y soltar los campos por su manejador (☰) para reordenarlos.
5. Haz clic en el icono de papelera para eliminar un campo.

2. Definir Reglas de Ubicación

En la sección Reglas de Ubicación (Location Rules), define dónde debe aparecer este grupo de campos:

1. Haz clic en Añadir Regla.
2. Selecciona el parámetro (actualmente Post Type), el operador (es igual a / no es igual a) y el valor (ej. Páginas).
3. Añade múltiples reglas — se combinan con lógica Y (AND) (todas deben cumplirse).
4. Si no se definen reglas, el grupo de campos no aparecerá en ninguna pantalla de edición de entradas.

3. Introducir Datos

1. Ve a cualquier entrada o página que cumpla con las reglas de ubicación.
2. Verás el grupo de campos representado como una caja meta (meta box) debajo del editor.
3. Rellena los campos:
   • Texto — Escribe directamente en el campo.
   • Imagen — Haz clic en Seleccionar Imagen para abrir la Biblioteca de Medios. Haz clic en Eliminar Imagen para limpiar.
   • Galería — Haz clic en Añadir Imágenes a la Galería para seleccionar múltiples imágenes. Arrastra las miniaturas para reordenarlas. Pasa el cursor sobre una miniatura y haz clic en × para eliminar imágenes individuales, o haz clic en Limpiar Galería para eliminar todas.
4. Haz clic en Actualizar / Publicar para guardar.

4. Mostrar Campos en Plantillas

Utiliza las funciones de la API para desarrolladores en los archivos de plantilla de tu tema:

get_custom_field( $field_key, $post_id )

Obtiene el valor crudo (sin procesar) de un campo personalizado.

// Dentro del bucle (The Loop) - detecta automáticamente el ID del post actual
$subtitulo = get_custom_field( 'subtitle' );

// Con un ID de post explícito
$subtitulo = get_custom_field( 'subtitle', 42 );

// El campo de imagen devuelve el ID del archivo adjunto (attachment ID)
$image_id = get_custom_field( 'hero_image' );
$url = wp_get_attachment_image_url( $image_id, 'large' );

// El campo de galería devuelve un array de IDs de archivos adjuntos
$gallery_ids = get_custom_field( 'photo_gallery' );
foreach ( $gallery_ids as $id ) {
    echo wp_get_attachment_image( $id, 'medium' );
}

the_custom_field( $field_key, $post_id )

Imprime (con echo) la salida formateada de un campo personalizado. Maneja automáticamente el renderizado según el tipo de campo:

• Texto — Muestra la cadena escapada.
• Imagen — Muestra una etiqueta <img> completa mediante wp_get_attachment_image().
• Galería — Muestra una secuencia de etiquetas <img> para cada imagen en la galería.

<!-- Texto -->
<h2><?php the_custom_field( 'subtitle' ); ?></h2>

<!-- Imagen -->
<div class="hero">
    <?php the_custom_field( 'hero_image' ); ?>
</div>

<!-- Galería -->
<div class="gallery">
    <?php the_custom_field( 'photo_gallery' ); ?>
</div>

5. Gestionar Post Types (Nuevo)

Cuando tus campos están condicionados a un Custom Post Type creado por otro plugin, pueden surgir conflictos de orden de carga en el hook init que hacen que Elementor pierda el contexto del post. Para solucionarlo, puedes absorber la creación del Post Type dentro de este plugin:

1. Ve a Campos Personalizados (Custom Fields) → Post Types.
2. Rellena los campos:
   • Post Type Slug — El identificador del CPT (ej. pruebas_2). Debe coincidir exactamente con el slug del CPT externo.
   • Singular Label — El nombre singular (ej. "Prueba").
   • Plural Label — El nombre plural (ej. "Pruebas").
3. Haz clic en Registrar Post Type.
4. Desactiva el plugin externo que creaba el CPT originalmente (o simplemente déjalo activo — si ambos intentan registrar el mismo slug, el primero en ejecutarse gana, y Custom ACF se registra en prioridad 5).

Nota: Los CPTs gestionados se registran en el hook init con prioridad 5, antes que la mayoría de los plugins (que usan la prioridad 10 por defecto). Esto garantiza que el CPT exista antes de que Elementor y otros plugins inicialicen sus componentes.

6. Usar con Elementor Pro (Dynamic Tags)

Si tienes Elementor Pro instalado, los campos de Custom ACF estarán disponibles automáticamente como Dynamic Tags en cualquier widget compatible.

1. Abre la página o entrada con el editor de Elementor.
2. Selecciona un widget (ej. Encabezado, Imagen, Carrusel de Imágenes).
3. Haz clic en el icono de Dynamic Tags (🔄) junto al campo del widget.
4. Busca el grupo Custom ACF y selecciona el tag correspondiente:
   • Custom ACF Text Field — Para widgets de texto, encabezados, botones, enlaces, etc.
   • Custom ACF Image Field — Para widgets de imagen, fondos, etc.
   • Custom ACF Gallery Field — Para widgets de carrusel de imágenes o galería.
5. En el desplegable Field Name, selecciona el campo que deseas mostrar.
6. El widget mostrará dinámicamente el valor del campo para cada entrada.

Nota: La integración se activa automáticamente al detectar Elementor Pro. Si Elementor Pro no está instalado, el plugin funciona normalmente sin esta característica.

Importante: Los Dynamic Tags de imagen y galería utilizan el Attachment ID internamente, no URLs. El plugin ya almacena las imágenes como IDs de adjuntos, lo cual es el formato que Elementor requiere.

Referencia de Tipos de Campos

Tipo	Valor Guardado	Retorno de get_custom_field()	Salida de the_custom_field()
text	String	string	Texto escapado
image	ID del Adjunto	int	Etiqueta <img> (tamaño completo)
gallery	Array de IDs de Adjuntos	array de int	Múltiples etiquetas <img> (completo)

Estructura de Archivos

custom-acf/
├── custom-acf.php                        # Punto de entrada del plugin
├── uninstall.php                         # Limpieza en desinstalación
├── PLAN.md                               # Plan de implementación
├── README.md                             # Este archivo (Español)
├── README_ENG.md                         # Versión en inglés
├── admin/
│   ├── css/
│   │   └── admin.css                     # Estilos de la interfaz de admin
│   └── js/
│       ├── builder.js                    # Interacciones del constructor de grupos de campos
│       └── renderer.js                   # Interacciones de galería y medios
└── includes/
    ├── class-custom-acf.php              # Orquestador principal
    ├── class-custom-acf-api.php          # API para desarrolladores (get/the_custom_field)
    ├── class-custom-acf-builder.php      # UI de creación y lógica de guardado de grupos
    ├── class-custom-acf-cpt.php          # Registro de CPT y menú de administración
    ├── class-custom-acf-target-cpt.php   # Gestión nativa de Post Types destino
    ├── class-custom-acf-elementor.php    # Integración con Elementor Pro
    ├── class-custom-acf-evaluator.php    # Motor de reglas de ubicación
    ├── class-custom-acf-renderer.php     # Renderizado de campos en posts destino
    └── elementor/
        ├── trait-custom-acf-tag-helpers.php      # Helpers compartidos para tags
        ├── class-custom-acf-tag-text.php         # Dynamic Tag: Texto
        ├── class-custom-acf-tag-image.php        # Dynamic Tag: Imagen
        └── class-custom-acf-tag-gallery.php      # Dynamic Tag: Galería

Arquitectura

Modelo de Datos

Qué	Dónde se Guarda	Clave Meta (Meta Key)
Grupos de Campos	Custom Post Type custom_field_group	—
Definiciones de Campo	Metadatos del post del grupo de campos	_custom_acf_fields
Reglas de Ubicación	Metadatos del post del grupo de campos	_custom_acf_location_rules
Datos del Usuario	Metadatos del post/página de destino	{field_name} (ej. subtitle)

Seguridad

• Verificación de Nonce en todos los envíos de formularios (tanto constructor como renderizador).
• Verificación de Capacidades (edit_post) antes de guardar cualquier dato.
• Protección de Autoguardado (Autosave) para evitar la corrupción de datos durante autoguardados.
• Sanitización de Entradas — sanitize_text_field() para texto, absint() para IDs, y validación contra lista blanca de tipos.
• Escapado de Salidas — Uso constante de esc_html(), esc_attr(), wp_kses_post().
• Lista blanca de tipos de campo — Solo se aceptan text, image y gallery al guardar.
• Unicidad de nombres de campo — Los nombres duplicados entre grupos se sufijan automáticamente para evitar colisiones de datos.

Licencia

GPL-2.0+