La API de opciones de WooCommerce (I)

Entre otros muchos cambios, WooCommerce 2.0 trajo una renovación completa de su Settings API. Aunque no es de mi total agrado ya que el encapsulado de clases no es óptimo, nos hace muchísimo más fácil añadir nuestra propia pestaña a las opciones de WooCommerce, una práctica más que recomendable si queremos extenderlo. Crear nuestro propio plugin para WooCommerce puede traer varias preguntas, una de ellas es ¿Dónde poner las opciones de nuestro plugin? Crear un nuevo submenú sería absurdo si ya disponemos de una pantalla que WooCommerce trae de serie y que podemos extender a nuestro antojo. Además, en muchos casos podemos aprovecharnos del sistema de validación que WooCommerce trae de serie.

A grandes rasgos, esto es lo que tendremos que hacer:

  1. Añadir nuestra propia pestaña en la pantalla de opciones de WooCommerce mediante un filtro y programar una nueva clase que se encargue de gestionar la pestaña.
  2. Crear las secciones necesarias dentro de dicha pestaña.
  3. Agregar campos a cada una de las secciones que hemos creado. Los campos pueden ser simples, ya sea un número o un campo de texto que WooCommerce podrá gestionar él solito.
  4. Es más que probable que necesitemos algún campo especial personalizado. Aquí no podremos hacer uso de las funciones que WooCommerce incorpora y tendremos que crearnos las nuestras propias.
  5. Validar los datos. De nuevo, WooCommerce se encargará de validar aquellos que ya lleva incorporado, para los nuestros será necesario picar un poco más de código.

Pues vamos allá.

1. Añadir nuestra propia pestaña en la pantalla de opciones de WooCommerce y programar una nueva clase que se encargue de gestionar la pestaña

Ésta es la típica imagen básica de las opciones de WooCommerce una vez instalado:

 

01-woocommerce_settings_tabs

 

Para que nuestro plugin esté completamente integrado con WooCommerce vamos a insertar una pestaña al final, después de Emails. Para ello vamos a crear primero un fichero que incluya una nueva clase que extiende de WC_Settings_Page. Dicha clase viene incluida en WooCommerce y se encarga de dar forma a cada una de las pestañas en la pantalla de opciones. Si revisamos el código de WooCommerce en includes/admin/settings/class-wc-settings-page.php podremos entender mejor porqué tenemos que extender de dicha clase pero requeriría un poco de tiempo explicarla a fondo. Es más o menos sencilla de entender si vamos mirando línea por línea.

Vamos a crear un nuevo fichero llamado class-wc-settings-holadolly.php dentro de nuestro plugin que importaremos más adelante. Aquí tenemos la estructura básica de la clase:

En el constructor de la clase tenemos la información necesaria para la pestaña. Toda pestaña necesita una ID y un título que son propiedades dentro de la misma clase pero lo que realmente incluye la pestaña es el hook que viene inmediatamente después, woocommerce_settings_tabs_array, que llama a un método llamado add_settings_page dentro de la clase padre, WC_Settings_Page. Dicho método no necesitamos implementarlo nosotros, la clase padre se encargará de recoger la ID y el título de la pantalla y mostrarlo correctamente. Por último el filtro incluye una prioridad que hemos puesto a 20 para que la pestaña se muestre al final de la cola.

Ojo con la última línea porque estamos creando una instancia de la clase nada más incluir el archivo (cosa que todavía no hemos hecho).

Por ahora la pantalla de opciones sigue igual. Nos falta incluir nuestra clase pero no podemos hacerlo de cualquier manera, WooCommerce provee un filtro especial para ello. Aquí va el código:

Los archivos que incluyen las clases que extienden de WC_Settings_Page se añaden dinámicamente mediante este filtro y se agregan a un array que WooCommerce ya tiene rellenado con las los archivos que WooCommerce incluye por defecto. Creo que es fácil entender lo que está pasando ahí. Nuestra clase se incluye y además se instancia, con lo que ya deberíamos ver nuestra pestaña:

02-holadolly-tab

 

Obviamente, aún queda por hacer, no hemos definido ninguna opción para nuestra pestaña.

 

 2. Crear las secciones necesarias dentro de dicha pestaña.

Toca empezar a jerarquizar nuestras opciones. Vamos a crear un par de secciones dentro de nuestra pestaña. Cada sección tendrá una serie de opciones que añadiremos más tarde. Por el momento dos bastarán: Una sección general (con campos que WooCommerce gestionará automáticamente) y otra especial (que tendremos que codificar nosotros mismos).

Para crear nuestras secciones tendremos que crear un nuevo método llamado get_settings dentro de nuestra clase WC_Settings_Hola_Dolly que la clase padre llamará automáticamente. Dicho método devolverá un array con toda la información sobre nuestras secciones/campos:

