Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Modo de Plantilla Visual te permite diseñar una única campaña utilizando el Creador de Campañas Visuales de Charitable: arrastra bloques, define la tipografía, coloca un muro de donantes, añade una tira de patrocinadores.

A continuación, puedes hacer que *cada* recaudador de fondos de embajador herede ese diseño, personalizado para cada embajador.

• Su nombre donde se encuentran los marcadores de posición.
• Su historia donde se encuentra el bloque de historia de la plantilla.
• Su imagen donde se encuentra la imagen principal de la plantilla.
• Su progreso frente a su objetivo donde se encuentra la barra de progreso de la plantilla.

Es la diferencia entre que todos los recaudadores de fondos se vean iguales (aburrido) y que todos los recaudadores de fondos se vean *consistentes* (dentro de la marca). La plantilla es la capa de marca; el contenido del embajador completa los detalles.

Cuándo usarlo

• Eventos patrocinados: el patrocinador de nivel oro de la maratón quiere su logotipo en la página de cada embajador. La plantilla contiene el bloque del logotipo; cada recaudador de fondos lo hereda.
• Programas de marca estrictos: tu equipo de identidad visual quiere un control estricto sobre cómo se renderiza cada página. Diseña una vez; bloquéalo.
• Pruebas A/B: clona la plantilla, edita el texto, cambia qué plantilla está activa; cada recaudador de fondos cambia en tiempo real.
• Causas cinematográficas: campañas conmemorativas, recaudaciones de fondos para galas: la misma imagen principal, la misma paleta de colores, el mismo ritmo emocional en cada embajador.

Encontrar las Plantillas Visuales

En tu administrador de WordPress, ve a Charitable » Embajadores » Plantillas

La subpestaña Plantillas tiene tres grupos de configuración:

1. Estilo de Plantilla Front-end: el selector Heredado / Mejorado / Visual. Aquí es donde activas el modo Visual.
2. Campaña de Plantilla de Recaudación: el selector de campaña que elige qué campaña existente actúa como plantilla. Solo se muestra cuando se selecciona Visual.
3. Plantilla Front-end: el selector de variante de diseño (igual que la subpestaña Página de Recaudación). Cuando se configura una campaña de plantilla, esto es solo informativo: la plantilla prevalece.

Elegir un Estilo de Plantilla Front-end

Tres modos, cada uno progresivamente más capaz:

Modo	Renderiza las páginas de recaudación con…
Legado	Las plantillas originales de la versión 1.x. CSS y marcado sin cambios. Elige esto si has personalizado plantillas o CSS y no quieres que nada cambie.
Mejorado	Las plantillas de la versión 3.0 (barras de progreso, estadísticas con iconos, ventana emergente para compartir, búsqueda) sobre las páginas existentes. Utiliza el selector de diseño de Página de Recaudación para la forma.
Visual	Cada página de recaudación se renderiza a partir de un diseño del Creador de Campañas Visuales que elijas a continuación. Máximo control.

Puedes cambiar entre modos en cualquier momento. Volver a Heredado no pierde ninguna configuración guardada: el puntero de la campaña de plantilla del modo Visual se conserva para que puedas volver más tarde.

Elegir una Campaña de Plantilla

Una vez seleccionado Visual, aparece el selector Campaña de Plantilla de Recaudación.

El selector funciona con autocompletado: empieza a escribir el título de tu plantilla, elige entre los resultados. Solo ofrece campañas que:

• Se han abierto en el Generador de Campañas Visuales (tienen `campaign_settings_v2` post-meta).
• No son la recaudación de fondos que estás a punto de renderizar (sin bucle infinito).
• Pasan cualquier filtro `charitable_ambassadors_onboarding_visual_template_candidates` que hayas añadido.

Elige uno, guarda y el modo Visual está activo. Cada recaudación de fondos de embajador en tu sitio ahora se renderiza usando el diseño de esa campaña.

Cómo funciona la sustitución

Cuando un visitante carga una página de recaudación de fondos de embajador, Embajadores intercepta el filtro `get_post_metadata` para la clave meta `campaign_settings_v2` de la campaña. Esto es lo que sucede:

1. Pro solicita los datos del generador `campaign_settings_v2` de la recaudación de fondos.
2. Embajadores comprueba: ¿estamos en modo Visual? ¿Hay una plantilla configurada? ¿Es una página de recaudación de fondos (no la plantilla en sí)? ¿Tiene esta recaudación de fondos sus propios datos de generador (si es así, los datos propios de la recaudación de fondos prevalecen)?
3. Si se cumplen todas las condiciones, Embajadores clona en profundidad el `campaign_settings_v2` de la plantilla, reescribe `id` al ID de la recaudación de fondos y `title` al título de la recaudación de fondos.
4. Cada cadena de datos clonados se procesa a través del **sustituidor de tokens**: cualquier `{ambassador_name}`, `{parent_title}`, `{percent_raised}`, etc., se reemplaza con los valores reales de la recaudación de fondos.
5. Pro lee los datos sustituidos y renderiza. Cada bloque dinámico (formulario-donar, barra-progreso, muro-donantes) se enlaza al ID de la recaudación de fondos en el momento de la renderización.

