#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,15 @@
+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,53 @@
+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

@@ -757,6 +757,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 eg. sm, lg', '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 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 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 [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 component(name, icon, description) VALUES
     ('shell', 'layout-navbar', 'Personalize the "shell" surrounding your page contents. Used to set properties for the entire page.');
 
@@ -819,6 +882,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": [

examples/official-site/sqlpage/sqlpage.yaml

@@ -2,4 +2,7 @@
 database_url: "sqlite::memory:"
 
 # We have a file upload example, and would like to limit the size of the uploaded files 
-max_uploaded_file_size: 256000
+max_uploaded_file_size: 256000
+
+# For the show-progress example to work, we have to disable compression
+compress_responses: False

sqlpage/sqlpage.css

@@ -50,4 +50,49 @@ td > p {
 .datagrid {
   --tblr-datagrid-padding: 1.25rem;
   --tblr-datagrid-item-width: 12rem;
-}
+}
+
+/* loader container */
+div.sqlpage-loader-start {
+  position: fixed;
+  text-align: center;
+  left: 50vw;
+  top: 50vh;
+  margin-top: -5.5em;
+  margin-left: -87.5px;
+  padding-bottom: 2em;
+  height: 9em;
+  width: 175px;
+}
+div.sqlpage-loader-start:not(:has(+ .sqlpage-loader-stop)) {
+  /* only display if not followed by sqlpage-loader-stop */
+  display: block;
+}
+.sqlpage-loader-start:not(:last-child) {
+  /* firefox doesn't support :has
+     so hide the loader if it is no longer the last element */
+  display: none;
+}
+/* end loader container */
+
+/* progress container */
+.sqlpage-progress-container {
+  margin: 1em 0 1em;
+}
+div.sqlpage-progress-container:not(:has(+ .sqlpage-progress-container)) {
+  /* only display if not followed by sqlpage-progress-container */
+  display: block;
+}
+.sqlpage-progress-container:not(:last-child) {
+  /* firefox doesn't support :has
+     so hide the loader if it is no longer the last element */
+  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,4 @@
+<div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
+  {{#if spinner}}<span class="{{default spinner "spinner-border"}}
+    {{#if size}}spinner-border-{{size}}{{/if}}
+    {{#if color}}text-{{color}}{{/if}}"></span>{{/if}}

sqlpage/templates/loader-stop.handlebars

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

sqlpage/templates/progress.handlebars

@@ -0,0 +1,44 @@
+{{#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}}
+{{#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}}