Lo primero que vemos es que en el constructor hemos añadido un filtro más, ‘woocommerce_settings_’ . $this->id, que llama a un método output() que no tenemos en nuestra clase pero que sí tiene la clase padre, WC_Settings_Page. Dicho método se encarga de sacar por pantalla las opciones que estamos generando. Si no usamos ese filtro no veremos nada.

El método get_settings devuelve un array con las dos secciones bien marcadas. Si nos fijamos, aunque hay dos secciones, dentro del array tenemos cuatro elementos. Toda sección debe llevar un elemento que abre la sección ( ‘type’ => ‘title’ ) y otro que la cierra ( ‘type’ => ‘sectionend’). Si nos olvidamos de cerrarlas la página no se comportará correctamente.

Como vemos, cada sección tiene una id a la que debemos hacer referencia tanto al abrir como al cerrar la sección. Además hay otra propiedad, desc, que incluye la descripción de la sección. Dicha propiedad no es obligatoria, simplemente es el texto que aparecerá al principio de cada sección. Existen más propiedades pero no hay espacio suficiente aquí para explicar cada una de ellas, lo mejor es bucear un poco por el código de WooCommerce.

La pantalla se nos queda tal que así:

03-settings-tab-with-sections

 

Esto, lógicamente no sirve para nada, si pulsamos el botón no estaremos guardando nada. ¿Qué tal si rellenamos las secciones con unos cuantos campos?

 

3. Agregar campos simples

WooCommerce puede manejar automáticamente campos sencillos (y otros que no lo son tanto): números, texto, email, color, contraseña, áreas de texto, selects, multiselects, radios, checkboxes, ancho de imagen, selector de página, selector de país y multiselector de país. Como vemos la lista no está nada mal pero entre todos ellos vamos a escoger uno muy sencillo: Campo numérico. Este campo lo vamos a poner dentro de la sección de Opciones Generales y tendremos que darle un valor por defecto, una id, un título, indicar de qué tipo es y quizás una descripción. Muy sencillo, sólo hay que tener en cuenta que las opciones por pantalla aparecen en el mismo orden que indicamos en get_settings(), dentro del array:

Poco hay que explicar aquí, nuestro nuevo campo se define con un array tal y como hemos dicho, con un título, una id (holadolly_general_options_number), un valor por defecto ( 0 ) y un tipo de campo (number). Además le hemos añadido una propiedad llamada desc_tip que mostrará un icono con un símbolo de interrogación que al pasar el ratón por encima nos mostrará dicho texto. Podríamos haber optado por una simple descripción utilizando una propiedad desc pero así vemos la flexibilidad que WooCommerce nos ofrece.

04-settings-with-number

 

Bien, el campo se muestra correctamente con su icono de interrogación, valor por defecto, título, etc. Si cambiamos el valor a 1 y guardamos… Nada, vuelve a 0 el valor. Hay algo que todavía tenemos que hacer y es una de las cosas que no me terminan de gustar del diseño de esta clase, no es importante pero puede resultar molesto. Necesitamos decirle a la clase padre que cuando pulsemos el botón de guardar, nos guarde las opciones. Se hace mediante un filtro en el constructor de nuestra clase:

save() es un método que incluye la clase WC_Settings_Page y que guardará todas las opciones que mostremos por pantalla automáticamente a menos que le indiquemos lo contrario. Si ahora cambiamos el valor del campo y guardamos, el valor quedará guardado en base de datos, sí, ¿Pero dónde? Si volvemos un poco más arriba veremos de nuevo que dicho campo lleva asociado una id, holadolly_general_options_number, que es precisamente el slug de nuestra opción. Para recoger el valor simplemente tenndremos que llamar a get_option():

get_option('holadolly_general_options_number')

 

Aquí tenéis el código entero (es un plugin normal y corriente): https://github.com/igmoweb/woocommerce-settings-api-explained

 

Conclusión de la primera parte

Hemos aprendido a añadir nuestra propia pestaña a las opciones de WooCommerce de una manera eficaz, bien integrada y que nos evita mucho código. Un campo simple como puede ser un campo numérico es muy fácil de crear y ni siquiera hemos tenido que implementar código para tratar y guardar en Base de Datos dicho campo, WooCommerce lo ha hecho todo por nosotros: Muestra el campo, lo valida y lo guarda. También hemos aprendido a recoger su valor para usarlo donde queramos, todo en unas pocas líneas de código.

En la segunda parte del artículo aprenderemos a usar campos más avanzados que ya tendremos que mostrar, validar y guardar por nosotros mismos.

Todo esto y mucho más, muy pronto en Hola Dolly 🙂

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s