Como incluir Admin Pointers en tu Theme o Plugin

  • 12/10/2013

Desde WordPress 3.3, tenemos los Avisos Personalizados que aparecen cuando hay nuevas funcionalidades. Ya lo habréis visto en algunos lados:

Tutorial admin pointers wp

Tutorial admin pointers seo-by-yoast

Estuve leyendo algunos tutoriales y he revisado los códigos. La forma más simples es la que nos presenta Frank Bueltge, de WP Engineer. He quitado partes que parecen obsoletas en el JavaScript, y he preparado una función para poder añadir más de un Pointer (aunque faltaría ajustar el PHP para esa posibilidad). Voy a dejar esa solución a cargo del estimado lector y lectora.

Lo importante es definir el ID de nuestro pointer, our_pointer_id, y ajustar el ID del elemento que queremos destacar. En este caso, el menú apariencia, #menu-appearance :

Tutorial admin pointers target

Y además, la pantalla donde queremos que aparezca usando get_current_screen() (ver explicación al final) :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
<?php
add_action( 'admin_enqueue_scripts', 'fb_enqueue_wp_pointer' );
 
function fb_enqueue_wp_pointer( $hook_suffix )
{
    if( 'themes' != get_current_screen()->id )
        return;
 
    # Este valor tambien es usado en JavaScript
    $user_pointer = get_user_setting( 'our_pointer_id', 0 ); 
    if( !$user_pointer )
    {
        $enqueue = TRUE;
        add_action( 'admin_print_footer_scripts', 'get_content_in_wp_pointer' );
        wp_enqueue_style( 'wp-pointer' );
        wp_enqueue_script( 'wp-pointer' );
        wp_enqueue_script( 'utils' ); // Usado en UserSettings
    }
}
 
function get_content_in_wp_pointer()
{
    $pointer_content = sprintf(
        '<h3>%s</h3><p>%s</p>', 
        __( 'Nuestro aviso' ), 
        __( 'Nuestra explicacion usando WP Pointers.' )
    );
    ?>
    <script type="text/javascript">
    //<![CDATA[
        jQuery(document).ready( function($) 
        {
            // Funcion generica para abrir pointers
            function open_pointer( id, content_val, edge_val, align_val, usersetting )
            {
                $(id).pointer({
                    content: content_val,
                    position: {
                        edge: edge_val,
                        align: align_val
                    },
                    close: function() {
                        setUserSetting( usersetting, '1' );
                    }
                }).pointer('open');
            }
 
            // Abrir un pointer especifico
            open_pointer( 
                '#menu-appearance', 
                '<?php echo $pointer_content; ?>', 
                'left',  // edge:  top, bottom, left, right
                'right', // align: top, bottom, left, right, middle
                'our_pointer_id'
            );
        });
    //]]>
    </script>
    <?php
}

El resultado es este:
Tutorial admin pointers resultado


Luego tenemos el excelente tutorial de Stephen Harris, donde la cosa es bastante más avanzada. Para nuestra suerte, el comentario más valorado nos ofrece todo el código adaptado a una classe reusable.

Hice una versión mesclando el código de Frank y el resultado esta en este Gist. Para configurarlo, hay que ajustar:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
<?php
add_action( 'admin_enqueue_scripts', 'fb_enqueue_wp_pointer' );
 
function fb_enqueue_wp_pointer( $hook_suffix )
{
    if( 'themes' != get_current_screen()->id )
        return;
 
    # Este valor tambien es usado en JavaScript
    $user_pointer = get_user_setting( 'our_pointer_id', 0 ); 
    if( !$user_pointer )
    {
        $enqueue = TRUE;
        add_action( 'admin_print_footer_scripts', 'get_content_in_wp_pointer' );
        wp_enqueue_style( 'wp-pointer' );
        wp_enqueue_script( 'wp-pointer' );
        wp_enqueue_script( 'utils' ); // Usado en UserSettings
    }
}
 
function get_content_in_wp_pointer()
{
    $pointer_content = sprintf(
        '<h3>%s</h3><p>%s</p>', 
        __( 'Nuestro aviso' ), 
        __( 'Nuestra explicacion usando WP Pointers.' )
    );
    ?>
    <script type="text/javascript">
    //<![CDATA[
        jQuery(document).ready( function($) 
        {
            // Funcion generica para abrir pointers
            function open_pointer( id, content_val, edge_val, align_val, usersetting )
            {
                $(id).pointer({
                    content: content_val,
                    position: {
                        edge: edge_val,
                        align: align_val
                    },
                    close: function() {
                        setUserSetting( usersetting, '1' );
                    }
                }).pointer('open');
            }
 
            // Abrir un pointer especifico
            open_pointer( 
                '#menu-appearance', 
                '<?php echo $pointer_content; ?>', 
                'left',  // edge:  top, bottom, left, right
                'right', // align: top, bottom, left, right, middle
                'our_pointer_id'
            );
        });
    //]]>
    </script>
    <?php
}

Lo más difícil es la screen, pero en verdad no lo es. Abrid la página deseada y pedir al browser que us enseñe el código fuente. Una de las primera cosas que vemos es esto:

Tutorial admin pointers HTML

Nuestra screen es el pagenow.

Bueno, ya me decís como us ha ido. Suerte!

Leave a reply

This entry was posted in Admin Interface, Tutorial on .