Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Enviar Campaña es el formulario que tus embajadores completan para crear una recaudación de fondos. Se encuentra detrás del shortcode [charitable_submit_campaign] y los guía a través de tres pasos:

• ¿Elegir el tipo de destinatario (¿estoy recaudando fondos como individuo? ¿un equipo? ¿un miembro de un equipo?)
• Elegir la causa principal para la que están recaudando fondos
• Completar los detalles de la campaña (título, historia, objetivo, imagen)

La versión 3.0 introduce un primer paso de cuadrícula de tarjetas que reemplaza el flujo heredado basado en selecciones. Mismo modelo de datos, experiencia de usuario mucho más amigable: el destinatario se convierte en una selección de tarjeta táctil, la campaña principal se convierte en un selector enriquecido con logotipos y barras de progreso en lugar de un largo menú desplegable.

Cuándo usarlo

• Configuración – el Asistente de Configuración crea automáticamente una página /submit-campaign/ con el shortcode incluido. Visítala una vez para confirmar.
• Vincular embajadores directamente a una causa específica – comparte ?cap_recipient=individual&cap_campaign=42 y el formulario preselecciona esas opciones.
• Tematización – copia la plantilla en tu tema para realizar cambios de diseño en todo el sitio.

Encontrar la Página

/submit-campaign/ (o el slug que hayas usado). La página muestra el formulario para embajadores conectados y solicita iniciar sesión o redirige automáticamente al inicio de sesión (configurable en General » Requerir Cuenta Antes del Envío).

Si también necesitas encontrar la configuración que rige el formulario:

Administrador de WordPress > Benéfico > Embajadores > General

La subpestaña General alberga Tipos de Campaña Disponibles, Selección Predeterminada, Slug de URL del Recaudador de Fondos, Requerir Cuenta Antes del Envío, Requerir Verificación de Correo Electrónico, Aprobar Campañas Automáticamente, Longitud Mínima/Máxima de Campaña y el método de pago.

Cómo Usar Enviar Campaña en Embajadores

Paso 1 – Elige tu destinatario

El primer paso pregunta: *¿para quién es esta recaudación de fondos?* La cuadrícula de tarjetas muestra los tipos de destinatario que tengas habilitados en General » Tipos de Campaña Disponibles:

Tarjeta	Elige si
Individual	El embajador recauda fondos solo. El caso más común.
Equipo	El embajador está creando un nuevo equipo al que se unirán otros embajadores.
Miembro del equipo	El embajador se une a un equipo existente como miembro.

La cuadrícula de tarjetas está limitada por la Versión de UI siendo enhanced o visual. Los sitios que todavía usan el sistema heredado ven el paso original basado en selecciones. La configuración del sitio Selección Predeterminada controla qué tarjeta se preselecciona cuando el formulario se carga por primera vez: el primer tipo habilitado, un tipo específico o “Requerir que el usuario elija” (sin preselección, botón Continuar deshabilitado).

Cuando solo hay una tarjeta habilitada en todo el sitio, el formulario avanza automáticamente más allá del paso 1 – no tiene sentido hacer la pregunta.

Paso 2 – Elige una campaña principal

Si tu sitio tiene varias campañas principales habilitadas para peer-to-peer, el paso 2 es el selector de campañas principales:

El selector muestra una tarjeta por campaña principal disponible con la miniatura, el título, la cantidad recaudada actual frente al objetivo y un botón Seleccionar esta. Hay un campo de búsqueda encima de la cuadrícula para sitios con muchas campañas principales.

El selector funciona con AJAX: consulta un endpoint que devuelve solo las campañas para las que el embajador actual es elegible para recaudar fondos. Eso es importante: excluye campañas inactivas, campañas caducadas y cualquier campaña restringida por charitable_ambassadors_user_can_invite o puertas similares.

Continuar está deshabilitado hasta que se seleccione una campaña principal.

Si el destinatario en el paso 1 era Miembro del equipo, este paso se reemplaza por un selector de equipos que muestra los equipos existentes como tarjetas compactas de “Unirse al equipo”.

Paso 3 – Rellenar detalles de la campaña

El paso 3 es el formulario largo: título, historia, objetivo, fecha de finalización, importes de donación sugeridos, imagen destacada. Este paso es lo que genera el formulario estándar de envío de campañas de Charitable Pro. Respeta todos los Ajustes de Campos configurados en la configuración general de Charitable.

Enviar, y:

• Se crea una nueva publicación de campaña como borrador (o pendiente si Aprobar campañas automáticamente está desactivado).
• Se activa la acción charitable_campaign_submission_save, a la que escucha el manejador de atribución de invitaciones.
• Si Aprobar automáticamente está activado, la recaudación de fondos se publica inmediatamente.
• Si Aprobar automáticamente está desactivado, la recaudación de fondos llega a Moderación para que tu equipo la revise.

