Agregar campos a los elementos del menú de WordPress: la página de configuración del complemento

Publicado: 2021-07-08

Al usar cualquier complemento de WordPress, probablemente haya notado que el autor ha proporcionado algunas configuraciones que puede usar para personalizar la funcionalidad del complemento. Técnicamente, el autor ha creado un elemento de menú y una página de configuración donde este elemento de menú lo redirige. En este artículo, verá los pasos que debe seguir para hacer lo mismo con su propio complemento.

El artículo requiere que ya haya aplicado el código provisto en el ejemplo en el artículo Adición de campos a los elementos del menú de WordPress - Complemento personalizado. Reanudaremos desde allí y veremos cómo podemos hacer que nuestro complemento sea más fácil de usar agregando su página de configuración en el área de administración para que permita a los usuarios administradores establecer sus preferencias sobre cómo funcionará el complemento.

Pasos iniciales

A los efectos de este artículo, crearemos un bonito menú de configuración simple. Como vimos en nuestro artículo anterior, al usar nuestro complemento, el usuario administrador puede agregar un subtítulo a cualquier elemento del menú. En los próximos pasos, proporcionaremos una opción para que el usuario pueda elegir el tipo de elemento HTML en el que se envolverá el campo de subtítulos.

En este punto, el archivo PHP principal de nuestro complemento se ve así:

 <?php /* Plugin Name: Menu Item Field Creator Description: My custom plugin to create menu item fields */ class MyCP_Menu_Item_Field_Creator { public function __construct() { add_action( 'wp_nav_menu_item_custom_fields', array( $this, 'menu_item_sub' ), 10, 2 ); add_action( 'wp_update_nav_menu_item', array( $this, 'save_menu_item_sub' ), 10, 2 ); add_filter( 'wp_nav_menu_args', array( $this, 'menu_item_sub_custom_walker' ) ); } public function menu_item_sub( $item_id, $item ) { $menu_item_sub = get_post_meta( $item_id, '_menu_item_sub', true ); ?> <div> <span class="subtitle"><?php _e( 'Subtitle', 'menu-item-sub' ); ?></span><br /> <input type="hidden" class="nav-menu-id" value="<?php echo $item_id; ?>" /> <div class="logged-input-holder"> <input type="text" name="menu_item_sub[<?php echo $item_id; ?>]" value="<?php echo esc_attr( $menu_item_sub ); ?>" /> </div> </div> <?php } public function save_menu_item_sub( $menu_id, $menu_item_db_id ) { if ( isset( $_POST['menu_item_sub'][ $menu_item_db_id ] ) ) { $sanitized_data = sanitize_text_field( $_POST['menu_item_sub'][ $menu_item_db_id ] ); update_post_meta( $menu_item_db_id, '_menu_item_sub', $sanitized_data ); } else { delete_post_meta( $menu_item_db_id, '_menu_item_sub' ); } } public function menu_item_sub_custom_walker( $args ) { if ( class_exists( 'My_Custom_Nav_Walker' ) ) { $args['walker'] = new My_Custom_Nav_Walker(); } else { echo 'DOES NOT EXIST'; } return $args; } } $mycp_menu_item_field_creator = new MyCP_Menu_Item_Field_Creator(); if ( ! class_exists( 'My_Custom_Nav_Walker' ) ) { class My_Custom_Nav_Walker extends Walker_Nav_Menu { public function start_el( &$output, $item, $depth=0, $args=[], $id=0 ) { $menu_item_sub = get_post_meta( $item->ID, '_menu_item_sub', true ); $output .= '<li class="' . implode( ' ', $item->classes ) . '">'; if ( $item->url && $item->url != '#' ) { $output .= '<a href="' . $item->url . '">'; } else { $output .= '<span>'; } $output .= $item->title; if ( $item->url && $item->url != '#' ) { $output .= '</a>'; } else { $output .= '</span>'; } if ( ! empty( $menu_item_sub ) ) { $output .= '<div class="menu-item-sub">' . $menu_item_sub . '</div>'; } } } }

Lo siguiente que haremos es continuar y crear un elemento de menú para la página de configuración de nuestro complemento, así como un ejemplo simple de lo que podría incluir en la página de configuración como contenido.

