Docs: show the template's Show total switch reaching data.js

public/widgets/mywidget/data.js

@@ -1,5 +1,5 @@
 module.exports = async function (ctx) {
-  const { url, apiKey } = ctx.config;
+  const { url, apiKey, showTotal } = ctx.config;
   if (!url) ctx.fail('Not configured', { kind: ctx.KIND.INVALID });
 
   const base = ctx.normalizeBase(url);
@@ -13,6 +13,6 @@ module.exports = async function (ctx) {
 
   return {
     items: r.data.items.slice(0, 10).map(i => ({ name: i.name })),
-    total: r.data.total ?? r.data.items.length,
+    total: showTotal === false ? null : (r.data.total ?? r.data.items.length),
   };
 };

public/widgets/mywidget/demo.js

@@ -10,7 +10,7 @@ module.exports = function (ctx) {
   const { wave, round } = ctx.demo;
   return {
     items: [{ name: 'First item' }, { name: 'Second item' }],
-    total: Math.round(wave(600, 8, 20)),
+    total: ctx.config.showTotal === false ? null : Math.round(wave(600, 8, 20)),
     ratio: round(wave(300, 0, 1), 2),
   };
 };

public/widgets/mywidget/index.html

@@ -13,27 +13,36 @@
       align-items:center; justify-content:center; gap:4px }
     .n { font-size:34px; font-weight:600; letter-spacing:-0.5px }
     .l { font-size:12px; color:#8e8e93 }
+    .i { max-width:100%; font-size:13px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis }
     html[data-theme="light"] body { color:#1c1c1e }
     html[data-theme="light"] .l { color:#6c6c70 }
   </style>
 </head>
 <body>
   <div id="root"></div>
   <script type="module">
-    import { poll } from '/js/widget-toolbox.js?v=1';
+    import { formatNumber, poll } from '/js/widget-toolbox.js?v=1';
 
     const root = document.getElementById('root');
 
     poll({
       render: data => {
         root.replaceChildren();
-        const n = document.createElement('div');
-        n.className = 'n';
-        n.textContent = String(data.total);
-        const l = document.createElement('div');
-        l.className = 'l';
-        l.textContent = data.total === 1 ? 'item' : 'items';
-        root.append(n, l);
+        if (data.total != null) {
+          const n = document.createElement('div');
+          n.className = 'n';
+          n.textContent = formatNumber(data.total);
+          const l = document.createElement('div');
+          l.className = 'l';
+          l.textContent = data.total === 1 ? 'item' : 'items';
+          root.append(n, l);
+        }
+        for (const item of data.items.slice(0, 3)) {
+          const row = document.createElement('div');
+          row.className = 'i';
+          row.textContent = item.name;
+          root.append(row);
+        }
       },
       isEmpty: data => !data.items?.length,
       emptyText: 'Nothing here',

src/content/docs/docs/create-a-widget/checklist.md

@@ -8,6 +8,8 @@ CI validates every manifest. Run the same check locally with `cd api && node --t
 ## Files
 
 - `widget.json` with `name` matching the folder, `label`, `sizes` and `fields`.
+- A `glyph` no other widget uses. Add one to `ui/js/widget-glyphs.js` when none is free.
+- A line under Widgets in the app `README.md`.
 - `data.js`, unless the widget runs entirely in the browser.
 - `index.html`.
 - `i18n/en.json`, plus one catalog per shipped language.

src/content/docs/docs/create-a-widget/index.mdx

@@ -36,13 +36,13 @@ cp -r docs/widget-template ui/widgets/mywidget
 }
 ```
 
-`name` must match the folder. Each field becomes a row in the widget's settings. A `secret` never returns to the browser. See [Manifest](/docs/create-a-widget/manifest/).
+`name` must match the folder. Each field becomes a row in the widget's settings. A `secret` never returns to the browser. A `toggle` that was never saved is absent from `ctx.config`, so test for `false`. See [Manifest](/docs/create-a-widget/manifest/).
 
 ## 3. Data
 
 ```js title="data.js"
 module.exports = async function (ctx) {
-  const { url, apiKey } = ctx.config;
+  const { url, apiKey, showTotal } = ctx.config;
   if (!url) ctx.fail('Enter the service URL.', { kind: ctx.KIND.INVALID });
 
   const r = await ctx.fetchJSON(`${ctx.normalizeBase(url)}/api/items`, {
@@ -55,7 +55,7 @@ module.exports = async function (ctx) {
 
   return {
     items: r.data.items.slice(0, 10).map(i => ({ name: i.name })),
-    total: r.data.total ?? r.data.items.length,
+    total: showTotal === false ? null : (r.data.total ?? r.data.items.length),
   };
 };
 ```
@@ -66,11 +66,14 @@ The return value is served at `/api/widget-data/<id>`. Report every failure thro
 
 ```html title="index.html"
 <script type="module">
-  import { poll } from '/js/widget-toolbox.js?v=1';
+  import { formatNumber, poll } from '/js/widget-toolbox.js?v=1';
   const root = document.getElementById('root');
 
   poll({
-    render: data => { root.textContent = `${data.total} items`; },
+    render: data => {
+      const names = data.items.slice(0, 3).map(i => i.name).join(', ');
+      root.textContent = data.total == null ? names : `${formatNumber(data.total)} items: ${names}`;
+    },
     isEmpty: data => !data.items?.length,
     interval: 30000,
   });