Cómo extender SaveTo Wishlist con hooks y la API REST

¿Estás creando una integración personalizada, cambiando el aspecto del botón de la lista de deseos o reaccionando cuando un cliente guarda un producto? SaveTo Wishlist te proporciona filtros y acciones de WordPress para cada una de estas tareas, además de una API REST para leer y modificar listas de deseos. Este artículo enumera los hooks y las rutas que vienen con SaveTo Wishlist Lite 1.1.8, con los argumentos que cada uno recibe y un ejemplo funcional para los casos comunes.

Antes de empezar

• Necesitas tener activos en el sitio SaveTo Wishlist Lite y WooCommerce. SaveTo Wishlist Pro y Registry añaden sus propios hooks, que no se cubren aquí.
• Cada nombre de hook comienza con stwlite_.
• Coloca tu código en un pequeño plugin personalizado o en un plugin de fragmentos de código. Añade los filtros de ubicación (ver más abajo) en un archivo de plugin, no en el archivo functions.php de un tema.
• Cada hook y ruta en este artículo existe en SaveTo Wishlist Lite 1.1.8. Un hook que no aparece aquí no forma parte de la interfaz pública, así que no dependas de él.

Hooks

Cada hook a continuación enumera su tipo, los argumentos que recibe y lo que hace. Cuando registres una función de devolución de llamada que acepte más de un argumento, pasa el recuento de argumentos como cuarto parámetro de add_filter() o add_action(), como muestran los ejemplos.

Salida del botón

Estos filtros cambian el marcado del botón de la lista de deseos antes de que se imprima. El plugin pasa el marcado final a través de wp_kses(), por lo que las etiquetas y atributos que no estén en su lista de permitidos se eliminan. Para permitir más etiquetas, usa el filtro stwlite_allowed_button_html, que recibe la matriz de la lista de permitidos.

Este ejemplo añade una breve nota después del botón para los productos en oferta:

add_filter( 'stwlite_wishlist_button_html', function ( $button_html, $product, $placement, $style, $button_label ) {
    if ( '' === $button_html || ! $product instanceof WC_Product || ! $product->is_on_sale() ) {
        return $button_html;
    }

    return $button_html . '<span class="my-sale-note">On sale</span>';
}, 10, 5 );

Ubicación, estilo y etiquetas del botón

Estos filtros cambian dónde aparece el botón y cómo se ve. Cada uno recibe la configuración guardada y devuelve el valor a utilizar.

Las ubicaciones de la tienda son top_right, top_left, above_title, below_title, above_button, below_button y disable. Las ubicaciones de la página de producto son top_image_right, top_image_left, top_cart, bottom_cart, inline_cart, top_title, bottom_title y disable. El plugin lee la ubicación una vez, cuando se inicia en el hook setup_theme con prioridad 100. Por lo tanto, un filtro de ubicación debe añadirse antes de ese punto, así que regístrelo en un archivo de plugin y no en el archivo functions.php de un tema. Los filtros de estilo, etiqueta y color se ejecutan cada vez que se renderiza un botón, por lo que funcionan desde cualquier código.

add_filter( 'stwlite_wishlist_button_product_placement', function ( $placement ) {
    return 'bottom_cart';
} );

Para la pantalla de configuración correspondiente, consulta Cómo personalizar la ubicación y los estilos del botón de la lista de deseos en WooCommerce.

Datos de la lista de deseos

Estos filtros modifican los datos de la lista de deseos tal como los lee el plugin. Se ejecutan en muchas solicitudes, incluidas las comprobaciones de propiedad y permisos, así que mantén tus callbacks rápidos. No modifiques los valores de id, user_id, status o is_public, ya que el plugin los lee para decidir quién puede ver una lista de deseos.

Este ejemplo elimina la descripción de los objetos de lista de deseos en las respuestas de la lista:

add_filter( 'stwlite_collections_data', function ( $collections ) {
    foreach ( $collections as $collection ) {
        $collection->description = '';
    }

    return $collections;
} );

Acceso a la lista de deseos del usuario

Estos filtros deciden quién puede leer o poseer una lista de deseos. Para una solicitud de lectura, el plugin primero permite a los administradores con la capacidad manage_options, luego al propietario de la lista de deseos, luego a las listas de deseos publicadas públicas, luego a sus propias reglas de uso compartido. Solo después de esas comprobaciones llama a stwlite_user_wishlist_access.

Este ejemplo permite a los gerentes de la tienda leer cualquier lista de deseos:

add_filter( 'stwlite_user_wishlist_access', function ( $granted, $wishlist, $user_id, $request ) {
    if ( $user_id && user_can( $user_id, 'manage_woocommerce' ) ) {
        return true;
    }

    return $granted;
}, 10, 4 );

Acciones de la lista de deseos

Utiliza estas acciones para reaccionar cuando algo cambie, por ejemplo, para sincronizar datos con un CRM o escribir una entrada de registro.

Este ejemplo almacena el último producto que un cliente guardó en sus metadatos de usuario:

add_action( 'stwlite_after_product_added_to_wishlist', function ( $product_id, $quantity, $collection_id, $user_id, $added ) {
    if ( ! $added || ! $user_id ) {
        return;
    }

    update_user_meta( $user_id, 'my_last_wishlisted_product', (int) $product_id );
}, 10, 5 );

Pestañas y controles de configuración del administrador

La pantalla de configuración crea sus pestañas y campos a partir de matrices. Utilice estos filtros para agregar su propia pestaña, sección o campo, o para cambiar uno existente.

Las pestañas se encuentran debajo de la clave principal saveto_wishlist. Las claves de las pestañas secundarias son general, wishlist_page, wishlist_guest, wishlist_button y importer. Cada pestaña secundaria contiene sort, key, label, icon y una matriz sections. La matriz de controles tiene como clave $controls[ 'saveto_wishlist' ][ $tab_key ][ $section_key ], y cada sección contiene una lista de matrices de controles. Un control tiene un type (por ejemplo, switch o select), una label, un id que es el nombre de la opción, una description y un default. Los controles de tipo switch utilizan los valores yes y no.

Este ejemplo agrega un interruptor a la pestaña General. Asume la clave de sección save_to_wishlist_settings, que es la primera sección de esa pestaña.

add_filter( 'stwlite_admin_setting_default_general_tab_controls', function ( $controls ) {
    $controls['save_to_wishlist_settings'][] = array(
        'type'        => 'switch',
        'label'       => __( 'Log wishlist adds', 'my-plugin' ),
        'id'          => 'my_plugin_log_wishlist_adds',
        'description' => __( 'If Yes, write an entry to the debug log when a customer saves a product.', 'my-plugin' ),
        'options'     => array(
            'yes' => __( 'Yes', 'my-plugin' ),
            'no'  => __( 'No', 'my-plugin' ),
        ),
        'default'     => get_option( 'my_plugin_log_wishlist_adds', 'no' ),
    );

    return $controls;
} );

La pantalla de configuración guarda cada valor de control a través de la ruta de configuración del administrador descrita más adelante en este artículo. Dos filtros dinámicos le permiten manejar una guarda o un botón usted mismo:

• stwlite_group_settings_{action} es un filtro que recibe los valores guardados como $options cuando el payload de la configuración contiene una clave llamada action. Devuelve la matriz de respuesta con status y message.
• stwlite_trigger_{action} es un filtro que recibe los parámetros de la solicitud como $params cuando se llama a la ruta de acción. Devuelve una matriz con status y message, y una URL de redirect opcional.

Traducciones del frontend

La página de la lista de deseos carga estas cadenas dos veces por solicitud, por lo que su callback debe fusionar en un mapa y evitar trabajos pesados. Este ejemplo cambia una cadena. Utilice una clave que ya exista en la matriz.

