Ejemplos de edición manual de formularios

From SinergiaCRM - Wikisuite
Jump to navigation Jump to search

Introducción

A pesar de que el código HTML obtenido a través del asistente de generación de formularios es funcionalmente operativo (puede comprobarse fácilmente abriendo el fichero descargado en un navegador y cumplimentado el formulario), habitualmente se deseará modificar o ampliar su funcionamiento original.

Es importante tener presente que tanto la integración como la modificación del código HTML requerirán de un determinado nivel de conocimientos técnicos en tecnologías web como HTML, CSS o javascript. En este sentido, es importante hacer una valoración previa de lo que representará la integración y/o la modificación de cada formulario, a fin de saber si el equipo técnico de la entidad podrá hacerse cargo del proceso completo o si será necesario contar con la participación de los desarrolladores web.

Como en cualquier otro aspecto del CRM, SinergiaTIC ofrece soporte a través del foro a los procesos de integración de formularios. Para que sea eficiente, es deseable que las personas que formulen las consultas sean aquellas que cuentan con los conocimientos técnicos requeridos y estén a cargo del proceso de integración/adaptación, sean internas o externas a la organización. Así pues, se recomienda que los desarrolladores web externos se den de alta en el foro y formulen las consultas directamente.

A continuación se presentan, sin ánimo de exhaustividad, algunos ejemplos habituales de posibles modificaciones a realizar en el código HTML del formulario. Cabe tener en cuenta que en tanto se respeten las denominaciones de los módulos y campos del CRM que aparecen en el código fuente del formulario y unas mínimas convenciones de sintaxis, cualquier modificación deseada puede ser aplicada.


Incluir campos adicionales

Una vez el formulario ya se ha descargado no queda almacenado en el CRM, por lo que no es posible editarlo ahí en caso de querer aplicar determinados cambios. O se vuelve a generar desde cero o se aplican los cambios manualmente sobre el código descargado. Un caso típico es la necesidad de incluir un campo omitido en el asistente o de un módulo del que el asistente no permite seleccionar campos (por ejemplo, el módulo Compromisos de pago en los formularios de captación de fondos).

A modo de ejemplo, el código siguiente permitiría incorporar al formulario el campo Descripción del módulo Compromisos de pago.

<tr>
    <td id="td_lbl_stic_Payment_Commitments___description" style="text-align: left; font-size: 12px; font-weight: normal;" width="15%">
        <span>
            <label id="lbl_stic_Payment_Commitments___description" for="stic_Payment_Commitments___description">Descripción:</label> 
        </span>
    </td>
    <td id="td_stic_Payment_Commitments___description" style="font-size: 12px; font-weight: normal;" width="35%">
        <span id="sugarslot"> 
            <span id="sugarslot">
                <textarea id="stic_Payment_Commitments___description" type="text" name="stic_Payment_Commitments___description" /> </textarea>
            </span> 
        </span>
    </td>
</tr>

Lo más relevante del código anterior es observar que para que el campo incluido sea reconocido por el CRM al recibir los datos, su atributo name tiene que estar formado por la concatenación del nombre interno del módulo en el CRM (en este caso, stic_Payment_Commitments), tres guiones bajos ( ___ ) y el nombre interno del campo (description). Los nombres internos de módulos y campos pueden obtenerse fácilmente viendo el resto del código del mismo formulario o a través de Estudio (para más información sobre Estudio, ver Adaptación de módulos existentes).


Hacer un campo obligatorio

Al generar un formulario en el CRM, este obliga al usuario a incluir en él todos los campos que sean obligatorios en el módulo base del formulario (Personas, Organizaciones, Inscripciones, Interesados y Público objetivo). Estos campos también tendrán la condición de obligatorios en el formulario generado. En ocasiones, sin embargo, es necesario establecer como obligatorio en un formulario un campo que no lo es con carácter general en el CRM. Por ejemplo, campos típicos de contacto como Teléfono móvil o Correo electrónico no suelen ser obligatorios en el CRM pero sí suelen serlo en formularios web.

