Merge pull request #304 from ldgallery/oz-splash-screen

viewer: optional user-defined markdown splash screen

7 files changed, 201 insertions, 18 deletions

diff --git a/viewer/ldgallery-viewer.7.md b/viewer/ldgallery-viewer.7.md
index 96070dc..1e914ff 100644
--- a/viewer/ldgallery-viewer.7.md
+++ b/viewer/ldgallery-viewer.7.md
@@ -92,11 +92,58 @@ initialTagDisplayLimit
   Set to -1 to disable the limit on suggestions.
   Defaults to 10.
 
+splashScreen
+: Displays an information notice before opening the gallery (see below).
+
 An alternative viewer configuration file located in the viewer's directory can be loaded by specifying its name,
 without the ".json" extension, as a query parameter given before the page anchor;
 for example, some alternative configuration named "config_2.json" can be loaded with "http://gallery/?config_2#".
 
 
+# SPLASH SCREEN CONFIGURATION
+
+splashScreen.resource
+: Absolute or relative path to the information notice. The user is prompted to explicitly acknowledge such notice before being allowed to browse the gallery.
+  Rich text formatting is possible through the use of the [GitHub Flavoured Markdown syntax][GFM].
+  Inline HTML and CSS are also supported.
+  [GFM]: https://github.github.com/gfm/
+
+splashScreen.acknowledgmentKey
+: Optional key; when set to an arbitrary string, the information notice will appear only the first time it is proposed to the user. Once the notice acknowledged, the key is saved to the device's local storage. To display the notice again, change this key to another value.
+  When left empty, the notice will appear every time.
+
+splashScreen.buttonAcknowledgeLabel
+: Optional label for the acknowledge button shown below the notice.
+  *Defaults to "Acknowledge"*
+
+splashScreen.style
+: Optional CSS attributes for the information notice's container.
+  String or JSON formats are supported.
+
+
+# CONFIGURATION EXAMPLE
+
+Viewer __config.json__:
+
+```json
+{
+  "galleryRoot": "./gallery/",
+  "galleryIndex": "index.json",
+  "initialItemSort": "date_desc",
+  "initialTagDisplayLimit": 10,
+  "splashScreen": {
+    "resource": "./splashscreen.md",
+    "acknowledgmentKey": "v001",
+    "buttonAcknowledgeLabel": "I agree",
+    "style": {
+      "max-width": "45em",
+      "font-size": "20px",
+      "padding-top": "20vh"
+    }
+  }
+}
+```
+
 # PROGRESSIVE WEB APPLICATION
 
 This web application can be "installed" on some user's mobile device as a progressive web application, i.e. a shortcut giving the web page the appearance of a native application.
diff --git a/viewer/src/@types/gallery.d.ts b/viewer/src/@types/gallery.d.ts
index d9e7534..9011f19 100644
--- a/viewer/src/@types/gallery.d.ts
+++ b/viewer/src/@types/gallery.d.ts
@@ -18,6 +18,7 @@
 */
 
 import { ItemType } from "./ItemType";
+import { SplashScreenConfig } from "./splashscreen";
 
 export type ItemSortStr = "title_asc" | "date_asc" | "date_desc";
 
