#435: show spinner indicating page is loading

examples/official-site/examples/show-progress/README.md

@@ -0,0 +1,3 @@
+# SQLPage display progress
+
+This is a very simple example of a page that shows a spinner to indicate page is loading.

examples/official-site/examples/show-progress/go.sql

@@ -0,0 +1,19 @@
+-- Disable actix-web compression middleware:
+--    https://github.com/actix/actix-web/issues/3410
+SELECT 'http_header' AS component, 'Identity' AS "Content-Encoding";
+
+SELECT 'shell' AS component, 'light' AS theme;
+
+-- can disable the spinner to show only progress bar
+SELECT 'loader-start' AS component,  '' AS spinner;
+
+SELECT 'progress' AS component,
+  NULL AS percent,
+  'sm' AS size,
+  'yellow' AS color,
+  'Working on it' AS stage;
+SELECT sqlpage.fetch('https://example.com');
+
+SELECT 'loader-stop' AS component;
+
+SELECT 'text' AS component, 'Processing complete.' AS contents;

examples/official-site/examples/show-progress/index.sql

@@ -0,0 +1,57 @@
+-- Disable actix-web compression middleware:
+--    https://github.com/actix/actix-web/issues/3410
+SELECT 'http_header' AS component, 'Identity' AS "Content-Encoding";
+
+SELECT 'shell' AS component, 'dark' AS theme;
+
+SELECT 'loader-start' AS component,
+  -- pick from the tabler spinners: https://tabler.io/docs/components/spinners
+  "spinner-border" spinner,
+  "sm" AS size,
+  "red" AS color;
+
+SELECT 'progress' AS component,
+  'sm' AS size,
+  'yellow' AS color,
+  '0' AS percent,
+  'Fething data' AS stage;
+SELECT sqlpage.fetch('https://example.com');
+
+/* percent property is optional */
+SELECT 'progress' AS component,
+  NULL AS percent,
+  'sm' AS size,
+  'yellow' AS color,
+  'Doing something' AS stage;
+SELECT sqlpage.fetch('https://example.com');
+
+/* stage property is optional */
+SELECT 'progress' AS component,
+  'sm' AS size,
+  'yellow' AS color,
+  '40' AS percent;
+SELECT sqlpage.fetch('https://example.com');
+
+/* multiple rows */
+SELECT 'progress' AS component, 'sm' AS size, 'yellow' AS color;
+SELECT '70' AS percent, 'Fetching data' AS stage
+SELECT sqlpage.fetch('https://example.com');
+SELECT '80' AS percent, 'Fetching more data' AS stage;
+SELECT sqlpage.fetch('https://example.com');
+SELECT '90' AS percent, 'Fetching again' AS stage;
+SELECT sqlpage.fetch('https://example.com');
+
+SELECT '100' AS percent;
+
+SELECT 'loader-stop' AS component;
+
+SELECT 'text' AS component,
+  'It works!' AS title,
+  TRUE AS center,
+  'Page is loaded.' AS contents;
+
+SELECT 'button' AS component;
+SELECT 'Go' AS title, './go.sql' AS link;
+
+-- can use progress on it's own
+SELECT 'progress' AS component, 'sm' AS size, 'Waiting for user' AS stage;

examples/official-site/sqlpage/migrations/01_documentation.sql