Para establecer como obligatorio un campo en un formulario bastaría con indicar de forma temporal en Estudio (ver Adaptación de módulos) que el campo fuera requerido y una vez generado el formulario volver a desactivar la opción. Sin embargo, existen varias circunstancias en las que esta opción no es aplicable: cuando el formulario ya ha sido generado y no se desea volver a generar, cuando hay que aplicar la obligatoriedad sobre campos de determinados tipos (casillas de verificación o upload), etc. En estos casos es posible editar el código del formulario para obtener el mismo efecto.

Para ello basta con buscar en el código HTML un input oculto (hidden) llamado req_id e incorporar a su value el nombre del campo deseado. Se pueden incorporar todos los campos necesarios, separándolos entre sí mediante punto y coma. El formulario validará que todos los campos indicados se hayan cumplimentado antes de permitir el envío de los datos al CRM.

En el ejemplo siguiente se muestra el código que hace obligatorios los campos Nombre, Apellidos y Correo electrónico del módulo Personas.

<input id="req_id" type="hidden" name="req_id" value="Contacts___first_name;Contacts___last_name;Contacts___email1;" />

Lo más relevante del código anterior es observar que el campo incluido tiene que estar formado por la concatenación del nombre interno del módulo en el CRM (en este caso, Contacts), tres guiones bajos ( ___ ) y el nombre interno del campo (por ejemplo, first_name). En cualquier caso, como el campo ya formará parte del formulario, podrá copiarse el valor desde el lugar donde se encuentre.

Como complemento a la acción anterior, y a efectos visuales, será necesario establecer la marca de campo obligatorio junto a la etiqueta del campo (por defecto es un asterisco rojo pero puede ser cualquier otro elemento adaptado a la imagen gráfica del sitio web). De no incluirse podría resultar confuso para el usuario pues el formulario seguirá exigiendo la cumplimentación del campo.

<span class="required" style="color: #ff0000;">*</span>

Finamente, cabe mencionar que también es posible anular el requisito de obligatoriedad simplemente quitando el nombre del campo del punto indicado del código fuente.


Convertir un campo en oculto

Todos los campos que se seleccionan en el asistente del CRM y algunos más que el propio asistente incluye de forma automática son visibles por defecto en el formulario generado. Sin embargo, es posible que uno o más de estos campos, aunque sigan siendo necesarios a efectos de proceso, no deban ser accesibles para el usuario final. Por ejemplo, en un formulario de inscripción a eventos el importe de la inscripción puede ser un valor fijo y no un importe que el usuario pueda indicar libremente. O, también, en un formulario para recoger donativos para una campaña la periodicidad podría fijarse a Puntual o el medio de pago a Tarjeta. A veces también se usa un campo oculto para poder saber desde qué formulario se están recibiendo los datos.

En estos casos basta con añadir o modificar un elemento input de tipo hidden, estableciendo en el atributo value el valor deseado.

En el ejemplo siguiente se usa un campo oculto para indicar el valor del campo Medio de pago de una inscripción a un evento.

<input id="stic_Payment_Commitments___payment_method" type="hidden" name="stic_Payment_Commitments___payment_method" value="card" />

Lo más relevante del código anterior es observar que para que el campo incluido sea reconocido por el CRM al recibir los datos, su atributo name tiene que estar formado por la concatenación del nombre interno del módulo en el CRM (en este caso, stic_Payment_Commitments), tres guiones bajos ( ___ ) y el nombre interno del campo (payment_method). Los nombres internos de módulos y campos pueden obtenerse fácilmente viendo el resto del código del mismo formulario o a través de Estudio (para más información sobre Estudio, ver Adaptación de módulos existentes).


Establecer la fecha de primer pago

