From 3d66587678f28f6f115fe35c19422f34c8f4d628 Mon Sep 17 00:00:00 2001
From: evilchili <evilchili@gmail.com>
Date: Sat, 17 Jan 2026 15:49:05 -0800
Subject: [PATCH] improve docs on default widget

---
 src/ttfrog/schema.py                        | 47 ++++++++++++++++++---
 src/ttfrog/themes/default/static/froghat.js |  1 -
 2 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/src/ttfrog/schema.py b/src/ttfrog/schema.py
index 5987ad6..ab57208 100644
--- a/src/ttfrog/schema.py
+++ b/src/ttfrog/schema.py
@@ -312,27 +312,45 @@ class Widget(Page):
 
     default = dedent(
         """
-# hello
+This is a sample widget that you can customize to your liking. Widget pages must contain at minimum the
+**Template** section. It, along with the optional **CSS** and **Processor** sections, will be parsed by
+wiki at display time. All other content on this page is ignored, so you can include usage docs, exmaples,
+and so on, just like this text and the annnotations below in *italics*.
 
-Insert the word "HELLO."
+The name of your widget is the portion of the URI following `/Widget/`.
+
+# Hello, World Example Widget
+*Provide a description of your widget.*
+
+Insert the word "HELLO" and optionally a name.
 
 ## Usage
-{{{
-<pre>\\{\\{widget hello [name="NAME"] \\}\\}</pre>
-}}}
+*Display the usage of your widget. Ensure that the example is enclosed in a preformatted (`pre`) block.*
+*Be sure to include a description of any parameters and keyword arguments.*
+
+<pre>
+{{widget hello [NAME] }}
+</pre>
+
 
 ## Example
+*Include one or more example uses of the widget. Once you save this page, you can refer to your widget directly.*
 
-This example uses the current page's widget definition: {{widget hello world}} Nice, huh?
+Here is what it looks like to say hello to the whole world: {{widget hello world}}!
 
 
 ## Template
+*The template is javascript string that will be evaluated when the widget is loaded. Any keyword parameters*
+*you specify in the  Usage section above will be available as variables, so you can use variable subsetitution*
+*in your template definition. The template must be enclose in a code block.*
 
 ```
-HELLO${name ? ", " + name : ""}.
+HELLO ${{token.keywords.split(" ").slice(1).join(" ") || ""}}
 ```
 
 ## CSS
+*If you want to customize the styling of your widget, include CSS in this section. This CSS must be enclosed*
+*in a code block.*
 
 ```
 display: inline;
@@ -343,8 +361,23 @@ border-radius: 5px;
 ```
 
 ## Processor
+*If you want full control over how your widget is processed, you can override the default processor*
+*here. The processor function below is the default.*
 
 ```
+function(token, widget) {{
+    /*
+     * token    The token object created by the wiki parser. token.keywords and
+     *          token.params contain the keyword and paramater arguments from
+     *          the wiki page source where the widget was used.
+     * widget:  The widget instance. widget.css, widget.template, and
+     *          widget.processor contain the definitions parsed from the
+     *          corresponding sections on this page.
+     */
+    var ret = '';
+    eval("ret = `" + widget.template + "`");
+    return ret;
+}}
 ```
 """
     )
diff --git a/src/ttfrog/themes/default/static/froghat.js b/src/ttfrog/themes/default/static/froghat.js
index 59ae70d..7352002 100644
--- a/src/ttfrog/themes/default/static/froghat.js
+++ b/src/ttfrog/themes/default/static/froghat.js
@@ -222,7 +222,6 @@ class MacroPlugin extends FroghatPlugin {
                 var widgetName = token.keywords.split(" ")[0];
                 var contents = '';
                 var cached = loadWidget(widgetName, (widget) => {
-                    console.log(token, node);
                     contents = widget.processor(token, widget);
                     var targets = wiki.element.querySelectorAll(`[data-macro-name="widget"][data-keywords="${token.keywords}"]`);
                     targets.forEach(widgetElement => {