@@ -820,6 +820,69 @@ and `shell.json` would be placed at the website''s root and contain the followin
 ```
 ', NULL);
 
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('loader-start', 'refresh', 'Display a spinner to indicate page is loading.', '0.25.0');
+
+INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'loader-start', * FROM (VALUES
+    ('spinner', '
+The name of a [spinner](https://tabler.io/docs/components/spinners) (from tabler.io).
+Default is "spinner-border".
+Set to the empty string to disable the spinner - e.g. to display only progress
+updates.
+', 'TEXT', TRUE, TRUE),
+    ('size', 'Size of the spinner (e.g. sm, lg) [see here](https://tabler.io/docs/components/progress)', 'TEXT', TRUE, TRUE),
+    ('color', 'Color of the spinner', 'COLOR', TRUE, TRUE)
+) x;
+
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('loader-stop', 'refresh-off', '
+Hide the spinner displayed by the loader-start component.
+', '0.25.0');
+
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('progress', 'time-duration-15', 'Display a progress bar.', '0.25.0');
+
+INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'progress', * FROM (VALUES
+    -- top-level
+    ('percent', 'Number between 0 and 100.', 'INTEGER', TRUE, TRUE),
+    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', TRUE, TRUE),
+    ('color', 'The fill color of the progress bar', 'COLOR', TRUE, TRUE),
+    ('size', 'The size of the progress bar (e.g. sm, lg) [see here](https://tabler.io/docs/components/progress)', 'TEXT', TRUE, TRUE),
+    -- item-level
+    ('percent', 'Number between 0 and 100.', 'INTEGER', FALSE, TRUE),
+    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', FALSE, TRUE)
+) x;
+
+INSERT INTO example(component, description, properties) VALUES
+    ('loader-start', '
+Will be displayed until [loader-stop](/documentation.sql?component=loader-stop) is selected.
+
+See the [live example](/examples/show-progress/).
+
+Source is [here](https://github.com/lovasoa/SQLpage/tree/main/examples/official-site/examples/show-progress)
+', NULL),
+    ('loader-stop', '
+Hide the spinner displayed by the [loader-start](/documentation.sql?component=loader-start) component.
+
+See the [live example](/examples/show-progress/).
+
+Source is [here](https://github.com/lovasoa/SQLpage/tree/main/examples/official-site/examples/show-progress)
+', NULL),
+    ('progress', '
+Can be used on it''s own (will persist on the page) or with
+[loader-start](/documentation.sql?component=loader-start) and
+[loader-stop](/documentation.sql?component=loader-stop) to hide the progress bar once processing
+is complete.
+
+Subsequent uses of this component and/or any rows will
+update the progress bar.
+
+See the [live example](/examples/show-progress/).
+
+Source is [here](https://github.com/lovasoa/SQLpage/tree/main/examples/official-site/examples/show-progress)
+', NULL)
+;
+
 INSERT INTO component(name, icon, description) VALUES
     ('shell', 'layout-navbar', 'Personalize the "shell" surrounding your page contents. Used to set properties for the entire page.');
 
@@ -882,6 +945,7 @@ You see the [page layouts demo](./examples/layouts.sql) for a live example of th
                     {"link": "/examples/multistep-form", "title": "Forms", "icon": "edit"},
                     {"link": "/examples/handle_picture_upload.sql", "title": "File uploads", "icon": "upload"},
                     {"link": "/examples/authentication/", "title": "Password protection", "icon": "password-user"},
+                    {"link": "/examples/show-progress/", "title": "Tracking progress of background tasks", "icon": "loader-2"},
                     {"link": "//github.com/lovasoa/SQLpage/blob/main/examples/", "title": "All examples & demos", "icon": "code"}
                 ]},
                 {"title": "Community", "submenu": [

sqlpage/sqlpage.css

@@ -50,4 +50,50 @@ td > p {
 .datagrid {
   --tblr-datagrid-padding: 1.25rem;
   --tblr-datagrid-item-width: 6rem;
-}
+}
+
+/* loader container */
+.sqlpage-loader-container {
+  position: fixed;
+  text-align: center;
+  left: 50vw;
+  top: 50vh;
+  margin-top: -5.5em;
+  margin-left: -87.5px;
+  padding-bottom: 2em;
+  height: 9em;
+  width: 175px;
+}
+.sqlpage-loader-container:has(.status) {
+  position: inherit;
+  text-align: inherit;
+  left: inherit;
+  top: inherit;
+  margin-top: inherit;
+  margin-left: inherit;
+  padding-bottom: inherit;
+  height: inherit;
+  width: inherit;
+}
+div.sqlpage-loader-start:has(+ .sqlpage-loader-stop) {
+  /* hide if followed by sqlpage-loader-stop */
+  display: none;
+}
+/* end loader container */
+
+/* progress container */
+.sqlpage-progress-container {
+  margin: 1em 0 1em;
+}
+div.sqlpage-progress-container:has(+ .sqlpage-progress-container) {
+  /* hide if followed by sqlpage-progress-container */
+  display: none;
+}
+.sqlpage-progress-container label {
+  text-align:left;
+  color: var(--tblr-text-primary);
+}
+.sqlpage-progress-container label:after {
+  content: "…";
+}
+/* end progress container */

sqlpage/templates/loader-start.handlebars

@@ -0,0 +1,6 @@
+<div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
+  <div class="sqlpage-loader-container">
+    <span class="{{default spinner "spinner-border"}}
+      {{#if size}}spinner-border-{{size}}{{/if}}
+      {{#if color}}text-{{color}}{{/if}}">
+    </span>

sqlpage/templates/loader-stop.handlebars

@@ -0,0 +1,3 @@
+  </div>
+</div>
+<div class="sqlpage-loader-stop"></div>

sqlpage/templates/progress.handlebars

@@ -0,0 +1,42 @@
+<div class="sqlpage-progress-container">
+  <div class="progress {{~#if size}} progress-{{size}}{{/if}}">
+    <div
+      id="sqlpage-loading-{{default stage "progress"}}"
+      class="progress-bar
+      {{~#if (not percent)}} progress-bar-indeterminate{{/if}}
+      {{~#if color}} bg-{{color}}{{/if}}"
+      role="progressbar"
+      aria-valuenow="{{percent}}"
+      {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
+      aria-valuemin="0" aria-valuemax="100"
+      {{~#if stage}}aria-label="{{stage}}"{{/if}}>
+    </div>
+  </div>
+  {{~#if stage}}
+    <br>
+    <label for="sqlpage-loading-{{default stage "progress"}}">{{stage}}</label>
+  {{/if}}
+</div>
+{{#each_row}}
+{{#if (or percent stage)}}
+  <div class="sqlpage-progress-container">
+    <div class="progress {{~#if ../size}} progress-{{../size}}{{/if}}">
+      <div
+        id="sqlpage-loading-{{default stage "progress"}}"
+        class="progress-bar
+        {{~#if (not percent)}} progress-bar-indeterminate{{/if}}
+        {{~#if ../color}} bg-{{../color}}{{/if}}"
+        role="progressbar"
+        aria-valuenow="{{percent}}"
+        {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
+        aria-valuemin="0" aria-valuemax="100"
+        {{~#if stage}}aria-label="{{stage}}"{{/if}}>
+      </div>
+    </div>
+    {{~#if stage}}
+      <br>
+      <label for="sqlpage-loading-{{default stage "progress"}}">{{stage}}</label>
+    {{/if}}
+  </div>
+{{/if}}
+{{/each_row}}