Cuando el envío de datos a través de un formulario supone la creación de un compromiso de pago en el CRM, la fecha de primer pago se establece por defecto a la del día en curso. Sin embargo, en algunas ocasiones puede ser interesante establecer una fecha de primer pago distinta de la actual. Por ejemplo, en el caso de entidades que gestionen cuotas de socio con periodicidad mensual puede considerarse oportuno empezar a cobrar la cuota el mes siguiente al del alta, particularmente cuando el alta se realiza en los últimos días del mes. Así pues, el campo podría introducirse como oculto en el formulario y el propio sitio web podría establecer su valor a conveniencia mediante javascript, de modo que resultara en algo como:

<input id="stic_Payment_Commitments___first_payment_date" type="hidden" name="stic_Payment_Commitments___first_payment_date" value="2021-07-01" />


Cambiar el usuario destinatario de las notificaciones

En el asistente de diseño se indica a qué usuario del CRM se asignará el formulario. Dicho usuario recibirá las notificaciones por correo electrónico que envía al CRM cuando cualquier persona cumplimenta el formulario. Para modificar este usuario hay que buscar la siguiente línea en el código fuente del formulario:

<input id="assigned_user_id" type="hidden" name="assigned_user_id" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"/>

Las X representan el identificador interno (id) del usuario del CRM que recibe las notificaciones. Para que sea otro usuario quién las reciba basta localizar su id en el CRM y reemplazar el uno por el otro en el código fuente del formulario. El id puede obtenerse a través de un informe basado en el módulo de Usuarios o mirando el parámetro record en la URL de la vista de detalle del usuario en cuestión:

https://<entidad>.sinergiacrm.org/...&record=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX


Cambiar la campaña asociada

En los asistentes de creación de formularios básicos y de captación de fondos se indica la campaña a la que se asignará el formulario. Para modificar esta campaña hay que buscar la siguiente línea en el código fuente del formulario:

<input name="campaign_id" id="campaign_id" type="hidden" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />

Las X representan el identificador interno (id) de la campaña del CRM asociada al formulario. Para asociar una campaña distinta basta localizar su id en el CRM y reemplazar el uno por el otro en el código fuente del formulario. El id puede obtenerse a través de un informe basado en el módulo de Campañas o mirando el parámetro record en la URL de la vista de detalle de la campaña en cuestión:

https://<entidad>.sinergiacrm.org/...&record=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX


Cambiar la plantilla de correo asociada

En los asistentes de creación de formularios de inscripción a eventos y de captación de fondos se puede indicar la plantilla de correo utilizada para confirmar la operación que se enviará a la persona que rellena el formulario. Para modificar esta plantilla hay que buscar la siguiente línea en el código fuente del formulario y sustituir el identificador que aparece tras la palabra email_template (hay que tener especial cuidado en respetar los caracteres especiales %3A, %22, etc.):

<input id="defParams" type="hidden" name="defParams" value="%7B%22version%22%3A%222%22%2C%22email_template_id%22%3A%22XXXXXX-XXXX-XXXX-XXXX-XXXXXXXX%22%2C%22relation_type%22%3A%22%22%7D" />

Las X representan el identificador interno (id) de la plantilla del CRM asociada al formulario. Para asociar una plantilla distinta basta localizar su id en el CRM y reemplazar el uno por el otro en el código fuente del formulario. El id puede obtenerse mirando el parámetro record en la URL de la vista de detalle de la plantilla en cuestión:

https://<entidad>.sinergiacrm.org/...&record=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX


Cambiar el evento asociado

En el asistente de creación de formulario de inscripción a un evento se indica el evento al cual se asignará el formulario. Para modificar el evento hay que buscar la siguiente línea en el código fuente del formulario:

<input id="event_id" type="hidden" name="event_id" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />

Las X representan el identificador interno (id) del evento del CRM asociado al formulario. Para asociar un evento distinto basta localizar su id en el CRM y reemplazar el uno por el otro en el código fuente del formulario. Para saber como obtener el "ID" consultar Notas acerca de los ID de registros.