El resultado: una página de recaudación de fondos que se ve exactamente como la plantilla, pero con el contenido del embajador correcto.

Tokens disponibles

Puedes usar cualquiera de estos tokens en los campos de texto de la plantilla, texto alternativo, subtítulos, etc.:

Token	Sustituido con
{title}	El título de la publicación de la recaudación de fondos.
{ambassador_name}	El nombre para mostrar del autor.
{parent_title}	El título de la campaña principal.
{parent_url}	El permalink de la campaña principal.
{goal}	El importe del objetivo de la recaudación de fondos (formateado).
{raised}	El importe recaudado por la recaudación de fondos (formateado).
{donor_count}	El número de donantes únicos.
{percent_raised}	Progreso como porcentaje (p. ej. 42%).
{fundraiser_image}	URL de la imagen destacada.

Colócalos en cualquier lugar del contenido de texto de la plantilla. Por ejemplo, un encabezado principal de “Ayuda a {ambassador_name} a alcanzar su meta de {goal}” se convierte en “Ayuda a Sarah Chen a alcanzar su meta de 5.000 $” en la recaudación de fondos de Sarah, “Ayuda a Marcus Liu a alcanzar su meta de 2.500 $” en la de Marcus.

Anulaciones por recaudación de fondos

Una recaudación de fondos puede optar por no participar en la plantilla al tener su propia meta campaign_settings_v2. Si tú (o el embajador) abres una recaudación de fondos específica en el Generador de Campañas Visuales y la guardas, los datos de esa recaudación de fondos prevalecen a partir de entonces; la plantilla ya no se aplica a ella.

Para restaurar el diseño de la plantilla en una recaudación de fondos que ha seguido su propio camino: elimina la meta post campaign_settings_v2 en esa recaudación de fondos:

delete_post_meta( $fundraiser_id, 'campaign_settings_v2' );

La próxima carga de página volverá a aplicar la plantilla.

Los bloques dinámicos siguen funcionando

Aunque la estructura de la plantilla se clona en cada recaudación de fondos, los bloques dinámicos como el formulario de donación, la barra de progreso y el muro de donantes todavía se enlazan al ID de la recaudación de fondos en el momento de la renderización. Por lo tanto:

• La barra de progreso muestra el progreso de la recaudación de fondos, no el de la plantilla.
• El formulario de donación publica en la campaña de la recaudación de fondos.
• El muro de donantes enumera los donantes de la recaudación de fondos, no los de la plantilla.

Esto es lo que hace que el modo Visual funcione: el diseño se comparte, pero los datos son por recaudación de fondos.

Enlaces sociales

Si la plantilla incluye un bloque de Enlaces Sociales, ese bloque se convierte en los identificadores sociales del embajador (extraídos de los campos de su perfil de usuario). Los embajadores que no han completado sus identificadores sociales obtienen un bloque de Enlaces Sociales vacío, por lo que mostramos una advertencia en el administrador si tu plantilla incluye Enlaces Sociales pero la finalización del perfil del embajador es baja.

Qué plantilla de embajador muestra qué

Embajadores Benéficos tiene dos capas de control de plantillas en Embajadores → Plantillas:

1. Estilo de Plantilla Frontend — el motor general:
   • Legado — las plantillas y CSS originales, sin cambios. La configuración de la Página de Recaudación de Fondos (QR, muro de donantes, ventana emergente para compartir, etc.) no se aplica aquí.
   • Mejorado — plantillas modernas con imagen principal, barra de progreso, estadísticas de iconos, compartir y buscar. Recomendado para la mayoría de las instalaciones. Se aplica la configuración de la Página de Recaudación de Fondos.
   • Visual — utiliza una campaña que hayas creado en el Generador Visual como plantilla.
2. Plantilla Frontend — cuando el estilo es Mejorado, esto elige el diseño. Cada diseño renderiza una mezcla diferente de elementos. Utiliza la siguiente tabla para elegir la que mejor se adapte.

Comparación de características de la plantilla mejorada

