Cómo añadir un filtro de búsqueda adicional en tu listado de usuarios de WordPress

Hoy quiero mostrarte cómo hacer algo que me ha resultado muy útil en varios proyectos de clientes que he llevado a cabo.

Se trata de añadir nuevos buscadores en el listado de usuarios que filtren según el valor de un ajuste de usuario (metadatos) que estos tengan asignados.

Y para que se entienda esto, vamos con un ejemplo:

• Imagínate que tienes varios miles de usuarios dados de alta en WordPress.
• Y cada uno de ellos tiene varios metadatos asignados como pueden ser: su NIF (número de identificación fiscal), su teléfono, empleo, género…
• Si quisieras buscar dentro de ese listado con el buscador propio de WordPress, este solo filtra por el nombre, nombre de usuario y correo.
• Por lo que puede resultar útil en algunos proyectos poder añadir un buscador extra para, por ejemplo, filtrar por NIF.
• Esto lo he aplicado en algún proyecto y les resultó súper útil para no volverse locos.

Aclarado el uso de lo que voy a mostrarte, lo primero que te recomiendo antes de seguir es que te hayas visto el módulo del curso Desarrollo de plugins de WordPress llamado «Ajustes de usuario«, allí aprenderás qué son y cómo usarlos.

1- Creamos un nuevo plugin

Lo que vamos a hacer lo podrás meter en un nuevo plugin, en el archivo de funciones o en algún plugin propio que ya tengas dedicado para añadir funcionalidades extra a tus proyectos.

Yo optaré por la primera opción y llamaré a mi plugin scv-filter-by-nif y dentro meteremos el archivo principal llamado igual scv-filter-by-nif.php.

Y creamos su cabecera:

<?php
/*
* Plugin Name: Filtro por ajuste de usuario
* Plugin URI: https://silicodevalley.com/lab/filtro-ajustes-usuario
* Description: Añade un buscador para filtar por un ajuste de usuario
* Version: 1.0
* Author: David Perálvarez
* Author URI: https://silicodevalley.com
* License: GPL2
*/

2- Añadimos el NIF como nuevo ajuste de usuario

Para ello lo que hacemos es añadirlo a la página de mostrar y editar perfil de usuario.

Todo este proceso lo vimos paso a paso en la lección «Añadir sección en el perfil y página de edición de usuarios«.

El código que obtendríamos sería:

// Add field to user / edit profile
add_action( 'show_user_profile', 'scv_add_field_user_profile' );
add_action( 'edit_user_profile', 'scv_add_field_user_profile' );

function scv_add_field_user_profile( $user ){

  $nif = get_user_meta( $user->ID, 'scv_user_nif', true );

  ?>
  <h3>Datos fiscales</h3>

  <table class="form-table">
    <tr>
      <th>
        <label for="nif">NIF</label>
      </th>
      <td>
        <input type="text" class="regular-text" name="nif" id="nif" value="<?php echo esc_attr( $nif ); ?>">
        <p class="description">Introduce tu número de identificación fiscal.</p>
      </td>
    </tr>
  </table>
  <?php
}

3- Guardamos el metadato

Ahora cada vez que se pulse el botón de actualizar en el perfil del usuario, guardaremos el valor del NIF que se haya introducido.

// Save user meta
add_action( 'personal_options_update', 'scv_save_field_profile' );
add_action( 'edit_user_profile_update', 'scv_save_field_profile' );

function scv_save_field_profile( $user_id ){
  update_user_meta( $user_id, 'scv_user_nif', $_POST['nif']  );
}

4- Añadimos una nueva columna al listado de usuarios

Ahora que los usuarios tienen asignado un NIF sería interesante poder mostrar una nueva columna en el listado de usuarios de WordPress, para ver dicho valor.

Para ello hacemos uso del filtro manage_users_columns:

// Add custom column to the user's list
add_filter( 'manage_users_columns', 'scv_add_user_columns', 100 );

function scv_add_user_columns( $columns ) {

  $columns['scv_user_nif'] = 'NIF';
  return $columns;

}

Y ahora mostramos su valor:

// Show column values
add_filter( 'manage_users_custom_column', 'scv_show_column_values', 10, 3 );

function scv_show_column_values( $value, $column_name, $user_id ){
	if( $column_name == 'scv_user_nif' ):
		$value = get_user_meta( $user_id, 'scv_user_nif', true );
	endif;

	return $value;
}

Esto lo logramos gracias al filtro manage_users_custom_column, donde identificamos en qué columna nos encontramos y si es la nuestra, mostramos el NIF de ese usuario, que recuerda que lo tenemos almacenado en un metadato de usuario.

5- Ponemos un buscador nuevo encima y debajo del listado

Ahora que ya tenemos una nueva columna con la información que necesitamos, empieza nuestro trabajo de añadir la posibilidad de buscar por dicho valor.

Para hacer eso hacemos uso de la acción restrict_manage_users que nos sitúa justo encima y debajo del listado de usuarios y es allí donde añadimos nuestro buscador por duplicado.

// Add searh by NIF
add_action('restrict_manage_users', 'scv_add_search_by_nif');

function scv_add_search_by_nif( $which ){

  echo '<div style="float: right; margin: 0 4px;"><input type="text" name="nif_'.$which.'" value="" placeholder="NIF">';

  submit_button('Filtrar', 'primary', $which, false);

  echo '</div>';
}

Digo por duplicado, porque la variable $which contiene el valor top o bottom, según si está encima o debajo del listado.

Y la función submit_button, genera el botón de búsqueda de nuestro formulario y con $which identifica si se ha usado el superior o el inferior.

6- Capturamos el valor buscado y filtramos por ese valor

Desde el momento que pulsamos el botón de filtrar, la página se actualiza y es en ese instante, donde gracias a la acción pre_get_users, podemos comprobar si estamos en la página de listado de usuarios y si es el caso:

• Miramos si el usuario ha buscado por NIF desde el formulario superior o inferior (o no lo ha hecho).
• Si lo ha hecho, nos metemos dentro de la consulta (query) que se encarga de listar los usuarios y la modificamos para que filtre por NIF, gracias a añadir una meta query.

// Filter query by NIF
add_action('pre_get_users', 'scv_filter_query_by_nif');

function scv_filter_query_by_nif($query){
  global $pagenow;
  
  if (is_admin() && 'users.php' == $pagenow):

    $nif_top = $_GET['nif_top'] ? $_GET['nif_top'] : null;
    $nif_bottom = $_GET['nif_bottom'] ? $_GET['nif_bottom'] : null;

    $nif = !empty($nif_top) ? $nif_top : $nif_bottom;
  
    if ( !empty($nif) ):

      // change the meta query based on which option was chosen
      $meta_query = array (array (
        'key' => 'scv_user_nif',
        'value' => $nif,
        'compare' => 'LIKE'
      ));
      $query->set('meta_query', $meta_query);

    endif;

  endif;
}

Para entender bien este paso te recomiendo que realices el curso de WP_Query.

¡Y con este último paso ya lo tendríamos listo!

Como siempre testea bien el plugin para comprobar su funcionamiento. Espero que te haya gustado, te haya resultado útil y lo puedas usar en futuros proyectos 🙂