Modificar las URLs de redirección

En cada uno de los formularios se deben definir una "URL de redirección" y en algunos casos también una "URL de redirección en caso de error". Es posible modificar estas direcciones de redirección desde el código fuente del formulario.

Para modificar la "URL de redirección" hay que buscar la siguiente línea en el código fuente del formulario y modificar la URL:

<input id="redirect_url" type="hidden" name="redirect_url" value="https://www.urlredireccion.org/gracias" />


Para modificar la "URL de redirección en caso de error" hay que buscar la siguiente línea en el código fuente del formulario y modificar la URL:

<input id="redirect_ko_url" type="hidden" name="redirect_ko_url" value="https://www.urlredireccion.org/error" />


Los valores a modificar se encuentran después de value= y se debe introducir la URL entre comillas.


Modificar el importe de las inscripciones

En el asistente de creación de formulario de inscripción a un evento que incluya el sistema de pago se puede indicar el importe que deberá pagar la persona que se inscriba. Si se desea modificar este valor una vez creado el formulario, se deberá buscar la siguiente línea en el código fuente del formulario:

<input id="stic_Registrations___amount_dec_c" type="hidden" name="stic_Registrations___amount_dec_c" value="15,3" />

El valor a modificar se encuentra detrás de "value=", donde se podrá entrar el importe deseado entre las comillas.


Añadir campos upload para archivos adjuntos en formularios básicos de campañas

En el asistente de generación de formularios básicos de campañas no es posible indicar la inclusión de campos de tipo upload para subir ficheros al CRM vía formularios web. En caso de que se desee contar con esta posibilidad hay que editar el código fuente del formulario de la siguiente manera:

1) Localizar la etiqueta <form> y añadirle el atributo enctype="multipart/form-data" de modo que esta línea:

<form id="WebToLeadForm" action="http://entidad.sinergiacrm.org/index.php?entryPoint=WebToLeadCapture" method="POST" name="WebToLeadForm">

se convierta en esta:

<form id="WebToLeadForm" action="http://entidad.sinergiacrm.org/index.php?entryPoint=WebToLeadCapture" method="POST" name="WebToLeadForm" enctype="multipart/form-data">

2) Añadir el siguiente código en el lugar deseado entre los campos del formulario:

<div class="row">
    <div class="col">
        <label>Fichero adjunto 1:</label> 
        <input name="documents[]" id="Documents___document1" type="file"/>
    </div> 
    <div class="col"> </div>
    <div class="clear"> </div>
</div>

El código anterior introduce una capa con dos columnas, que es la estructura que por defecto genera el asistente del CRM. Si el formulario ha sido modificado para disponer los campos de otra forma, el código anterior deberá adaptarse para que encaje con la nueva disposición. Lo relevante, como en otros casos, es conservar los nombres e identificadores de los campos (atributos name e id).

Para añadir más de un control de tipo upload basta con replicar el código de las dos primeras celdas en cualquier otro par de celdas de la misma fila o de una fila nueva sustituyendo el id Documents___document1 por Documents___document2 y sucesivos. En realidad no es imprescindible que los id tengan esta denominación, basta con que no se repitan entre sí ni con cualquier otro id del formulario. Lo que sí debe garantizarse es que el array que los reúne y los manda al servidor mantenga el nombre documents[].

3) Por último, debe añadirse un campo oculto que indique al CRM en qué idioma debe escribir los comentarios sobre el origen de los ficheros recibidos (ver el apartado Recepción de ficheros adjuntos). En caso de no indicar esta opción los comentarios se escribirán en el idioma del navegador desde el que se envía el formulario.

<input id="language" type="hidden" name="language" value="ca_ES" />


Evitar envíos múltiples