Tendremos que trabajar con dos ganchos de WordPress. El admin_menu para registrar los elementos del menú de administración y el admin_init para registrar las opciones del complemento más adelante cuando agreguemos la página de configuración del complemento con sus formularios. Por supuesto, también aprovecharemos al máximo las API que proporciona WordPress y utilizaremos algunas funciones integradas. Profundicemos más.

Crear el elemento del menú de la página de opciones

Para agregar el elemento del menú, agregaremos el admin_menu correspondiente dentro del método __construct() debajo de los enlaces agregados actualmente.

 class MyCP_Menu_Item_Field_Creator { public function __construct() { add_action( 'wp_nav_menu_item_custom_fields', array( $this, 'menu_item_sub' ), 10, 2 ); add_action( 'wp_update_nav_menu_item', array( $this, 'save_menu_item_sub' ), 10, 2 ); add_filter( 'wp_nav_menu_args', array( $this, 'menu_item_sub_custom_walker' ) ); add_action( 'admin_menu', array( $this, 'plugin_settings_menu_page' ) ); } . . .

Usamos el gancho admin_menu y definimos el método plugin_settings_menu_page() (que describiremos a continuación) para especificar la información para el elemento del menú y la página de configuración del complemento.

 public function plugin_settings_menu_page() { add_menu_page( __( 'Page Title Attribute Text', 'oop-menu-item-sub' ), __( 'Menu Item Field Creator', 'oop-menu-item-sub' ), 'manage_options', 'menu-item-field-creator', array( $this, 'plugin_settings_page_content' ) ); }

El método también debe colocarse dentro de la clase principal del complemento. Tenga en cuenta que dentro de nuestro método plugin_settings_menu_page() usamos la función add_menu_page() que proporciona WordPress. Esta función acepta los siguientes argumentos:

 add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position )

Se requiere definir $page_title y es básicamente la primera parte de las etiquetas de título de la página a la que es redirigido al seleccionar este elemento del menú.
El $menu_title -también obligatorio- es el texto que se utilizará para el menú.
$capability es la capacidad requerida para que el usuario muestre este menú. En nuestro caso, elegimos el permiso manage_options ya que se otorga solo a Superusuarios y Administradores. Si desea comprender qué rol o capacidad se ajusta a sus necesidades, puede consultar la documentación oficial relacionada.
El $menu_slug también es obligatorio y debe ser único. Es el nombre del slug para referirse a este menú. No olvide que solo debe usar caracteres alfanuméricos en minúsculas, guiones y guiones bajos que sean compatibles con sanitize_key() .
$icon_url es un argumento opcional y es la URL que enlaza con el archivo de icono que se usará para el elemento del menú.
El argumento $function es donde define la función de devolución de llamada que creará el contenido de la página de configuración. En nuestro caso, es plugin_settings_page_content() , que aún no tiene funcionalidad. Lo agregamos a nuestro código usando el método plugin_settings_menu_page() .

 public function plugin_settings_page_content() { $html = "<p>Test content for our custom plugin</p>"; echo $html; }

En este punto, debería ver el elemento de menú "Creador de campo de elemento de menú" y el contenido de prueba de la página de contenido y reconocer la URL del menú que definió en los argumentos.

También nos gustaría señalar que si desea incluir la opción de su complemento en el menú de configuración incorporado y no como un elemento de menú de nivel superior separado, puede hacerlo fácilmente utilizando la función add_options_page() en su lugar. En ese caso, debe reemplazar esto:

 public function plugin_settings_menu_page() { add_menu_page( __( 'Page Title Attribute Text', 'oop-menu-item-sub' ), __( 'Menu Item Field Creator', 'oop-menu-item-sub' ), 'manage_options', 'menu-item-field-creator', array( $this, 'plugin_settings_page_content' ) ); }

con este:

 public function plugin_settings_menu_page() { add_options_page( __( 'Page Title Attribute Text', 'oop-menu-item-sub' ), __( 'Menu Item Field Creator', 'oop-menu-item-sub' ), 'manage_options', 'menu-item-field-creator', array( $this, 'plugin_settings_page_content' ) ); }

Esto resultará en una ubicación de menú aquí:

En nuestra próxima sección, pondremos contenido simple en la página de configuración que el usuario administrador puede usar para configurar el comportamiento del complemento.

Agregar funcionalidad a nuestra página de configuración

Lo que hemos hecho hasta ahora es agregar nuestro elemento de menú y definir la función que mostrará la página de contenido de configuración. Si queremos funcionalidad en nuestra página de configuración, tendremos que registrar algunos campos y luego mostrarlos en la página de configuración del complemento. Como ejemplo, crearemos un formulario donde el usuario puede definir el tipo de elemento HTML para envolver el campo de subtítulos.

La salida

Reemplace el código plugin_settings_page_content con esto:

 public function plugin_settings_page_content() { ?> <form action="options.php" method="post"> <?php do_settings_sections( 'options_page' ); settings_fields( 'option_group' ); submit_button( __( 'Save Subtitle', 'oop-menu-item-sub' ) ); ?> </form> <?php }

En estas líneas usamos las do_settings_sections() y settings_fields() . do_settings_sections() imprimirá todas las secciones y campos de configuración que están registrados. El settings_fields() generará los campos de entrada ocultos nonce, action y option_page para la página de configuración.

Ahora procedamos y registremos nuestra configuración.

Registre su configuración

Para registrar los campos requeridos, usaremos el admin_init ya que se activa cuando se inicializa una pantalla de administración.

 class MyCP_Menu_Item_Field_Creator { public function __construct() { add_action( 'wp_nav_menu_item_custom_fields', array( $this, 'menu_item_sub' ), 10, 2 ); add_action( 'wp_update_nav_menu_item', array( $this, 'save_menu_item_sub' ), 10, 2 ); add_filter( 'wp_nav_menu_args', array( $this, 'menu_item_sub_custom_walker' ) ); add_action( 'admin_menu', array( $this, 'plugin_settings_menu_page' ) ); add_action( 'admin_init', array( $this, 'plugin_register_settings' ) ); } . . .

Insertaremos el método plugin_register_settings() dentro de nuestra clase así:

 public function plugin_register_settings() { register_setting( 'option_group', 'option_name' ); add_settings_section( 'section_id', __( 'Settings Page Title', 'oop-menu-item-sub' ), array( $this, 'render_section' ), 'options_page' ); add_settings_field( 'html_element', __( 'Choose HTML Element:', 'oop-menu-item-sub' ), array( $this, 'render_field' ), 'options_page', 'section_id' ); }

Ahora demos un paso atrás y echemos un vistazo de nuevo a lo que hemos hecho hasta ahora.

Para registrar una configuración y sus datos, usamos la función register_setting () que, según la documentación, está estructurada así:

 register_setting( $option_group, $option_name, $args )

El $option_group es un parámetro obligatorio y debe coincidir con el nombre del grupo utilizado en settings_fields() .
También se requiere $option_name y es el nombre de la opción que se desinfectará y guardará. Es el valor bajo la columna option_name en la tabla de la base de datos de opciones.
El $args no es necesario aquí. Es una matriz de datos opcional que describe la configuración cuando se registra. Lo que puede especificar aquí es su tipo, descripción, una función sanitize_callback() para el valor de la opción, una opción " show_in_rest " que define si los datos actuales deben incluirse en la API REST y una opción predeterminada donde puede definir el valor predeterminado al llamar a get_option() .
También presentamos las add_settings_section() y add_settings_field() que nos ayudarán a completar este paso.
La función add_settings_section() se utiliza para registrar una sección con un determinado nombre de slug en WordPress. Aquí, el $id es el nombre del slug para identificar la sección y se usa en el atributo 'id' de las etiquetas.

 add_settings_section( $id, $title, $callback, $page )

$title es el título formateado de la sección que se mostrará como encabezado de la sección, $callback es la función que reflejará el contenido en la parte superior de la sección y $page es el nombre de la página que debería haga coincidir el argumento $page de do_settings_sections() , que en nuestro caso es "options_page".

Todos los parámetros anteriores son obligatorios.

La función add_settings_field () que proporciona WordPress le permite agregar un nuevo campo a una sección.

 add_settings_field( $id, $title, $callback, $page, $section, $args )

El $id , $title , $callback y $page se usan como se explicó anteriormente. $section es el nombre de slug de la sección de la página de configuración en la que se muestra el cuadro y $args se usa al generar el campo. Tanto $section como $args son opcionales.

A los efectos de este artículo, no introduciremos una función adicional para desinfectar nuestros valores. Sin embargo, notaremos que es muy recomendable que siempre desinfecte los campos de su formulario.

Ahora tenemos dos métodos públicos que deben introducirse, render_section() y render_field() .

Para el método render_section() solo un encabezado para nuestra sección:

 public function render_section() { ?> <h2><?php _e( 'Section #1', 'oop-menu-item-sub' ); ?></h2> <?php }

Para el método render_field() 3 botones de radio con nuestras opciones para el elemento HTML:

 public function render_field() { $stored_option = get_option( 'option_name' )['html_element']; ?> <input type="radio" name="option_name[html_element]" value="div" <?php checked( $stored_option, 'div' ); ?> /> div <input type="radio" name="option_name[html_element]" value="p" <?php checked( $stored_option, 'p' ); ?> /> p <input type="radio" name="option_name[html_element]" value="span" <?php checked( $stored_option, 'span' ); ?> /> span <?php }

Este debería ser el resultado que ves ahora:

Si elige otro elemento, como span por ejemplo, y lo guarda, también debería funcionar correctamente.

Refleje los cambios en la página de opciones en su sitio web

El último paso que queda por explicar es cómo aplicar el elemento HTML que los usuarios administradores elegirán al elemento de subtítulos debajo del elemento del menú en la parte frontal del sitio web.

Este paso es realmente simple ya que lo único que necesitamos es recuperar el campo seleccionado de la tabla de opciones de la base de datos y modificar la Clase “ My_Custom_Nav_Walker ” en nuestro código. Específicamente, tendremos que reemplazar la parte del código donde agregamos la entrada menu_item_sub a la variable $output .

 $output .= '<div class="menu-item-sub">' . $menu_item_sub . '</div>';

Primero obtendremos el elemento con get_option( 'option_name' )['html_element']; y guárdelo en una variable $stored_option y luego aplíquelo a la línea anterior. La clase final debería verse así:

 if ( ! class_exists( 'My_Custom_Nav_Walker' ) ) { class My_Custom_Nav_Walker extends Walker_Nav_Menu { public function start_el( &$output, $item, $depth=0, $args=[], $id=0 ) { $menu_item_sub = get_post_meta( $item->ID, '_menu_item_sub', true ); $output .= '<li class="' . implode( ' ', $item->classes ) . '">'; if ( $item->url && $item->url != '#' ) { $output .= '<a href="' . $item->url . '">'; } else { $output .= '<span>'; } $output .= $item->title; if ( $item->url && $item->url != '#' ) { $output .= '</a>'; } else { $output .= '</span>'; } $stored_option = get_option( 'option_name' )['html_element']; if ( ! empty( $menu_item_sub ) ) { $output .= '<'. $stored_option .' class="menu-item-sub">' . $menu_item_sub . '</'. $stored_option .'>'; } } } }

A veces ayuda visualizar cómo funcionan las funciones de WordPress al crear una página de configuración mientras mira el código de nuestro complemento. Así es como se ve en nuestro ejemplo:

Conclusión

Como se habrá dado cuenta, la API de configuración de WP es la herramienta principal aquí que nos permite crear los huesos para la página de opciones de nuestro complemento. Aparte de eso, es su elección decidir si usará un enfoque más orientado a objetos con clases o usará la ruta más simple donde simplemente pega las funciones y enlaces en el archivo PHP del complemento principal.

Señalemos aquí que la ruta que seguimos para reconstruir el complemento no es realmente OOP, pero definitivamente dio un paso en esa dirección. En una próxima serie de artículos sobre programación orientada a objetos, profundizaremos en las otras características que pueden mejorar la administración de nuestro complemento.

Crear una página de configuración para nuestro complemento personalizado puede volverse un poco confuso, pero con suerte, después de leer este artículo, comprenderá lo que se requiere. ¡Feliz codificación!

Leer también

Agregar campos personalizados a los elementos del menú de WordPress
Agregar campos a los elementos del menú de WordPress: complemento personalizado