Plugin Wordpress para gestión de Área Privada

From SinergiaCRM
Jump to: navigation, search

Presentación

SinergiaCRM Private Area (SPA) es un plugin para Wordpress (WP) que permite crear un área privada en cualquier sitio web de la entidad basado en este gestor de contenidos, con el obejtivo de mostrar, crear y editar registros en los diferentes módulos de SinergiaCRM. Mediante un área privada convenientemente adaptada, cualquier entidad puede facilitar que determinados colectivos (socios, trabajadores, entidades federadas, etc.) puedan visualizar o proporcionar datos de forma segura e identificada sin necesidad de contar con un acceso directo al CRM. Un ejemplo típico de aplicación sería ofrecer a los socios un espacio donde consultar y actualizar sus datos.

Para conectarse y comunicarse con el CRM, SPA utiliza la API Rest v4.1 de SugarCRM Community Edition, también presente en SuiteCRM. La conexión con el CRM se realiza mediante un usuario estándar del mismo, indicando sus datos de acceso en la configuración del plugin.

El plugin ofrece una serie de funcionalidades ya desarrolladas:

  • Creación de nuevos usuarios (single_stic_signup)
  • Edición del perfil de usuario (single_stic_profile)
  • Baja del usuario (single_stic_unsubscribe)
  • Cambio de contraseña (single_stic_password_change)
  • Recuperación de contraseña (stic_forgot_password)

También se ha incluido en el plugin, a modo ilustrativo y de ejemplo, el equivalente a las vistas de lista y de edición de los módulos Formas de pago y Relaciones con Personas, de modo que puedan servir de base para desarrollar similares funcionalidades para cualquier otro módulo del CRM.

  • Vista de lista de Formas de pago (list_stic_payment_methods)
  • Vista de edición de Formas de pago (single_stic_payment_method)
  • Vista de lista de Relaciones con Personas (list_stic_contact_relationships)
  • Vista de edición de Relaciones con Personas (single_stic_contact_relationship)

El plugin dispone también de una página de contenido libre donde es posible incluir cualquier código HTML (custom_stic_html_page), pensada, por ejemplo, para permitir la inclusión de un formulario creado en el CRM (de captación de fondos, de inscripción a eventos, etc), de modo que pueda ser utilizado de forma privada por personas cuyos datos ya están registrados en el CRM. En cualquier caso, este tipo de página podría usarse para mostrar cualquier contenido HTML.

La adaptación del plugin a las necesidades específicas debe realizarse mediante la modificación de los ficheros PHP que se incluyen en las siguientes rutas (relativas a la carpeta del plugin):

  • /pages: los ficheros de esta carpeta pueden usarse como plantillas para la creación de vistas de lista y edición distintas de las proporcionadas como ejemplos.
  • menu.php: fichero utilizado para la gestión de los elementos del menú principal del área privada, incluyendo la página por defecto.
  • /inc/stic-action.php: fichero donde programar la lógica de la conexión al CRM mediante el API para recuperar y/o modificar los datos de los módulos del CRM.

 

 

Instalación

1. Descargar el plugin: sinergiacrm-private-area.zip

2. En el área de administración de Wordpress, ir al apartado Plugins, pulsar en Añadir nuevo, luego en Subir plugin, seleccionar el fichero descargado en el punto anterior y pulsar sobre Instalar ahora.

3. Activar el plugin.

 

Configuración

Si la instalación y la activación han sido correctas, el plugin aparecerá en la lista de plugins instalados en la instancia de Wordpress y en la columna izquierda del área de administración, donde se encuentra el menú principal, aparecerá la opción Área privada de SinergiaCRM. Al hacer clic en esta opción se accede a la página de configuración del plugin.

.Wpap 02 config plugin.jpg