Si la persona que cumplimenta un formulario pulsa repetidamente el botón Enviar puede suceder que en el CRM se introduzcan datos duplicados. El 04/01/2022 se introdujo una modificación en el generador de formularios un mecanismo de control para evitar que esto suceda. A continuación se describe dicha modificación por si se desea aplicar a formularios preexistentes.


Formularios básicos de campañas

Añadir justo al principio del bloque Javascript del formulario el siguiente código:

<script type='text/javascript'>
    
    // Código añadido ######################################
    var formHasAlreadyBeenSent = false;
    
    /**
     * Prevent multiple form submissions
     *
     * @return void
     */
    function lockMultipleSubmissions() {
      if (formHasAlreadyBeenSent) {
        console.log("Form is locked because it has already been sent.");
        event.preventDefault();
      }
      formHasAlreadyBeenSent = true;
    }
    
    // Attach function to event
    document.getElementById("WebToLeadForm").addEventListener("submit", lockMultipleSubmissions);
   
    // Fin código añadido ######################################
 
    ...


Formularios de captación de fondos o de inscripción a eventos

En el bloque Javascript del formulario, sustituir el contenido de la función submitForm() por el siguiente código (la declaración de la variable formHasAlreadyBeenSent debe ir justo antes de la llamada a la función):

  
  var formHasAlreadyBeenSent = false;
  /**
   * Form submission function
   * @param form form to be sent
   */
  function submitForm(form) {
    if (checkFields() && checkFormSize()) {
      if (typeof validateCaptchaAndSubmit != "undefined") {
        validateCaptchaAndSubmit();
      } else {
        if (formHasAlreadyBeenSent != true) {
          formHasAlreadyBeenSent = true;
          form.submit();
        } else {
          console.log("Form is locked because it has already been sent.");
        }
      }
    }
    return false;
  }


Permitir pagos recurrentes con tarjeta o PayPal

Históricamente los formularios de captación de fondos han incorporado un mecanismo de validación para que solo en el caso de las domiciliaciones bancarias fuera posible generar en el CRM un compromiso de pago periódico. Actualmente el CRM puede gestionar también pagos recurrentes con tarjeta y PayPal y el mecanismo de validación se ha actualizado para contemplar dichos casos.

Tal y como se describirá a continuación, los formularios ya existentes al aparecer esta funcionalidad pueden ser adaptados para disponer de la versión actualizada del mecanismo de validación. Igualmente, los creados a posteriori pueden ser también adaptados para habilitar o deshabilitar a voluntad la funcionalidad en determinados medios de pago.

Es importante tener en cuenta que este mecanismo de control para permitir o evitar determinadas combinaciones de periodicidades y medios de pago solo opera en el contexto del navegador del usuario final que está rellenando el cuestionario. Esto implica que si en el proceso de adaptación e integración web del formulario generado por el CRM el código asociado a este mecanismo es modificado inadecuadamente o directamente eliminado o, en el caso de formularios antiguos, simplemente no incorporado, el control no se ejercerá del modo previsto y el CRM podría recibir combinaciones de periodicidad y medio de pago no deseadas, que asumirá como correctas y procesará como en cualquier otro caso.


Formularios creados antes de existir la funcionalidad

1) Junto al grupo de campos de tipo hidden que ya aparecen en el formulario es necesario añadir otro campo del mismo tipo por cada una de las opciones que se desee habilitar:

<input type="hidden" id="allow_card_recurring_payments" name="allow_card_recurring_payments" value="1">
<input type="hidden" id="allow_paypal_recurring_payments" name="allow_paypal_recurring_payments" value="1">

Si en algún momento se desea deshabilitar la posibilidad de recurrencia en alguno de los dos medios de pago basta con poner su atributo value a 0 o, simplemente, borrar la línea de código.

2) Al final del bloque javascript del formulario se encuentran las funciones adaptPeriodicity() y adaptPaymentMethod(). Es necesario reemplazar completamente ambas funciones por el siguiente código:

// Set variables for manage recurring payment validations
var oP = document.getElementById('allow_paypal_recurring_payments');
var allowPaypalRecurringPayments = oP && oP.value == 1 ? 1 : 0;
var oC = document.getElementById('allow_card_recurring_payments');
var allowCardRecurringPayments = oC && oC.value == 1 ? 1 : 0;

/**
 * Adapt the form based on the periodicity value
 */
function adaptPeriodicity() {
  var oPeriodicity = document.getElementById("stic_Payment_Commitments___periodicity"); // Retrieve the html element from periodicity
  var vPeriodicity = oPeriodicity.options[oPeriodicity.selectedIndex].value;
  var oPaymentMethod = document.getElementById("stic_Payment_Commitments___payment_method"); // Retrieve the html element of payment method
  var vPaymentMethod = oPaymentMethod.options[oPaymentMethod.selectedIndex].value;

  // If the periodicity has a value and is not punctual mark the means of payment as 'Direct debit'
  if (vPeriodicity && vPeriodicity != "punctual" &&
    ((vPaymentMethod == "card" && allowCardRecurringPayments == 0)
      || (vPaymentMethod == "paypal" && allowPaypalRecurringPayments == 0)
      || vPaymentMethod == "bizum")) {
    if (confirm(stic_Payment_Commitments_LBL_PAYMENT_TYPE_PUNCTUAL)) {
      setSelectValue(oPaymentMethod, "direct_debit");
      adaptPaymentMethod();
    } else {
      setSelectValue(oPeriodicity, oPeriodicity.prev_value);
      return false;
    }
  }
  oPeriodicity.prev_value = vPeriodicity;
}

/**
* Adapt the form based on the value of the payment method
*/

function adaptPaymentMethod() {

  var oPaymentMethod = document.getElementById("stic_Payment_Commitments___payment_method"); // Retrieve the html element of payment method
  var vPaymentMethod = oPaymentMethod.options[oPaymentMethod.selectedIndex].value;
  var oPeriodicity = document.getElementById("stic_Payment_Commitments___periodicity"); // Retrieve the html element of periodicity
  var vPeriodicity = oPeriodicity.options[oPeriodicity.selectedIndex].value;

  // If the payment method has changed to card or bizum, check the periodicity
  if (((vPaymentMethod == "card" && allowCardRecurringPayments == 0)
    || (vPaymentMethod == "paypal" && allowPaypalRecurringPayments == 0)
    || vPaymentMethod == "bizum")
    && vPeriodicity && vPeriodicity != "punctual") {
    if (confirm(stic_Payment_Commitments_LBL_PERIODICITY_PUNCTUAL)) {
      // If you want to continue, punctual periodicity is indicated
      setSelectValue(oPeriodicity, "punctual");
    } else {
      setSelectValue(oPaymentMethod, oPaymentMethod.prev_value);
      return false;
    }
  }

  // If the payment method is a direct debit, it shows the account number field and marks it as required.
  if (vPaymentMethod == "direct_debit") {
    showField("stic_Payment_Commitments___bank_account");
    addRequired("stic_Payment_Commitments___bank_account");
  } else {
    hideField("stic_Payment_Commitments___bank_account");
    removeRequired("stic_Payment_Commitments___bank_account");
  }
  oPaymentMethod.prev_value = vPaymentMethod;
}


Formularios creados después de existir la funcionalidad

Si una vez generado el formulario se desea cambiar en un u otro sentido el comportamiento establecido para los pagos recurrentes con tarjeta o Paypal, basta con localizar las siguientes líneas en el código HTML del formulario web:

<input type="hidden" id="allow_card_recurring_payments" name="allow_card_recurring_payments" value="X">
<input type="hidden" id="allow_paypal_recurring_payments" name="allow_paypal_recurring_payments" value="X">

y establecer el atributo value de cada opción según lo deseado: 0 para deshabilitar la recurrencia, 1 para habilitarla.