doc(w.w.template) module description

lib/wibox/widget/template.lua

@@ -5,10 +5,27 @@
 -- concrete widget definition. The template widget can be used to build widgets
 -- that the user can customize at their will, thanks to the template mechanism.
 --
+-- Common usage examples
+-- =====================
+--
+-- A basic implementation of the template widget needs a widget definition and
+-- a callback to manage widget updates.
+--
+-- The `:update()` can be called later to update the widget template. Arguments
+-- can be provided to the `:update()` method, it will be forwarded to the
+-- `update_callback` function.
+--
+--@DOC_wibox_widget_template_basic_textbox_EXAMPLE@
+--
+-- Alternatively, you can declare the `template` widget instance using the
+-- declarative pattern (both variants are strictly equivalent):
+--
+--@DOC_wibox_widget_template_basic_textbox_declarative_EXAMPLE@
+--
 -- @author Aire-One
 -- @copyright 2021 Aire-One <aireone@aireone.xyz>
 --
--- @classmod wibox.widget.template
+-- @widgetmod wibox.widget.template
 -- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 

tests/examples/wibox/widget/template/basic_textbox.lua

@@ -0,0 +1,31 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE
+
+--DOC_HIDE_START
+local parent = ...
+local wibox = require("wibox")
+--DOC_HIDE_END
+
+    local my_template_widget = wibox.widget.template {
+        template = wibox.widget.textbox,
+        update_callback = function(template_widget, args)
+            local text = args.text or "???"
+            template_widget.widget.text = text
+        end,
+    }
+
+--DOC_NEWLINE
+    -- Later in the code
+
+--DOC_NEWLINE
+    -- With no arguments, the update_callback will fallback to "???"
+    my_template_widget:update()
+
+--DOC_NEWLINE
+    -- With custom arguments, the update_callback will changes the displayed text
+    my_template_widget:update { text = "Cool text to update the template!" }
+
+--DOC_HIDE_START
+
+parent:add(my_template_widget)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/template/basic_textbox_declarative.lua

@@ -0,0 +1,25 @@
+--DOC_NO_USAGE
+
+--DOC_HIDE_START
+local wibox = require("wibox")
+--DOC_HIDE_END
+
+    local my_template_widget = {
+        id = "mytemplatewidget",
+        template = wibox.widget.textbox,
+        update_callback = function(template_widget, args)
+            local text = args.text or "???"
+            template_widget.widget.text = text
+        end,
+        widget = wibox.widget.template,
+    }
+
+--DOC_HIDE_START
+
+-- Generate the widget to use the update method in the example.
+-- A better approch would have been to use an ID and the `get_children_by_id`
+-- on the parent.
+local widget = wibox.widget(my_template_widget)
+widget:update { text = "Cool text to update the template!" }
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80