doc(w.w.template) 3rd party lib usage example

lib/wibox/widget/template.lua

@@ -22,6 +22,32 @@
 --
 --@DOC_wibox_widget_template_basic_textbox_declarative_EXAMPLE@
 --
+-- Usage in libraries
+-- ==================
+--
+-- (this part is to be completed according to awful.widget comming PRs to implement the widget_template usage)
+--
+-- This widget was designed to be used as a standard way to offer customization
+-- over concrete widget implementation. We use the `wibox.widget.template` as a
+-- base to implement widgets from the `awful.widget` library. This way, it is
+-- easy for the final user to customize the standard widget offered by awesome!
+--
+-- It is possible to use the template widget as a base for a custom 3rd party
+-- widget module to offer more customization to the final user.
+--
+-- Here is an example of implementation for a custom widget inheriting from
+-- `wibox.widget.template` :
+--
+-- The module definition should include a default widget and a builder function
+-- that can build the widget with either, the user values or the default.
+--
+--@DOC_wibox_widget_template_concrete_implementation_module_EXAMPLE@
+--
+-- On the user side, it only requires to call the builder function to get an
+-- instance of the widget.
+--
+--@DOC_wibox_widget_template_concrete_implementation_user_EXAMPLE@
+--
 -- @author Aire-One
 -- @copyright 2021 Aire-One <aireone@aireone.xyz>
 --

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

@@ -0,0 +1,56 @@
+--DOC_NO_USAGE
+
+--DOC_HIDE_START
+local parent = ...
+
+local gears = require("gears")
+local wibox = require("wibox")
+
+local concrete_widget_template_builder
+--DOC_HIDE_END
+
+    -- Build the default widget used as a fallback if user doesn't provide a template
+    local default_widget = {
+        template = wibox.widget.textclock,
+        update_callback = function(widget_template, args)
+            local text = args and args.text or "???"
+            widget_template.widget.text = text
+        end,
+    }
+
+--DOC_NEWLINE
+    function concrete_widget_template_builder(args)
+        args = args or {}
+
+--DOC_NEWLINE
+        -- Build an instance of the template widget with either, the
+        -- user provided parameters or the default
+        local ret =  wibox.widget.template(
+            args.widget_template and args.widget_template or
+            default_widget
+        )
+
+--DOC_NEWLINE
+            -- Patch the methods and fields the widget instance should have
+
+--DOC_NEWLINE
+            -- e.g. Apply the received buttons, visible, forced_width and so on
+            gears.table.crush(ret, args)
+
+--DOC_NEWLINE
+            -- Optionally, call update once with parameters to prepare the widget
+            ret:update {
+                text = "default text",
+            }
+
+--DOC_NEWLINE
+        return ret
+    end
+
+--DOC_HIDE_START
+
+local w = concrete_widget_template_builder()
+parent:add(w)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

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

@@ -0,0 +1,38 @@
+--DOC_NO_USAGE
+
+--DOC_HIDE_START
+local parent = ...
+
+local wibox = require("wibox")
+
+local function concrete_widget_template_builder(args)
+    return wibox.widget.template(args)
+end
+--DOC_HIDE_END
+
+    -- Instanciate the widget with the default template
+    local default_widget = concrete_widget_template_builder()
+
+--DOC_NEWLINE
+    -- Instanciate the widget with a custom template
+    local custom_widget = concrete_widget_template_builder {
+        widget_template = {
+            template = wibox.widget.imagebox,
+            update_callback = function (template, args)
+                if args and args.text == "default text" then
+                    template.widget.image = "/path/to/image.png"
+                else
+                    template.widget.image = "/path/to/another-image.png"
+                end
+            end
+
+        }
+    }
+
+--DOC_HIDE_START
+
+parent:add(default_widget)
+parent:add(custom_widget)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+