Enlaces profundos con cap_recipient y cap_campaign

Puedes pre-rellenar los pasos 1 y 2 añadiendo argumentos de consulta a la URL de envío:

/submit-campaign/?cap_recipient=individual&cap_campaign=42

Argumento	Lo que preselecciona
cap_recipient	individual / equipo / miembro-de-equipo – el tipo de destinatario.
cap_campaign	Un ID de campaña principal. Si es válido, el selector se omite y la campaña principal se bloquea.

Los nombres de los argumentos de consulta se pueden filtrar a través de charitable_ambassadors_submit_form_query_arg_names si necesitas usar nombres diferentes (para compatibilidad con URL heredadas).

La ventana emergente “Reclutar para esta campaña” en Mis Campañas genera URL con exactamente esta forma, por lo que cuando un recluta hace clic en un enlace de invitación, el formulario comienza pre-rellenado con la campaña principal correcta.

El shortcode

[charitable_submit_campaign]

Atributo opcional:

[charitable_submit_campaign parent_id="42"]

Cuando se establece parent_id, el shortcode bloquea la campaña principal al renderizar (idéntico a pasar cap_campaign=42 en la URL).

Archivos de plantilla

Ruta	Se usa cuando
templates/shortcodes/submit-campaign.php	Versión de la interfaz de usuario heredada.
templates/shortcodes/submit-campaign-enhanced.php	Versiones mejoradas + Visual de la interfaz de usuario, cuando la ruta de la cuadrícula de tarjetas está activa.
templates/shortcodes/submit-campaign/.php	Partials por paso referenciados por el shell mejorado.

Ruta de anulación de tema: your-theme/charitable-pro/charitable-ambassadors/submit-campaign-enhanced.php (y los partials por paso).

Elegibilidad y acceso

Configuración	Predeterminado	Efecto
Requerir cuenta antes de enviar	Activado	Los embajadores deben iniciar sesión. Los visitantes que no han iniciado sesión ven un aviso de inicio de sesión con una redirección a la página de envío.
Requerir verificación de correo electrónico	Activado	Los embajadores que no han verificado su correo electrónico ven un aviso de verificación en lugar del formulario.
Campañas de aprobación automática	Desactivado	Si las nuevas presentaciones se publican inmediatamente o van a Moderación.

Si tu sitio es más abierto ("cualquiera puede enviar, ya nos preocuparemos de ello más tarde"), desactiva ambas opciones de Requerir. Si eres más estricto ("solo las cuentas verificadas pueden enviar"), actívalas ambas.

Límite por destinatario

Puedes limitar cuántas recaudaciones de fondos puede tener un solo embajador a la vez a través del filtro charitable_ambassadors_user_max_fundraisers. Cuando se excede, el botón de envío del paso 3 muestra un aviso amistoso "has alcanzado tu límite de recaudación de fondos" en lugar de enviar.

Consejos

• Usa URLs con enlaces profundos en tus correos electrónicos de invitación. No hagas que los embajadores busquen en un selector principal; si ya sabes para qué causa están reclutando, pasa cap_campaign=ID en el enlace.
• La selección predeterminada importa. "El primer tipo habilitado" se siente acogedor; "Requerir que el usuario elija" se siente deliberado. Elige para que coincida con la personalidad de tu programa.
• Aprobación automática para equipos de confianza, manual para el público. ¿Una gala para tus donantes actuales? Aprobación automática. ¿Un p2p público? Moderación manual.
• Lee los datos de tu formulario a través del perfil del Directorio. Cuando necesites saber qué rellenó un embajador, la pestaña Datos del formulario en su perfil muestra todo sin que tengas que iniciar sesión como él.

---

Referencia del desarrollador

El resto de esta página es para desarrolladores que personalizan el formulario de envío.

Shortcode

[charitable_submit_campaign]
[charitable_submit_campaign parent_id="42"]

Clase: Charitable_Ambassadors_Submit_Campaign_Shortcode. El shortcode delega a una instancia de formulario Charitable_Ambassadors_Campaign_Form y su procesador.

Filtros