Plantilla	Código QR (cuando está habilitado)*	Imagen principal	Barra de progreso	Estadísticas de iconos	Muro de donantes	Donar tarjeta	Navegación fija	Mejor para
Clásico	Pegatina en esquina + ventana emergente para compartir	Sí	Sí	Sí	Sí	Barra lateral derecha	No	Un diseño limpio y familiar de héroe + historia + donación
Prioridad de la historia	Pegatina en esquina + ventana emergente para compartir	Sí	Sí	Sí	Sí	Banda de conversión en la parte inferior	No	Campañas narrativas
Prioridad de las estadísticas	Pegatina en esquina + ventana emergente para compartir	Sí (corto)	Sí	Sí	Sí	Superposición en el héroe	No	Liderando con progreso y números
Prioridad de la donación	Pegatina en esquina + ventana emergente para compartir	Sí (banner)	Sí	Sí	Sí	En línea, encima de la historia	No	Maximizando conversiones; historia colapsada
Revista	Pegatina en esquina + ventana emergente para compartir	Sí (cinemático)	Sí	Sí	Sí (arriba o abajo)	Banda de estadísticas debajo de la historia	No	Sensación editorial / premium
Exhibición	Pegatina en esquina + ventana emergente para compartir	Sí	Sí	Sí	Sí	Banda de estadísticas	Sí	Prioridad de imagen, navegable (con pestañas)
Póster de exhibición	Pegatina en esquina + ventana emergente para compartir	Sí (alto)	Sí	Sí	Sí (por niveles)	Banda en línea	FAB flotante	Páginas visuales grandes tipo "póster"
Concentración	Tarjeta QR insertada + Ventana emergente para compartir	Sí	Sí	Sí	Sí	Widget pequeño (derecha)	No	Compartir en persona; QR destacado en la página

* Activa Embajadores → Plantillas → Página de recaudación → "Mostrar código QR en la página de recaudación" para mostrar el QR. Cuando está desactivado, no aparece ningún QR en ninguna plantilla.

Cómo aparece el código QR

Con "Mostrar código QR en la página de recaudación" activado, cada plantilla mejorada muestra el QR, con la ubicación adaptada a su diseño:

• Rally presenta el QR como una gran tarjeta insertada en la barra lateral, la ubicación más destacada.
• Todas las demás plantillas mejoradas muestran una pegatina QR "Escanear" compacta fijada en la esquina superior derecha de la tarjeta de recaudación.
• Todas las plantillas mejoradas también incluyen una tarjeta QR dentro de la ventana emergente para compartir (haz clic en Compartir → Código QR) para obtener un PNG descargable.

Así que ya no tienes que elegir Rally solo para obtener un QR: elige el diseño que más te guste y activa la configuración.

Notas: Cambiar la plantilla solo afecta al diseño de la página pública de recaudación, no a tus datos. Cambia libremente y usa Vista previa para comparar. El QR está desactivado por defecto; activarlo es una configuración de un solo clic.

Consejos

• Empieza con un diseño mejorado; en la mayoría de los casos no necesitarás el Visual. Usa una de las 8 variantes mejoradas como base "suficientemente buena"; pasa a Visual cuando tengas un patrocinador o una razón de marca para necesitar el máximo control.
• La plantilla es solo una campaña. Puedes previsualizar la plantilla directamente; tiene su propio permalink, como cualquier campaña. Visita la URL sin iniciar sesión para ver exactamente lo que verán los embajadores (con el contenido propio de la plantilla, no sustituido).
• Usa tokens para todo lo que tenga mucho texto. No codifiques "Ayuda a Sarah" en la plantilla; usa Ayuda {ambassador_name} para que la plantilla siga siendo genérica.
• No pongas la plantilla en tu navegación principal. Es una "fuente de diseño" interna que no debería ser localizable como una recaudación real. Configura _wp_old_slug o noindex.

---

Referencia del desarrollador

El resto de esta página es para desarrolladores que personalizan el Modo de Plantilla Visual.

Almacenamiento de ajustes

charitable_settings > ambassadors > ambassadors_ui_version          # 'legacy' | 'enhanced' | 'visual'
charitable_settings > ambassadors > p2p_template_campaign_id        # int (0 = none)
charitable_settings > ambassadors > ambassadors_enhanced_layout_variant  # used for Enhanced; informational under Visual

Ayudantes:

charitable_ambassadors_ui_version();                                // 'legacy' | 'enhanced' | 'visual'
charitable_ambassadors_should_use_p2p_template( $fundraiser_id );   // bool
charitable_ambassadors_substitute_p2p_tokens( $string, $fundraiser_id ); // string
charitable_ambassadors_fundraiser_template_is_theme_overridden();   // bool

Puerta de sustitución

La sustitución solo se activa cuando TODAS estas condiciones son verdaderas:

1. ambassadors_ui_version === 'visual'.
2. p2p_template_campaign_id > 0.
3. La publicación solicitada es una recaudación publicada (un hijo de un padre habilitado para peer-to-peer).
4. La recaudación NO es la plantilla en sí.
5. La recaudación no tiene metadatos campaign_settings_v2 propios (comprobación de $wpdb en bruto para evitar recursión de filtros).
6. La plantilla SÍ tiene metadatos campaign_settings_v2.
7. La solicitud no es un contexto de administrador (para que el Constructor Visual pueda editar los metadatos de una recaudación de forma normal).

