template: Rename to `wibox.template`.

It was previously `wibox.widget.template`, but was in fact a container.

Now it is a top level concept. The next few commits will integrate it deeper
into AwesomeWM.

lib/awful/widget/common.lua

@@ -51,7 +51,7 @@ function common.create_buttons(buttons, object)
 end
 
 local function custom_template(args)
-    local l = base.make_widget_from_value(args.widget_template)
+    local l = wibox.template.make_from_value(args.widget_template)
 
     -- The template system requires being able to get children elements by ids.
     -- This is not optimal, but for now there is no way around it.

lib/wibox/init.lua

@@ -31,6 +31,7 @@ wibox.container = require("wibox.container")
 wibox.widget = require("wibox.widget")
 wibox.drawable = require("wibox.drawable")
 wibox.hierarchy = require("wibox.hierarchy")
+wibox.template = require("wibox.template")
 
 local force_forward = {
     shape_bounding = true,

lib/wibox/template.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- An abstract widget that handles a preset of concrete widget.
 --
--- The `wibox.widget.template` widget is an abstraction layer that contains a
+-- The `wibox.template` widget is an abstraction layer that contains a
 -- 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.
 --
@@ -23,7 +23,7 @@
 -- (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
+-- over concrete widget implementation. We use the `wibox.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!
 --
@@ -31,7 +31,7 @@
 -- 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` :
+-- `wibox.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.
@@ -46,7 +46,7 @@
 -- @author Aire-One
 -- @copyright 2021 Aire-One <aireone@aireone.xyz>
 --
--- @widgetmod wibox.widget.template
+-- @widgetmod wibox.template
 -- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
@@ -232,8 +232,10 @@ function template:set_property(property, value, ids)
     widgets = widgets or {target}
 
     for _, widget in ipairs(widgets) do
-        if widget["set_"..property] then
+        if rawget(widget, "set_"..property) then
             widget["set_"..property](widget, value)
+        else
+            widget[property] = value
         end
     end
 end
@@ -320,6 +322,10 @@ function template:get_widget()
     return lazy_load_child(self)
 end
 
+function template:get_children()
+    return { lazy_load_child(self) }
+end
+
 --- Set the update_callback property.
 -- @tparam function update_callback The new callback function.
 -- @method set_update_callback
@@ -330,6 +336,15 @@ function template:set_update_callback(update_callback)
     self._private.update_callback = update_callback
 end
 
+function template:get_update_callback()
+    return self._private.update_callback
+end
+
+-- Undocumented, for backward compatibility
+function template:get_create_callback()
+    return rawget(lazy_load_child(self), "create_callback")
+end
+
 --- Hack to allow automatic update of the widget at construction time.
 -- This is supposed to be a setter for an `update_now` property. This property
 -- however doesn't exist. We use this setter in the scope of the widget
@@ -347,32 +362,32 @@ function template:set_update_now(update_now)
 end
 
 
---- Create a new `wibox.widget.template` instance using the same template.
+--- Create a new `wibox.template` instance using the same template.
 --
 -- This copy will be blank. Note that `set_property`, `bind_property` or
 -- `update_callback` from `self` will **NOT** be transferred over to the copy.
 --
 -- The following example is a new widget to list a bunch of colors. It uses
--- `wibox.widget.template` to let the module user define their own color
+-- `wibox.template` to let the module user define their own color
 -- widget. It does so by cloning the original template into new instances. This
 -- example doesn't handle removing or updating them to keep the size small.
 --
 --@DOC_wibox_widget_template_clone1_EXAMPLE@
 --
 -- @method clone
--- @treturn wibox.widget.template The copy.
+-- @treturn wibox.template The copy.
 function template:clone()
     return template(self._private.widget_template)
 end
 
---- Create a new `wibox.widget.template` instance.
+--- Create a new `wibox.template` instance.
 -- @tparam[opt] table tmpl
 -- @tparam[opt] function tmpl.update_callback The callback function to update
 --   the widget.
 -- @tparam[opt] boolean tmpl.update_now Update the widget after its
 --   construction. This will call the `:update()` method with no parameter.
--- @treturn wibox.widget.template The new instance.
--- @constructorfct wibox.widget.template
+-- @treturn wibox.template The new instance.
+-- @constructorfct wibox.template
 function template.new(tmpl)
     tmpl = tmpl or {}
 
@@ -390,22 +405,22 @@ function template.new(tmpl)
     return ret
 end
 
---- Create a `wibox.widget.template` from a table.
+--- Create a `wibox.template` from a table.
 --
--- @staticfct wibox.widget.template.make_from_value
--- @tparam[opt=nil] table|wibox.widget.template|nil value A template declaration.
--- @treturn wibox.widget.template The template object.
+-- @staticfct wibox.template.make_from_value
+-- @tparam[opt=nil] table|wibox.template|nil value A template declaration.
+-- @treturn wibox.template The template object.
 function template.make_from_value(value)
     if not value then return nil end
 
+    if rawget(value, "_is_template") then return value:clone() end
+
     assert(
         not rawget(value, "is_widget"),
         "This property requires a widget template, not a widget object.\n"..
         "Use `wibox.template` instead of `wibox.widget`"
     )
 
-    if rawget(value, "_is_template") then return value:clone() end
-
     return template.new(value)
 end
 

lib/wibox/widget/init.lua

@@ -25,7 +25,6 @@ local widget = {
     slider = require("wibox.widget.slider");
     calendar = require("wibox.widget.calendar");
     separator = require("wibox.widget.separator");
-    template = require("wibox.widget.template");
 }
 
 setmetatable(widget, {

spec/wibox/widget/template_spec.lua

@@ -6,9 +6,9 @@
 _G.awesome.connect_signal = function() end
 
 local gtimer = require("gears.timer")
-local template = require("wibox.widget.template")
+local template = require("wibox.template")
 
-describe("wibox.widget.template", function()
+describe("wibox.template", function()
     local widget
 
     before_each(function()

tests/examples/sequences/widget/tmpl/bind_property.lua

@@ -12,7 +12,7 @@ client.focus = client.gen_fake{
 
     --DOC_HIDE_END
 
-    local my_template_widget = wibox.widget.template {
+    local my_template_widget = wibox.template {
         {
             {
                 set_icon = function(self, icon)

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

@@ -5,7 +5,7 @@ local parent = ...
 local wibox = require("wibox")
 --DOC_HIDE_END
 
-    local my_template_widget = wibox.widget.template {
+    local my_template_widget = wibox.template {
         widget = wibox.widget.textbox,
         update_callback = function(template_widget, args)
             local text = args.text or "???"

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

@@ -22,7 +22,7 @@ client.focus = client.gen_fake{
     local module = {}
     --DOC_NEWLINE
 
-    local default_template = wibox.widget.template {
+    local default_template = wibox.template {
         {
             {
                 {
@@ -59,7 +59,7 @@ client.focus = client.gen_fake{
     -- @property widget_template
     -- @tparam[opt=nil] wibox.template|nil
     function module:set_widget_template(t)
-        self._private.widget_template = wibox.widget.template.make_from_value(t)
+        self._private.widget_template = wibox.template.make_from_value(t)
     end
 
     --DOC_NEWLINE

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

@@ -25,9 +25,7 @@ local wibox = require("wibox")
 --DOC_NEWLINE
         -- Build an instance of the template widget with either, the
         -- user provided parameters or the default
-        local ret =  wibox.widget.template {
-            template = args.widget_template or default_widget
-        }
+        local ret =  wibox.template(args.widget_template or default_widget)
 
 --DOC_NEWLINE
         -- Patch the methods and fields the widget instance should have

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

@@ -6,7 +6,7 @@ local parent = ...
 local wibox = require("wibox")
 
 local function concrete_widget_template_builder(args)
-    return wibox.widget.template(args)
+    return wibox.template(args)
 end
 --DOC_HIDE_END
 

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

@@ -14,8 +14,7 @@ client.focus = client.gen_fake{
 
 --DOC_HIDE_END
 
-    local my_template_widget = wibox.widget.template {
-        template = {
+    local my_template_widget = wibox.template {
         {
             {
                 id         = "client_role",
@@ -52,7 +51,6 @@ client.focus = client.gen_fake{
         forced_width  = 200, --DOC_HIDE
         forced_height = 24, --DOC_HIDE
     }
-    }
 
 --DOC_NEWLINE
     -- Later in the code
@@ -63,5 +61,4 @@ client.focus = client.gen_fake{
 --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/set_property_existing.lua

@@ -14,7 +14,7 @@ client.focus = client.gen_fake{
 
 --DOC_HIDE_END
 
-    local my_template_widget = wibox.widget.template {
+    local my_template_widget = wibox.template {
         {
             {
                 id     = "icon_role",