add_filter( 'stwlite_frontend_translations', function ( $i18n ) {
    $i18n['just_now'] = __( 'a moment ago', 'my-plugin' );

    return $i18n;
} );

Datos de seguimiento de uso

Cuando una tienda ha permitido el seguimiento de uso, el plugin envía una verificación periódica. Estos filtros permiten que un plugin complementario añada datos a esos datos. Los valores deben ser escalares y no deben contener credenciales ni datos personales.

La configuración "Seguimiento de uso" en la pestaña General controla el consentimiento. Si una tienda la establece en No, el plugin no informa, independientemente de lo que devuelvan sus filtros.

API REST

Todas las rutas utilizan el espacio de nombres saveto-wishlist/v1, por lo que la ruta completa es https://your-site.com/wp-json/saveto-wishlist/v1/ seguida de la ruta en las tablas. Siguen la autenticación normal de la API REST de WordPress. El código del navegador envía la cabecera X-WP-Nonce para un usuario conectado, y otros clientes pueden usar una contraseña de aplicación con autenticación HTTP Basic. Una solicitud rechazada devuelve el error rest_forbidden_context con estado 401 para un llamador desconectado o 403 para uno conectado.

Rutas de cliente

Estas rutas potencian el botón de la lista de deseos y la página de la lista de deseos.

La ruta POST /frontend/endpoints siempre responde con HTTP 200 y un campo status, así que comprueba status en el cuerpo. Un llamador que no posee la lista de deseos recibe status establecido en error. Solo los usuarios con la capacidad manage_options pueden escribir en la lista de deseos de otro usuario.

Esta solicitud lista las listas de deseos de la cuenta que posee la contraseña de la aplicación:

curl -u "username:application-password" \
  "https://your-site.com/wp-json/saveto-wishlist/v1/frontend/endpoints/wishlists"

Estos filtros cambian quién pasa las comprobaciones de la ruta del cliente y qué devuelve la ruta de invitado:

Rutas de administrador

Las rutas a continuación sirven a las propias pantallas de administración del plugin y pueden cambiar entre versiones. Prefiera los hooks anteriores para integraciones. Cada ruta de administrador requiere la capacidad manage_options. Use el filtro stwlite_api_admin_permissions_check ($response, $request) para cambiar eso, y tenga cuidado al ampliar el acceso, ya que estas rutas pueden escribir opciones del sitio y eliminar listas de deseos.

Las fuentes de importación integradas son yith, ti, moreconvert y wpc. Utilice el filtro stwlite_available_importers, que recibe y devuelve una matriz que mapea un slug de fuente a un nombre de clase de importador, para registrar otra.

Preguntas frecuentes

¿Por qué mi filtro de ubicación no hace nada?

El plugin lee la ubicación cuando se inicia en el hook setup_theme con prioridad 100. Agregue el filtro desde un archivo de plugin. Un archivo functions.php del tema se carga después de ese punto.

¿Por qué mi marcado de botón pierde una etiqueta o atributo?

El plugin procesa el marcado del botón a través de wp_kses(). Agregue la etiqueta o el atributo a la lista de permitidos con el filtro stwlite_allowed_button_html.

¿Por qué la ruta de guardado devuelve HTTP 200 para una solicitud rechazada?

POST /frontend/endpoints siempre responde con HTTP 200 y pone el resultado en el campo status del cuerpo. Lea status y message en lugar del código HTTP.

¿Qué sigue?

• Cómo extender SaveTo Wishlist Pro con hooks y la API REST
• Cómo extender SaveTo Wishlist Registry con hooks y la API REST
• Cómo usar las habilidades de IA en SaveTo Wishlist

¿Necesitas ayuda?

Si tienes alguna pregunta o encuentras algún problema, estamos aquí para ayudarte.

• Usuarios premium: Abrir un ticket de soporte
• Usuarios gratuitos: Visita nuestro foro comunitario