Extending WordPress with custom API endpoints, HTMX example

[jasalt]

Adding custom /wp-json/ "REST API" endpoints provides a quick and dirty but already surprisingly functional way to extend WordPress with new interactive functionality leveraging Phel HTML templating and HTMX.

241129-phel-plugin-2024-11-30_17.04.39.mp4

Minimal example shown in video with main.phel content as follows:

(ns phel-wp-plugin\main
  (:require phel\html :refer [html])
  (:require phel\http))

(defn phel-widget-content []
  (println (html [:div
                  [:script {:src "https://unpkg.com/htmx.org@2.0.3" :crossorigin "anonymous"}]
                  [:button {:hx-get (str "/wp-json/phel/html?_wpnonce=" (php/wp_create_nonce "wp_rest"))
                            :type "submit"
                            :hx-target "#htmx-target" :hx-swap "afterbegin"}
                   "Press me!"]
                  [:div {:id "htmx-target"}]])))

(php/add_action "wp_dashboard_setup"
                (fn [] (php/wp_add_dashboard_widget "phel-widget-id"
                                                    "Phel HTMX demo"
                                                    phel-widget-content)))

(php/add_action
 "rest_api_init"
 (fn []  # GET Endpoint `/wp-json/phel/html` returning HTML content for HTMX
   (php/register_rest_route
    "phel" "/html"
    (to-php-array
     {"methods"  "GET"
      # "permission_callback" (fn [] (php/current_user_can "edit_files"))  # authentication if needed
      "callback" (fn [wp-rest-req]
                   (let [command-with-printing (with-output-buffer (println "Hello world from Phel!"))
                         current-time (php/time)
                         html-content (html [:pre command-with-printing]
                                            [:pre "Time is " current-time])
                         rsp (http/response-from-map {:status 200
                                                      :headers {:content-type "text/html"}
                                                      :body html-content})]
                     (http/emit-response rsp)))}))))

API endpoints are public by default but can be restricted based on capabilities by defining "permission_callback" function. For WooCommerce admin plugins it would be useful to check e.g. that (php/current_user_can "manage_woocommerce"). Related resources:

• https://wordpress.org/documentation/article/roles-and-capabilities/
• https://developer.wordpress.org/reference/functions/current_user_can/
• https://wordpress.org/plugins/user-role-editor/

See also general WP Rest API docs https://developer.wordpress.org/rest-api/.

[jasalt]

Some interesting areas to experiment would be to utilise Phel router "rooted" into such endpoint to provide neater routing using it's facilities for multiple sub-routes and to leverage it's middleware pattern.

Also another and maybe more sophisticated way of adding endpoints beyond /wp-json/ route is using Rewrite Endpoints API and custom template redirect as seen with a WordPress plugins HTMX-API-WP and htmxpress. This however requires a bit of extra code.

Some wrapping would be a nice to have for these use cases might be nice to have in general.