En esta página es necesario configurar los siguientes elementos que aparece:

  • Nombre del portal: El nombre que se mostrará como título del Área privada.
  • REST URL: La dirección de la API en el CRM: https://<dominio_del_crm>/service/v4_1/rest.php. Es necesario sustituir <dominio_del_crm> por el valor adecuado.
  • Nombre de usuario: El nombre de usuario del CRM que usará la API para acceder al CRM y recuperar o modificar los datos. No es necesario que sea un usuario administrador, pero sí debe tener los permisos suficientes a nivel de roles en el CRM para realizar las operaciones de lectura y escritura que se deseen realizar desde el área privada. Se recomienda crear un usuario específico para este fin.
  • Contraseña: La contraseña de acceso al CRM del usuario indicado en la casilla anterior.

 

Idiomas

El plugin usa el inglés como idioma nativo, es decir, que los textos a mostrar en pantalla que aparecen en el código del plugin están en dicho idioma. Además, el plugin utiliza las funciones de traducción propias de Wordpress (https://codex.wordpress.org/Function_Reference/translate), lo que permite, finalmente, que los textos se muestren al usuario en el idioma definido en Wordpress. El plugin se suministra con los ficheros de traducción al español y al catalán listos para ser utilizados.

Si en la adaptación del plugin a las necesidades de la entidad se incorporan nuevos textos, se recomienda seguir esta forma de trabajar:

1. En el código fuente del plugin usar la función:

<?php __($text, $domain); ?>

donde $text es la cadena a traducir y $domain es el dominio de traducción de Wordpress, que en este caso será el plugin, referenciado por la cadena sticpa. A modo de ejemplo:

<?php __('sample text', 'sticpa'); ?>

2. Una vez realizadas las modificaciones en el código será necesario completar las traducciones al idioma deseado. Una forma fácil de hacerlo es mediante el plugin Loco Translate (https://es.wordpress.org/plugins/loco-translate/), que permite la traducción de las cadenas en el propio entorno de administración de Wordpress.

Alternativamente pueden editarse los ficheros de idioma PO presentes en la carpeta languages mediante un editor local como Poedit (https://poedit.net/) u online como Loco Poeditor (https://localise.biz/free/poeditor). En caso de hacerlo por esta vía será necesario generar los correspondientes ficheros MO y subirlos a la carpeta languages. Este sistema puede servir también para generar archivos de traducción para idiomas no incluidos de serie en el plugin.

 

Acceso al área privada

Para poner en funcionamiento el área privada es necesario crear una página en Wordpress e incluir en la misma el shortcode [sinergiacrm-private-area]. Al invocar la URL de dicha página, que puede tener cualquier nombre, se mostrará en pantalla el formulario de acceso (login) al área privada.

Wpap 06 plugin login.jpg

Normalmente las personas que van a acceder al CRM no son usuarios del mismo, sino que suelen ser miembros de alguno de los colectivos involucrados en la actividad de la entidad: socios, voluntarios, etc. Así pues, es importante no confundir los usuarios del CRM (habitualmente los técnicos de la entidad) con los usuarios del área privada (cualquiera de los colectivos mencionados). Será necesario, pues, establecer y almacenar en algún lugar del CRM las credenciales de acceso de los usuarios del área privada.

Para ello el plugin usa los campos username (Nombre de usuario) y password (Contraseña) en el módulo Personas (Contacts). Estos campo no existen por defecto en el CRM y deben ser creados desde Estudio como campos de texto con el nombre indicado. Cabe tener presente que al guardar los campos el CRM modificará los nombres indicados añadiéndoles el sufijo _c, por tratarse de campos custom, es decir, personalizados. Por lo tanto, el nombre real final de los campos será username_c y password_c, y así se invocan en el código del plugin.

Si una entidad de segundo nivel (federaciones, plataformas, etc.) quisiera crear un área privada para sus entidades asociadas podría incluir los campos anteriores en el módulo Organizaciones (Accounts) y modificar el plugin para apuntar a dicho módulo en lugar de hacerlo al de personas.

En la versión actual del plugin la contraseña se almacena en texto plano.

 

Menú principal

El menú principal del área privada se gestiona mediante el fichero menu.php que se encuentra en la carpeta raíz del plugin. Solamente es necesario modificar los valores del array $menuElements y de la variable defaultMenuElement:

// Elementos del menú principal (pestañas). 
// La clave de cada elemento del array debe ser el nombre del fichero correspondiente de la carpeta "pages", sin extensión.
$menuElements['single_stic_profile'] = 'My profile';
$menuElements['list_stic_payment_methods'] = 'My payment methods';
$menuElements['list_stic_contact_relationships'] = 'My relationships';
$menuElements['custom_stic_html_page'] = 'Custom html';
$menuElements['single_stic_password_change'] = 'Change password';
$menuElements['single_stic_unsubscribe'] = 'Unsubscribe';

// Página que se cargará tras hacer login
$defaultMenuElement = 'custom_stic_html_page';

Cabe tener en cuenta que al definir las opciones del menú no es necesario usar la función de traducción en cada una de ellas puesto que la llamada a dicha función ya se incluye posteriormente en la función que genera el código HTML del menú a partir del array $menuElements

Por otro lado, no es necesario que todas las páginas definidas en el área privada se incluyan en el menú. Por ejemplo, las vistas de edición son llamadas habitualmente desde las vistas de lista, por lo que no es imprescindible definir un elemento del menú para ellas.

 

Funcionalidades básicas

Alta de nuevos usuarios

Desde el formulario de login puede accederse al formulario de registro de nuevos usuarios. Tal y como se ha comentado anteriormente, cabe tener presente que el alta de nuevos usuarios supondrá la creación de nuevos registros en el módulo Personas del CRM, no en el de Usuarios. Si la entidad no desea que se puedan crear personas nuevas por este sistema puede eliminar el enlace en la función sugar_crm_portal_login_form del fichero sinergiacrm-private-area.php que se encuentra en la ubicación raíz del plugin.

Wpap 07 plugin register.jpg

El formulario de registro puede adaptarse siguiendo las mismas reglas que para las vistas de edición que se describirán más adelante, modificando el fichero pages/single_stic_signup.php. En este caso no es necesario modificar el controlador existente.

Modificar el perfil de usuario

Una vez dentro del área privada es posible visualizar y actualizar los datos identificativos y de contacto del usuario logueado. Esta es una de las utilidades principales de un área privada, pues permite actualizar en el CRM los datos de socios u otros colectivos sin necesidad de intervención del equipo técnico de la entidad.

El formulario de perfil de usuario puede adaptarse siguiendo las mismas reglas que para las vistas de edición que se describirán más adelante, modificando el fichero pages/single_stic_profile.php.

Cambio de contraseña

El usuario logueado puede cambiar su contraseña mediante el formulario habilitado a tal fin. Este formulario no necesita adaptación y se gestiona mediante el fichero pages/single_stic_password_change.php.

Recuperación de contraseña

En caso de no recordar su contraseña el usuario puede solicitar su recordatorio desde el formulario de login. El plugin incluye la funcionalidad necesaria para gestionar el reenvío de la contraseña a la dirección de correo del usuario del área privada. Para ello es necesario que el usuario suministre su nombre de usuario y su dirección de correo electrónico y que estos valores coincidan con los disponibles en el CRM.

Wpap 08 plugin reset pwd.jpg

Es posible adaptar el contenido del correo enviado en la función prefix_admin_stic_forgot_password() incluida en el fichero inc/stic-action.php.

El envío de correos se realiza mediante la función wp_mail()  propia de Wordpress. Esta función, hace uso del envío directo de correos desde el servidor, que frecuentemente no está habilitada. En este caso se recomienda el uso de un plugin de Wordpress que habilite el envío a través de un servidor SMTP, como WP mail SMTP (https://es.wordpress.org/plugins/wp-mail-smtp/).

Baja del área privada

Un usuario logueado puede darse de baja del áre privada. El efecto de dicha acción es el borrado campos username_c y password_c del módulo Personas (Contacts) del CRM y la finalización de la sesión del usuario. Así pues, un usuario que se dé de baja no podrá volver a acceder al área privada si no se introducen nuevos valores en dichos campos del CRM y le son comunicados.

Si la entidad no desea permitir la baja de los usuarios del área privada puede eliminar dicha opción en el array de elementos del menú principal, tal y como se ha descrito anteriormente.

La gestión del proceso de baja se realiza mediante el fichero pages/single_stic_unsubscribe.php.

 

Vistas de lista

Las páginas de vista de lista permiten mostrar los registros de un determinado módulo (o un subconjunto de ellos) en forma de tabla, incluyendo enlaces para editar los registros mostrados y para añadir nuevos registros. En el plugin se incluyen dos ejemplos de este tipo, asociados a los módulos de Formas de pago y Relaciones con Personas. Por defecto los registros que se muestran en estas vistas son los relacionados con la persona que se ha logueado en el área privada, pudiéndose establecer otras condiciones adicionales (por ejemplo, solo formas de pago vigentes) o quitarlas por completo (por ejemplo, mostrar todos los registros de un módulo sin importar a qué persona estén vinculados).

Wpap 03 list view.jpg

Configuración general

Cada vista de lista se define en un fichero php en la carpeta pages. Partiendo del ejemplo para el módulo Formas de pago (list_stic_payment_methods.php) analizamos su estructura:

// El título del listado
$listSettings['title'] = __('My payment methods', 'sticpa');

// La página de destino del enlace correspondiente a cada registro
$listSettings['linkDestination']='?page=single_stic_payment_method';

// La etiqueta que mostrará el enlace de cada registro.
$listSettings['linkDestinationLabel']= __('Edit','sticpa');

// Si se muestra un botón para crear un nuevo registro y su etiqueta
$listSettings['createButton'] = array(value => true, label => __('New payment method', 'sticpa'));

// Si se permite o no la ordenación de las columnas, paginación y/o filtrado del listado. 
// Se usa el plugin datatables (https://datatables.net/manual/options). 
// La configuración de datatables se indica en su parámetro jsonSettings, de acuerdo a su propia documentación
$listSettings['datatables'] = array(value=>true, jsonSettings=>'{paging:false, searching: false}');

Configuración de las columnas

Las columnas o campos a incluir en la vista de lista se definen en el array $columnList. Siguiendo con el mismo fichero de ejemplo:

$columnsList[] = array(name => 'name', label => __('Name', 'sticpa'));
$columnsList[] = array(name => 'mediopago', label => __('Payment method', 'sticpa'), format=>'translate');
$columnsList[] = array(name => 'importe', label => __('Amount', 'sticpa'), format=>'currency', attributes=>'style="text-align:right;min-width:75px;"');

Para cada columna, es decir, para cada elemento del array $columnList, pueden defnirse los siguientes parámetros:

  • name: Requerido. El nombre del campo tal como existe en el CRM.
  • label: Requerido. La etiqueta que se mostrará en el encabezado de la columna.
  • format: Opcional. Define si el valor debe sufrir alguna transformación antes de su presentación en pantalla. Las transformaciones deben estar definidas en la función formatValue() dentro del archivo inc/stic-formatter.php. Valores posibles actualmente: ‘currency’|’translate’|’date’|’upper’|custom functions
  • attributes: Opcional. Los atributos html a añadir a las celdas de esa columna. 

Obtención de los datos

Para obtener los datos que se mostrarán en el listado se usa el array $params, que posteriormente se incluirá en la llamada API al CRM. Siguiendo con el ejemplo analizado:

$params = array(
    "module_name" => 'Contacts',
    "module_id" => $_SESSION['scp_user_id'],
    "link_field_name" => "redk_formas_de_pago_contacts",
    "related_module_query" => "(fechabaja is null OR fechabaja > curdate())",
    "related_fields" => $fieldsToRetrieve, //don't touch
    "related_module_link_name_to_fields_array" => array(),
    "deleted" => 0, //show or not deleted elements (usually 0)
    "order_by" => $order_by,
    "offset" => $offset,
    "limit" => 0,
);

Los parámetros habitualmente configurables son:

  • module_name: El módulo en que está validado el usuario del área privada, en este caso Contacts (Personas), aunque también podría ser, por ejemplo, Accounts (Organizaciones) si se tratara del área privada de una federación y sus usuarios fueran sus entidades asociadas.
  • link_field_name: El nombre de la relación entre module_name y el módulo del que queremos obtener los registros. Puede obtenerse en la sección Estudio del área de administración del CRM.
  • related_module_query: Los filtros para recuperar los datos, equivalente a la cláusula where de una consulta SQL.

La variable $fieldsToRetrieve contiene los campos a obtener del CRM según lo indicado en $columnsList

Puede encontrase información adicional sobre el resto de los parámetros y sobre el funcionamiento general de las llamadas al CRM en el apartado API de la Guia para desarrolladores de SugarCRM (en inglés).

 

Vistas de edición

Las páginas de vista de edición permiten mostrar en formato editable los datos de un solo registro de un determinado módulo. También pueden servir para la creación de nuevos registros Como en el caso de las vistas de lista, en el plugin se incluyen dos ejemplos de este tipo, asociados a los módulos de Formas de pago y Relaciones con Personas. Por defecto los registros que se crean desde estas vistas se relacionan con la persona que se ha logueado en el área privada, aunque la lógica puede cambiarse según necesidades.

Wpap 04 edit view.jpg

Configuración general 

Cada vista de edición se define en un fichero php en la carpeta pages. Partiendo del ejemplo para el módulo Formas de pago (single_stic_payment_method.php) analizamos su estructura:

// El título del formulario
$formSettings['title'] = __('My profile', 'sticpa');

// El nombre del módulo sobre el que actúa el formulario.
$formSettings['moduleName'] = 'Contacts';

// La etiqueta del botón Enviar
$formSettings['submitButton'] = __('Save','sticpa');

// Los atributos html que se incluirán en el elemento <form>. Puede ser útil para añadir una clase que mediante CSS permita manejar el aspecto del formulario (número de columnas, etc.).
$formSettings['attributes'] = "class="col3";"

// Mensajes que se mostrarán cuando se cargue el formulario después de ser enviado. En esta configuración, si el controlador del formulario definido en inc/stic-action.php devuelve msg=true aplicará la siguiente configuración mostrando el mensaje correspondiente. El parámetro type, indica el tipo de mensaje a mostrar, usando uno u otro color. Se pueden añadir cuantos mensajes sean necesarios
$formSettings['msg'][] = array(value => 'true', type => 'success', msg => __('The record has been updated successfully', 'sticpa'));

Configuración de los campos

Los campos a incluir en la vista de edición se definen en el array $fieldList. Es necesario incluir siempre el campo id para que sea posible actualizar registros existentes. La validación del formulario no utiliza Javascript, sino que emplea el estándar html5.

Siguiendo con el mismo fichero de ejemplo:

$fieldList[] = array(name => 'edad_c', label => __('Age', 'sticpa'), type => 'text', required => false, attributes => array(disabled => 'disabled'));
$fieldList[] = array(
  name => 'sexo_c',
  label => __('Gender', 'sticpa'),
  type => 'select',
  required => true,
  selectValues => array(
      ' ' => ' ',
      'hombre' => __('Male', 'sticpa'),
      'mujer' => __('Female', 'sticpa'),
  ),
);

Los parámetros de cada uno de los valores del array $fieldList pueden ser:

  • name: Requerido. El nombre del campo en el CRM.
  • label: Requerido. La etiqueta que se mostrará junto al campo.
  • type: Requerido. El tipo de campo que se mostrará en el formulario. Los posibles tipos son: texthiddenemaildatenumberpasswordtextareaselectreadOnly. Esta última opción permite mostrar campos no editables.
  • selectValues: Requerido si es del tipo select (desplegable). Debe incluirse un array con los elementos (options) que se mostrarán en el desplegable.
  • required: Opcional. Si el campo es o no requerido. Si no se indica se asume que no es requerido.
  • attributes: Opcional. Los atributos html que se incluirán en el control. Un posible uso es incluir llamadas a funciones Javascript.
  • format: Opcional. Define si el valor debe sufrir alguna transformación antes de su presentación en pantalla. Las transformaciones deben estar definidas en la función formatValue() dentro del archivo inc/stic-formatter.php. Valores posibles actualmente: ‘currency’|’translate’|’date’|’upper’|custom functions

Controlador

Una vez que la vista de edición está diseñada es necesario definir el controlador que se encargará de procesar y enviar los datos al CRM a través de la API. Los controladores están definidos en el fichero inc/stic-action.php. Este es el código del controlador asociado al ejemplo analizado en los apartados anteriores (single_stic_payment_method):

###################################################
# Process form to manage payment methods
# Page: pages/single_stic_payment_method.php
###################################################

//Se registran las funciones en php para que Wordpress las procese al cargar el formulario. La función siempre debe incluir el prefijo admin_post+<nombre_de_la_funcion>. Repetir la llamada con el prefijo admin_post_nopriv
add_action('admin_post_single_stic_payment_method', 'prefix_admin_single_stic_payment_method'); add_action('admin_post_nopriv_single_stic_payment_method', 'prefix_admin_single_stic_payment_method');

//Declarar la función. El nombre debe ser prefijo+scriptName
function prefix_admin_single_stic_payment_method()
{
  #### datos adaptables ##########################
  $moduleName = 'redk_Formas_de_Pago'; // El módulo donde guardar los datos del formulario
  $linkFieldName = 'redk_formas_de_pago_contacts'; // El nombre exacto de la relación entre $moduleName y Contacts. Si el módulo relacionado con Contacts es un módulo base de Sugar, entonces debe figurar el nombre del módulo
  ################################################

  global $objSCP; //requerido. No tocar

  foreach ($_REQUEST as $key => $value) {
      $moduleData[$key] = stripslashes_deep($value);
  }
  $isUpdate = $objSCP->set_entry($moduleName, $moduleData);

  if ($isUpdate != null) {

      // si se trata de un registro nuevo, creamos la relación con el registro de Contacts (Personas) que ha iniciado la sesión
      if ($isUpdate != $_REQUEST['id']) {
          $set_relationships_parameters = array(
              'session' => $objSCP->session_id,
              'module_name' => $moduleName,
              'module_id' => $isUpdate,
              'link_field_name' => $linkFieldName,
              'related_ids' => array($_SESSION['scp_user_id']),
              'delete' => 0,
          );
          $set_relationships_result = $objSCP->call("set_relationship", $set_relationships_parameters, $objSCP->url);
      }

      $redirect_url = $_REQUEST['scp_current_url'] . '&msg=true' . '&id=' . $isUpdate;
      wp_redirect($redirect_url);
  }
}

 

Páginas de contenido libre

A modo de ejemplo, se incluye en el plugin una página especial, pages/custom_stic_html_page.php, que permite incluir cualquier código html y/o php.

Wpap 05 custom html view.jpg

Uno de los usos para este tipo de páginas es la inclusión de un formulario web generado por SinergiaCRM (de captación de fondos, inscripción a eventos o de interesados), lo que permite convertir estos formularios en privados, ya que para acceder a ellos es necesario tener un usuario y contraseña en el área privada. Esto permitiría, por ejemplo, gestionar nuevos donativos o inscripciones sin necesidad de repreguntarle a la persona sus datos personales, más allá de que en cualquier momento podría actualizarlos también desde el área privada.

 

CSS y Javascript

Los ficheros css/stic-style.css y js/stic-js.js contienen respectivamente el código CSS y Javascript usado en el plugin. Pueden ser modificados libremente para adaptarlos a las necesidades específicas y también es posible agregar nuevos ficheros de ambos tipos siguiendo los protocolos estándares de Wordpress.

 

Otras consideraciones

1) La validación en el área privada no funciona si la directiva display_errors de PHP está activada.