Si alguna puerta es falsa, la sustitución es una operación nula y Pro lee los propios metadatos del recaudador de fondos (o recurre a la representación heredada).

El gancho de sustitución

add_filter( 'get_post_metadata', [ self::class, 'maybe_substitute_p2p_template' ], 10, 4 );

El manejador del filtro:

1. Devuelve anticipadamente en las puertas anteriores.
2. Lee los metadatos campaign_settings_v2 de la plantilla directamente a través de $wpdb (sin recursión de filtros).
3. Clona profundamente los datos, reescribe id/title.
4. Recorre recursivamente cada hoja de cadena y ejecuta cada una a través del sustituto de tokens.
5. Devuelve la matriz clonada y sustituida como si fueran los propios metadatos del recaudador de fondos.

Filtros

Filtro	Predeterminado	Propósito
charitable_ambassadors_p2p_template_tokens	matriz de 9	Añade tokens personalizados al sustituto. Recibe ($tokens, $fundraiser_id).
charitable_ambassadors_should_use_p2p_template	booleano calculado	Fuerza la activación o desactivación de la sustitución para un recaudador de fondos específico. Recibe ($should, $fundraiser_id).
charitable_ambassadors_p2p_template_campaign_id	valor de configuración	Anula el ID de la plantilla en tiempo de ejecución (por ejemplo, para una plantilla por padre).
Candidatos a plantillas visuales de incorporación de embajadores benéficos	calculado	Qué campañas aparecen en el autocompletado del selector de administración.

Acciones

Acción	Argumentos	Se dispara cuando
charitable_ambassadors_p2p_template_applied	$fundraiser_id, $template_id	Sustitución confirmada para la representación de un recaudador de fondos.

Registro de tokens

add_filter( 'charitable_ambassadors_p2p_template_tokens', function ( $tokens, $fundraiser_id ) {
    $author = get_user_by( 'id', get_post_field( 'post_author', $fundraiser_id ) );
    $tokens['{ambassador_city}'] = $author ? (string) get_user_meta( $author->ID, 'billing_city', true ) : '';
    return $tokens;
}, 10, 2 );

Capacidades

Acceso a la configuración: manage_charitable_settings. La representación en el front-end no tiene puerta de capacidad.

Compatibilidad

Cuando está activa una versión de Pro anterior al soporte del creador de campañas, el selector está limitado y el modo Visual recurre a la representación Mejorada. La comprobación se implementa en charitable_ambassadors_visual_mode_is_available().

Ejemplos de personalización

Usar una plantilla por padre (cada campaña padre tiene su propia plantilla):

add_filter( 'charitable_ambassadors_p2p_template_campaign_id', function ( $template_id ) {
    $fundraiser_id = get_the_ID();
    $parent_id     = (int) get_post_meta( $fundraiser_id, '_campaign_parent', true );
    if ( $parent_id ) {
        $per_parent = (int) get_post_meta( $parent_id, '_ambassadors_template_campaign_id', true );
        if ( $per_parent > 0 ) {
            return $per_parent;
        }
    }
    return $template_id;
} );

Añade un token {donate_url}:

add_filter( 'charitable_ambassadors_p2p_template_tokens', function ( $tokens, $fundraiser_id ) {
    $tokens['{donate_url}'] = add_query_arg( 'donate', '1', get_permalink( $fundraiser_id ) );
    return $tokens;
}, 10, 2 );

Omitir el modo Visual para los recaudadores de fondos en un término específico (por ejemplo, migración heredada):

add_filter( 'charitable_ambassadors_should_use_p2p_template', function ( $should, $fundraiser_id ) {
    if ( has_term( 'legacy-migration', 'campaign_tag', $fundraiser_id ) ) {
        return false;
    }
    return $should;
}, 10, 2 );

Restringir el selector de plantillas a una categoría específica:

add_filter( 'charitable_ambassadors_onboarding_visual_template_candidates', function ( $candidates ) {
    return array_filter( $candidates, function ( $candidate ) {
        return has_term( 'p2p-templates', 'campaign_category', $candidate['id'] );
    } );
} );

Relacionado

• Página de recaudación de fondos: el selector de diseño que se utiliza cuando el modo Visual no está activo.
• Variantes de diseño: las 8 variantes integradas que utiliza Enhanced.
• Características de visualización: la orientación de la pestaña Plantillas.
• Temas: el color de acento principal también fluye hacia el modo Visual.
• Hooks y filtros en Embajadores: referencia completa.