Filtro	Predeterminado	Propósito
charitable_submit_campaign_shortcode	HTML renderizado	Filtra toda la salida del shortcode.
charitable_ambassadors_use_card_submit_form	calculado	Fuerza la ruta de la cuadrícula de tarjetas activada/desactivada. Devuelve true cuando la versión de la interfaz de usuario es mejorada/visual y no heredada.
charitable_ambassadors_submit_form_query_arg_names	[ 'recipient'=>'cap_recipient', 'campaign'=>'cap_campaign' ]	Renombra los argumentos de consulta utilizados para enlaces profundos.
charitable_ambassadors_step1_expected_total	calculado	Anula el número total de pasos que se muestra en la pastilla "Paso 1 de N" (el get_pages() del formulario no puede ver páginas condicionales registradas posteriormente).
charitable_ambassadors_submit_form_recipient_card_help_url	''	URL para un enlace opcional "Más información" en el texto de ayuda de la tarjeta del destinatario.
embajadores_caritativos_max_recaudadores_usuario	ilimitado	Número máximo de recaudaciones publicadas + pendientes que un solo embajador puede poseer.
campos_usuario_envio_campaña_caritativa	calculado	Campos que se muestran en la sección de campos de usuario del paso 3. Compartido con el formulario Añadir Embajador del Directorio.

Acciones

Acción	Argumentos	Se dispara cuando
formulario_envio_embajadores_caritativos_antes_paso1	–	Justo antes de que se renderice el contenedor del paso 1.
embajadores_caritativos_despues_envio_formulario_paso1	–	Justo después del paso 1.
oculto_shortcode_envio_campaña_caritativa	$form_args	Se renderizó el estado de sesión cerrada / sin permisos en lugar del formulario.
guardar_envio_campaña_caritativa	$data, $campaign_id, $user_id, $form	Disparado por Pro después de que el formulario crea/actualiza una campaña con éxito. El manejador de atribución de invitaciones escucha esto.

Endpoints AJAX

Acción	Propósito
consulta_selector_envio_embajadores_caritativos	El autocompletado del selector de campañas padre. Acción nonce charitable_ambassadors_submit_picker, sin puerta de capacidad (debe estar conectado).

Ayudante de detección de URL

charitable_ambassadors_get_submit_form_query_args() // ['recipient' => 'individual'|'team'|..., 'campaign' => 0|int]

Úsalo para inspeccionar el estado activo del enlace profundo desde tu propia interfaz de usuario personalizada.

Comprobaciones de capacidad

El formulario utiliza Charitable_Ambassadors_Campaign_Form::current_user_can_edit_campaign() para decidir si renderizar el formulario. Devuelve falso para:

• Usuarios no conectados.
• Usuarios cuyas cuentas requieren verificación por correo electrónico y no la han completado.
• Usuarios sin la capacidad de editar publicaciones al editar una campaña existente.

Partes por paso

templates/shortcodes/submit-campaign/recipient-cards.php   # Step 1 cards
templates/shortcodes/submit-campaign/parent-picker.php     # Step 2 picker
templates/shortcodes/submit-campaign/team-picker.php       # Step 2 team variant
templates/shortcodes/submit-campaign/campaign-details.php  # Step 3 wrap

Cada uno puede ser anulado por el tema a través de la misma ruta tu-tema/charitable-pro/charitable-ambassadors/<parte>.php.

Ejemplos de personalización

Forzar el formulario de envío heredado para todos los usuarios (p. ej., durante la depuración de regresión):

add_filter( 'charitable_ambassadors_use_card_submit_form', '__return_false' );

Limitar cada embajador a una sola recaudación simultánea:

add_filter( 'charitable_ambassadors_user_max_fundraisers', function () {
    return 1;
} );

Añadir un banner de "Bienvenido de nuevo" encima del paso 1 para los embajadores que regresan:

add_action( 'charitable_ambassadors_before_submit_form_step1', function () {
    $user = wp_get_current_user();
    if ( $user && get_user_meta( $user->ID, '_charitable_ambassadors_submitted_before', true ) ) {
        echo '<div class="notice notice-info"><p>Welcome back, ' . esc_html( $user->display_name ) . '!</p></div>';
    }
} );

Renombrar los argumentos de consulta (p. ej., para compatibilidad con versiones anteriores de una campaña existente):

add_filter( 'charitable_ambassadors_submit_form_query_arg_names', function () {
    return [ 'recipient' => 'team_type', 'campaign' => 'parent' ];
} );

Sella el evento de recaudación de fondos enviado con la URL de referencia al guardar:

add_action( 'charitable_campaign_submission_save', function ( $data, $campaign_id, $user_id, $form ) {
    $ref = wp_get_referer();
    if ( $ref ) {
        update_post_meta( $campaign_id, '_referer_at_submit', esc_url_raw( $ref ) );
    }
}, 10, 4 );

Relacionado

• Mis campañas: a dónde van los embajadores después de enviar.
• Moderación: a dónde van las propuestas para su revisión.
• Invitaciones – Atribución: cómo los clics en el enlace de reclutamiento se vinculan con las propuestas.
• Asistente de configuración: el asistente crea la página de envío por ti.
• Hooks y filtros en Embajadores: referencia completa.

---