Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)
Esta es la tercera parte de una serie de artículos en los que buscamos cómo integrar mejor tu plugin o tema en la interfaz de usuario de la administración de WordPress. En esta parte vamos a ver cómo se pueden utilizar WordPress los 'indicadores de administración' en tus plugins.
Los indicadores del área de administración aparecieron por primera vez en 3.3, y estaban diseñados para destacar solo algunas de las nuevas características que vienen con cada lanzamiento de una versión principal (el personalizador de temas en 3.4, por ejemplo).
Cuando se utilizan correctamente, estos pueden ser muy eficaces para llamar la atención sobre las últimas características que hayan sido añadidas.
Descargo de responsabilidad: Los indicadores del área de administración todavía están en las primeras etapas de su vida, y existe la posibilidad de que puedan cambiar. Si el núcleo de WordPress alguna vez desarrolla una API pública, tú deberías adoptarla.
Utilízalos con moderación...
Una interfaz de usuario decente no consiste en información contextual sensacionalista. De hecho, una interfaz de usuario ideal no necesitaría ninguna. Son muy útiles para señalar la nueva característica ocasional, especialmente las que al usuario final le pueda haber pasado desapercibida. En este sentido pueden mejorar la 'experiencia de usuario', pero si los estás usando para cualquier otro propósito, o simplemente estás usando demasiados, entonces lo estás haciendo mal. En lugar de mejorar el plugin para el usuario final, acabarás frustrándolo.
¿Cuántos son demasiados? Recuerda que habrá otros plugins instalados, y cada uno puede estar haciendo también uso (o abuso) de estos indicadores. WordPress también (obviamente) los utiliza. Sería interesante medir la opinión de la gente sobre esto, pero yo mismo no añadiría más de dos en ninguna actualización importante (ninguna en las menores), y ciertamente no más de uno en una página concreta.
Es importante destacar que, sin una API principal, no hay una manera de administrar varios indicadores: si se añaden veinte indicadores a una página, se mostrarán veinte. Dado que no sabes lo que otros plugins están haciendo, por favor úsalos con moderación.
Creación de una función auxiliar
Al usar indicadores de administración en un plugin o tema, será útil poder añadir indicadores adicionales de forma fácil y rápida a medida que tu plugin evolucione. Con este fin, vamos a crear una función auxiliar que se ocupará del control interno de los indicadores. Hará uso de la MUY querida API de gancho de WordPress, y activará un filtro de la siguiente forma:
1 |
wptuts_admin_pointers_{screen-id} |
Donde {screen-id} es el ID de la página que se está visualizando. Para añadir un indicador a la página de edición de la entrada, por ejemplo, nos conectaríamos al siguiente filtro:
1 |
wptuts_admin_pointers_post
|
De esta manera, podemos agregar indicadores adicionales, usando una cantidad mínima de código. El rol de esta función auxiliar será crear una matriz de indicadores que se imprimirán en la página de administración en forma de matriz de objetos JavaScript, cada objeto se corresponde con un indicador. Cada objeto de indicador contiene los siguientes parámetros:
-
pointer_id- Un identificador único para el indicador. Una buena idea es incluir la versión para la que es relevante. Esto solo debe contener caracteres alfanuméricos en minúsculas, guiones bajos y guiones. -
target- Un selector para el objetivo del indicador, es decir, a lo que apunta (por ejemplo,#algun_ido.alguna-clase) -
options- Esta es una variedad de opciones. Podemos usar esto para alterar completamente cómo se ve y se comporta el indicador, pero para nuestros propósitos solo tenemos que considerar lo siguiente: contenido (el texto que aparece en el indicador) y la posición. La propiedad position viene determinada por:-
edge- Qué borde (izquierda, derecha, superior, inferior) debe ser adyacente al objetivo. -
aling- Cómo debe estar alineado el indicador en este borde, en relación con el objetivo (superior, inferior, izquierda, derecha, medio).
-
Un objeto de indicador típico podría tener este formato:
1 |
{
|
2 |
pointer_id: 'xyz_v110', |
3 |
target: '#some_id', |
4 |
options: {
|
5 |
content: '<h3> New feature: xyz </h3> <p> Lorem ipsum dolor sit amet...</p>', |
6 |
position: {
|
7 |
edge: 'left', |
8 |
align: 'top' |
9 |
} |
10 |
} |
11 |
} |
Una vez que los objetos de indicador se imprimen en la página de administración podemos hacer uso del widget de indicador de WordPress definido aquí.
Definición de la función auxiliar
Como se discutió en la sección anterior, el objetivo general de nuestra función es imprimir algunos objetos JavaScript en la página y cargar algún script personalizado. Así que nuestra función auxiliar se conectará a la acción wp_enqueue_scripts (aunque, podríamos llamarla más adelante).
1 |
add_action( 'admin_enqueue_scripts', 'wptuts_pointer_load'); |
2 |
function wptuts_pointer_load( $hook_suffix ) { |
3 |
// Helper function goes here
|
4 |
}
|
Recuerda, si estás utilizando este código en un plugin o tema, debes cambiar el nombre de la función, asegurándote de que sea única y preferiblemente prefíjala con el nombre de tu plugin o tu tema. La primera parte de esta función filtra una matriz vacía, utilizando el enlace wptuts_admin_pointers- screen_id. Esto nos permite agregar indicadores a esa matriz. Si no se añade nada, nos detenemos.
1 |
// Don't run on WP < 3.3
|
2 |
if ( get_bloginfo( 'version' ) < '3.3' ) |
3 |
return; |
4 |
|
5 |
// Get the screen ID
|
6 |
$screen = get_current_screen(); |
7 |
$screen_id = $screen->id; |
8 |
|
9 |
// Get pointers for this screen
|
10 |
$pointers = apply_filters( 'wptuts_admin_pointers-' . $screen_id, array() ); |
11 |
|
12 |
// No pointers? Then we stop.
|
13 |
if ( ! $pointers || ! is_array( $pointers ) ) |
14 |
return; |
Ahora estos indicadores pueden incluir los que el usuario haya visualizado antes, y 'descartado'. No queremos que aparezcan de nuevo para este usuario, así que a continuación obtenemos una matriz de indicadores que ya hayan visto y cerrado, y los eliminamos de nuestra matriz. También realizamos algunos controles de desinfección en nuestros punteros:
1 |
// Get dismissed pointers
|
2 |
$dismissed = explode( ',', (string) get_user_meta( get_current_user_id(), 'dismissed_wp_pointers', true ) ); |
3 |
$valid_pointers = array(); |
4 |
|
5 |
// Check pointers and remove dismissed ones.
|
6 |
foreach ( $pointers as $pointer_id => $pointer ) { |
7 |
|
8 |
// Sanity check
|
9 |
if ( in_array( $pointer_id, $dismissed ) || empty( $pointer ) || empty( $pointer_id ) || empty( $pointer['target'] ) || empty( $pointer['options'] ) ) |
10 |
continue; |
11 |
|
12 |
$pointer['pointer_id'] = $pointer_id; |
13 |
|
14 |
// Add the pointer to $valid_pointers array
|
15 |
$valid_pointers['pointers'][] = $pointer; |
16 |
}
|
17 |
|
18 |
// No valid pointers? Stop here.
|
19 |
if ( empty( $valid_pointers ) ) |
20 |
return; |
Finalmente ponemos en cola los scripts y estilos necesarios, e imprimimos los indicadores válidos en la página, utilizando wp_localize_script.
1 |
// Add pointers style to queue.
|
2 |
wp_enqueue_style( 'wp-pointer' ); |
3 |
|
4 |
// Add pointers script and our own custom script to queue.
|
5 |
wp_enqueue_script( 'wptuts-pointer', plugins_url( 'js/wptuts-pointer.js', __FILE__ ), array( 'wp-pointer' ) ); |
6 |
|
7 |
// Add pointer options to script.
|
8 |
wp_localize_script( 'wptuts-pointer', 'wptutsPointer', $valid_pointer ); |
La función en su totalidad
1 |
add_action( 'admin_enqueue_scripts', 'wptuts_pointer_load', 1000 ); |
2 |
|
3 |
function wptuts_pointer_load( $hook_suffix ) { |
4 |
|
5 |
// Don't run on WP < 3.3
|
6 |
if ( get_bloginfo( 'version' ) < '3.3' ) |
7 |
return; |
8 |
|
9 |
$screen = get_current_screen(); |
10 |
$screen_id = $screen->id; |
11 |
|
12 |
// Get pointers for this screen
|
13 |
$pointers = apply_filters( 'wptuts_admin_pointers-' . $screen_id, array() ); |
14 |
|
15 |
if ( ! $pointers || ! is_array( $pointers ) ) |
16 |
return; |
17 |
|
18 |
// Get dismissed pointers
|
19 |
$dismissed = explode( ',', (string) get_user_meta( get_current_user_id(), 'dismissed_wp_pointers', true ) ); |
20 |
$valid_pointers =array(); |
21 |
|
22 |
// Check pointers and remove dismissed ones.
|
23 |
foreach ( $pointers as $pointer_id => $pointer ) { |
24 |
|
25 |
// Sanity check
|
26 |
if ( in_array( $pointer_id, $dismissed ) || empty( $pointer ) || empty( $pointer_id ) || empty( $pointer['target'] ) || empty( $pointer['options'] ) ) |
27 |
continue; |
28 |
|
29 |
$pointer['pointer_id'] = $pointer_id; |
30 |
|
31 |
// Add the pointer to $valid_pointers array
|
32 |
$valid_pointers['pointers'][] = $pointer; |
33 |
}
|
34 |
|
35 |
// No valid pointers? Stop here.
|
36 |
if ( empty( $valid_pointers ) ) |
37 |
return; |
38 |
|
39 |
// Add pointers style to queue.
|
40 |
wp_enqueue_style( 'wp-pointer' ); |
41 |
|
42 |
// Add pointers script to queue. Add custom script.
|
43 |
wp_enqueue_script( 'wptuts-pointer', plugins_url( 'js/wptuts-pointer.js', __FILE__ ), array( 'wp-pointer' ) ); |
44 |
|
45 |
// Add pointer options to script.
|
46 |
wp_localize_script( 'wptuts-pointer', 'wptutsPointer', $valid_pointers ); |
47 |
}
|
El JavaScript
El script es muy simple, ya que el widget de indicador hace la mayor parte del trabajo. En este indicador todo lo que realmente necesitamos definir es lo que sucede cuando se descarta el indicador. En particular, enviamos una solicitud ajax con la acción 'dismiss-wp-pointer' y el indicador para establecer en el identificador único que especificamos al añadir el indicador.
1 |
jQuery(document).ready( function($) {
|
2 |
wptuts_open_pointer(0); |
3 |
function wptuts_open_pointer(i) {
|
4 |
pointer = wptutsPointer.pointers[i]; |
5 |
options = $.extend( pointer.options, {
|
6 |
close: function() {
|
7 |
$.post( ajaxurl, {
|
8 |
pointer: pointer.pointer_id, |
9 |
action: 'dismiss-wp-pointer' |
10 |
}); |
11 |
} |
12 |
}); |
13 |
|
14 |
$(pointer.target).pointer( options ).pointer('open');
|
15 |
} |
16 |
}); |
Ese es todo el código que necesitamos añadir, ya que WordPress maneja la solicitud ajax.
Adición de los indicadores
Como se prometió, añadir indicaciones es muy fácil. Para añadir una indicación a la pantalla 'post', por ejemplo:
1 |
add_filter( 'wptuts_admin_pointers-post', 'wptuts_register_pointer_testing' ); |
2 |
function wptuts_register_pointer_testing( $p ) { |
3 |
$p['xyz140'] = array( |
4 |
'target' => '#change-permalinks', |
5 |
'options' => array( |
6 |
'content' => sprintf( '<h3> %s </h3> <p> %s </p>', |
7 |
__( 'Title' ,'plugindomain'), |
8 |
__( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.','plugindomain') |
9 |
),
|
10 |
'position' => array( 'edge' => 'top', 'align' => 'middle' ) |
11 |
)
|
12 |
);
|
13 |
return $p; |
14 |
}
|
Nota: Al almacenar el indicador descartado, WordPress pasa el ID del mismo a través de sanitize_key, así que asegúrate de usar solo caracteres alfabéticos en minúsculas, guiones y guiones bajos.
By
