Agregar Participantes Vinculante

Agregar participantes es un componente creado con el objetivo de poder seleccionar participantes de un proceso. Utilizando este componente, se pueden agregar también grupos de colaboradores como participantes.

Este componente permite dos modos de uso:

Forma vinculada: se pueden agregar participantes individuales y grupos. Los procesos en dónde estén involucrados Grupos se mantengan actualizados de forma automática, si se realizan contrataciones, desvinculaciones o movilidades dentro de la empresa.

Forma spot: al guardar el formulario, se agregarán aquellas personas miembros del Grupo seleccionado en ese minuto.

Playground

Seleccionar participantes y/o grupos

Resultado despues de guardar:

Cambiar label

Mostrar grupo externo

Mostrar uso spot

Ruby

<%= participants_select_widget(
            employees_selected: selected_employees,
            resource: benefit_plan, <- Recurso que está utilizando el selector
            label: 'Seleccionar participantes y/o grupos',
            spot_use: false, <- Indica si el componente se usa de manera vinculada o spot
            user: current_user
          ) %>

JS

Todos estos métodos se encuentran en el archivo packs/plataforma/building_blocks/add_participants/app/assets/javascripts/add-participants-widget.js

Función para definir el template de resultado de busqueda y de selección del componente Select2.
En este caso, toma la clase con que venga la opción, y si es "employee", le asigna el icono de usuario.
Adicionalmente, se encarga de darle la clase "warning" a aquellos grupos que no son propios del usuario.

function formatState(state) {
  const groupIcon = '<span class="material-icons">groups</span> <span><span></span></span>';
  const isGroup = (typeof state?.id === 'string' && state?.id?.includes('group'));
  var $state = $(
    isGroup ? groupIcon : '<span><span></span></span>'
  );
  if (state?.element?.className === 'external-group') {
    $state = $('<span class="material-icons">groups</span><span class="external-group-selected"><span></span></span>');
    $(function () {
      $('.external-group-selected').each(function () {
        $(this).parent().addClass('warning');
      });
    });
  }
  $state.find('span').text(state.text);
  return $state;
}


En este otro método, se define todos los aspectos necesarios para que el componente select2
se vea como se espera en Agregar Participantes Vinculado.

onmount('.add-participants-select2', async function () {
  const selector = $(this);=
  $(function () {
    selector.select2({
      templateSelection: formatState,  <- Define cómo se muestra la selección, es decir, los chips de los participantes ya seleccionados.
      templateResult: formatState, <- Define cómo se muestra los resultados de búsqueda, en otras palabras, las opciones para elegir.
      allowClear: true,  <- Permite y muestra una opción para borrar todo lo seleccionado.
      placeholder: '',  <- Define el texto por defecto en el selector. Para que funcione allowClear, debe estar.
      closeOnSelect: false,  <- Permite que las opciones del selector se mantengan abiertas mientras se selecciona participantes.
      ajax: {  <- Permite realizar búsqueda de opciones mediante AJAX y formattea los resultados según lo necesario
        data: function (params) {
          const data = selector.select2('data');
          let selectedIds = data.map((ele) => (ele.id));
          const query = {
            search: params.term,
            selectedIds: selectedIds,
          };
          return query;
        },
      },
    });
  });
});

Lista de parámetros

Parámetro

Tipo

Detalle

label	String	Texto para el label sobre el selector
employees_selected	Array	Arreglo de empleados ya seleccionados. Cada empleado debe venir en formato [nombre o texto del empleado, id]
resource	Object	Recurso que está utilizando el agregar participantes
spot_use	Boolean	Indica si se está utilizando el componente de forma spot o no. Si es true, agrega un input oculto demostrando que es no_linked, para luego agregar los participantes de forma individual
user	Object	Usuario actual viendo el componente. Utilizado para comparar qué grupos son propios y cuáles son ajenos.

¿Cómo usar?

Uso Dinámico

El uso dinámico se refiere a poder agregar tanto participantes como grupos. Aquellos grupos quedarán vinculados, es decir, se materializarán sus participantes y se mantendrán actualizados de forma automática según el filtro que cumplan.

Para utilizar el componente y poder guardar tanto los participantes como los grupos de forma vinculada, se deben usar los siguientes callbacks en el controlador:

prepend_before_action :find_groups_ids_in_params, only: [:create, :update]
after_action :update_link, only: [:create, :update]

Estos callbacks funcionan de la siguiente manera:

• find_groups_ids_in_params quita los grupos de los params, interpretando los IDs y guardándolos para su posterior uso.

• update_link toma estos ids de grupos y genera las vinculaciones y desvinculaciones pertinentes, a través de FilterQueryAssignment.

Uso Spot

El uso spot busca facilitar poder agregar como participantes de un proceso a todos aquellos colaboradores que cumplan con cierto criterio en ese minuto del tiempo. Los grupos agregados no quedan guardados, sino quedarán guardados los colaboradores que pertenezcan a ese grupo en ese momento.

Como solo nos interesa que agregue a los participantes de forma individual, usamos el comportamiento habitual. Por ello, solo necesitamos traducir los grupos a sus colaboradores antes de crear y/o editar.

prepend_before_action :find_groups_ids_in_params, only: [:create, :update]

Casos de uso

Uso Dinámico

No hay participantes agregados anteriormente

1- El administrador va a visualizar un campo donde debe ingresar los participantes

2- Cuando haga click para desplegar el campo, se van a visualizar primero las opciones de grupo disponibles y luego la de empleados. Puede seleccionar directamente, o comenzar a escribir en el buscador, y el desplegable va a buscar las opciones que coincidan.

3- Al hacer click en un grupo se va a agregar dentro del campo y el administrador va a poder seguir buscando. Podemos combinar grupos e individuos, los podemos diferenciar, ya que las etiquetas de grupos tienen un icono a la izquierda.

4- Para poder limpiar el Agregar Participantes, podemos eliminar todos los seleccionados desde la “X” o hacerlo de manera individual. Esto se puede ser realizar con el campo desplegado/activo.

Hay participantes agregados anteriormente

El administrador visualiza un campo que tiene seleccionados los participantes individuales, debido a que se ingresaron con el Agregar Participantes. Si quiere visualizar más participantes ya seleccionados, el campo cuenta con scroll para la visualización de los seleccionados

Hay un grupo ya agregado que no es propio - "Grupos de terceros"

Como administrador de un proceso en donde se pueden vincular Grupos, puede suceder que otra persona haya vinculado grupos propios a algún proceso que yo deseo editar.

Para poder distinguir los grupos propios de los de terceros, estos últimos van a ser de color amarillento, propio de un estado de “cuidado o alerta” y también se mostrará el nombre del administrador autor que creó el grupo (Se verá "Nombre Grupo, (Autor)").

Debido a que los grupos son personales y sujetos al limite de área de la persona, no es posible visualizar grupos creados por otros administradores en el desplegable de búsqueda del Agregar Participantes, ya que solo muestra los grupos que el administrador creó. Por lo tanto, una vez eliminado el grupo de terceros, no es posible recuperar la selección por parte de ese administrador. Este administrador deberá avisar al administrador autor, que es propietario del grupo original, para que lo vuelva a agregar.

Para reforzar este mensaje o comportamiento, se va a visualizar una alerta del mismo color que los grupos de terceros, describiendo el comportamiento de los mismos.

Uso Spot

Se consideró, en esta versión del Agregar Participantes, las circunstancias en donde los administradores necesitan la rapidez que ofrece el seleccionar un grupo, pero no necesitan que en ese proceso la nómina se actualice. En cambio, los administradores buscan seleccionar los miembros del grupo de “ese momento”.

Por ejemplo, se podría usar en encuestas, evaluaciones o comunicaciones, se necesita llegar al grupo de personas en un momento determinado y no tiene sentido que esa selección se actualice luego.

Para esos casos se desarrolló el modo Spot en Agregar Participantes, que te permite seleccionar grupos, con la rapidez de un click, pero al momento de EJECUTAR EL PROCESO (crearlo, enviarlo) deja registrados los individuos que pertenecían al grupo en ese momento.

1- Se despliega el formulario con el componente. Este permite agregar tanto participantes directos como grupos.

2- Al elegir grupos y guardar, esto activa el que se guarden aquellos colaboradores que cumplen con las condiciones del grupo en ese momento de forma individual. Al volver a entrar al formulario, se puede chequear que haya pasado esto.