@@ -26,6 +27,7 @@ export interface Config {
   galleryIndex?: string;
   initialItemSort?: ItemSortStr;
   initialTagDisplayLimit?: number;
+  splashScreen?: SplashScreenConfig;
 }
 
 export interface Properties {
diff --git a/viewer/src/@types/splashscreen.d.ts b/viewer/src/@types/splashscreen.d.ts
new file mode 100644
index 0000000..4e03fa8
--- /dev/null
+++ b/viewer/src/@types/splashscreen.d.ts
@@ -0,0 +1,25 @@
+/* ldgallery - A static generator which turns a collection of tagged
+--             pictures into a searchable web gallery.
+--
+-- Copyright (C) 2019-2021  Guillaume FOUET
+--
+-- This program is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as
+-- published by the Free Software Foundation, either version 3 of the
+-- License, or (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+export interface SplashScreenConfig {
+  resource?: string;
+  acknowledgmentKey?: string;
+  buttonAcknowledgeLabel?: string;
+  style?: any;
+}
diff --git a/viewer/src/locales/en.json b/viewer/src/locales/en.json
index b21262a..d0a7a26 100644
--- a/viewer/src/locales/en.json
+++ b/viewer/src/locales/en.json
@@ -14,6 +14,8 @@
   "panelLeft.propositions": "Related filters",
   "panelLeft.propositions.other": "other filters",
   "search.no-result-fmt": "No result<br>({0} match in other folders) | No result<br>({0} matches in other folders)",
+  "snack.retry": "Retry",
+  "splashScreen.button.acknowledge": "Acknowledge",
   "tag-propositions.addition": "Include all items with this tag",
   "tag-propositions.intersection": "Search for this tag",
   "tag-propositions.item-count": "Item count",
diff --git a/viewer/src/store/uiStore.ts b/viewer/src/store/uiStore.ts
index f5bb898..520fcf4 100644
--- a/viewer/src/store/uiStore.ts
+++ b/viewer/src/store/uiStore.ts
@@ -18,6 +18,7 @@
 */
 
 import { Config } from "@/@types/gallery";
+import { SplashScreenConfig } from "@/@types/splashscreen";
 import ItemComparators, { ItemSort } from "@/services/itemComparators";
 import { action, createModule, mutation } from "vuex-class-component";
 
@@ -26,12 +27,17 @@ const VuexModule = createModule({
   strict: true,
 });
 
+const STORAGE_SPLASHSCREEN_ACKNOWLEDGMENT = "splashScreenAcknowledgment";
+
 export default class UIStore extends VuexModule {
   fullscreen: boolean = false;
   fullWidth: boolean = window.innerWidth < Number(process.env.VUE_APP_FULLWIDTH_LIMIT);
   searchMode: boolean = false;
   sort: ItemSort = ItemComparators.DEFAULT;
 
+  splashScreenConfig: SplashScreenConfig | null = null;
+  splashScreenEnabled: boolean = false;
+
   // ---
 
   @mutation toggleFullscreen(value?: boolean) {
@@ -50,11 +56,34 @@ export default class UIStore extends VuexModule {
     this.sort = sort;
   }
 
+  @mutation setSplashScreenConfig(splashScreenConfig: SplashScreenConfig) {
+    this.splashScreenConfig = splashScreenConfig;
+  }
+
+  @mutation setSplashScreenEnabled(enabled: boolean) {
+    this.splashScreenEnabled = enabled;
+  }
+
+  // ---
+
   @action async initFromConfig(config: Config) {
     if (config.initialItemSort) {
       const itemSort = ItemComparators.ITEM_SORTS[config.initialItemSort];
       if (itemSort) this.setSort(itemSort);
       else throw new Error("Unknown sort type: " + config.initialItemSort);
     }
+    if (config.splashScreen) {
+      this.setSplashScreenConfig(config.splashScreen);
+      const uid = config.splashScreen.acknowledgmentKey;
+      this.setSplashScreenEnabled(!uid || localStorage.getItem(STORAGE_SPLASHSCREEN_ACKNOWLEDGMENT) !== uid);
+    }
+  }
+
+  // ---
+
+  @action async validateSpashScreen() {
+    this.setSplashScreenEnabled(false);
+    const uid = this.splashScreenConfig?.acknowledgmentKey;
+    if (uid) localStorage.setItem(STORAGE_SPLASHSCREEN_ACKNOWLEDGMENT, String(uid));
   }
 }
diff --git a/viewer/src/views/MainLayout.vue b/viewer/src/views/MainLayout.vue
index c54f183..2347ba7 100644
--- a/viewer/src/views/MainLayout.vue
+++ b/viewer/src/views/MainLayout.vue
@@ -22,14 +22,13 @@
     <ld-title :gallery-title="$galleryStore.galleryTitle" :current-item="$galleryStore.currentItem" />
     <PanelTop v-if="isReady" :class="[$style.layout, $style.layoutTop]" />
     <PanelLeft v-if="isReady" :class="[$style.layout, $style.layoutLeft]" />
-    <router-view
-      v-if="!isLoading"
-      ref="content"
-      :class="[$style.layout, $style.layoutContent]"
-      class="scrollbar"
-      tabindex="01"
+    <b-loading v-if="isLoading" active />
+    <SplashScreen
+      v-else-if="$uiStore.splashScreenEnabled"
+      :class="$style.layout"
+      @validation="$uiStore.validateSpashScreen()"