5316: add documentation, lint and change some names to make more sense

Author: sinejespersen

README.md

@@ -51,7 +51,7 @@ Further documentation can be found in the
 ## Content Structure
 
 | Component | Description                                                                                                                                                                                                                                                                                                                                                            | Accessible by |
-|-----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|
+| --------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
 | Slide     | A slide is the visible content on a screen.                                                                                                                                                                                                                                                                                                                            | Admin, editor |
 | Media     | Media is either images or videos used as content for slides.                                                                                                                                                                                                                                                                                                           | Admin, editor |
 | Theme     | A theme has css, that can override the slide css.                                                                                                                                                                                                                                                                                                                      | Admin         |
@@ -318,7 +318,7 @@ See the `docker-compose.override.yml` playwright entry and the version imported
 
 This project includes a test script that handles building assets, running
 Playwright tests, and stops and starts the node container. This script tests the
-*built* files. This is the approach the GitHub Action uses.
+_built_ files. This is the approach the GitHub Action uses.
 
 ```shell
 task test:frontend-built
@@ -404,6 +404,7 @@ TRACK_SCREEN_INFO_UPDATE_INTERVAL_SECONDS=300
   The format of the interval should follow <https://www.php.net/manual/en/dateinterval.construct.php>.
 
   **Default**: 2 days.
+
 - APP_KEY_VAULT_SOURCE: Source of key-value pair for `src/Service/KeyVaultService`. Atm. "ENVIRONMENT" is the only
   option.
 - APP_KEY_VAULT_JSON: A json object formatted as a string. Contains key-value pairs that can be accessed by through
@@ -431,23 +432,26 @@ ADMIN_ENHANCED_PREVIEW=false
   See [https://labs.rejseplanen.dk/](https://labs.rejseplanen.dk/) for information about acquiring an API key.
 
   **Default**: Not set.
+
 - ADMIN_SHOW_SCREEN_STATUS: Should the status of the screen be shown in the Admin (true|false)?
 
   **Default**: Disabled.
+
 - ADMIN_TOUCH_BUTTON_REGIONS: Should the option of setting a button name for a slide be enabled in the Admin?
   This option is used by the Client if a region is configured to be a "touch-buttons" region.
 
   **Default**: Disabled.
+
 - ADMIN_LOGIN_METHODS: Which login methods should be displayed in the admin (array of objects as json string)?
 
   Available types: "oidc" | "username-password".
 
   ```json
   {
-      "type": "oidc",
-      "provider": "internal",
-      "label": "Button text",
-      "icon": "faCity"
+    "type": "oidc",
+    "provider": "internal",
+    "label": "Button text",
+    "icon": "faCity"
   }
   ```
 
@@ -456,17 +460,18 @@ ADMIN_ENHANCED_PREVIEW=false
   - icon: Name of the fontawesome icon to use for the button or "mitID" for MitID logo.
 
   ```json
-    {
-      "type": "username-password",
-      "provider": "username-password",
-      "label": ""
-    }
+  {
+    "type": "username-password",
+    "provider": "username-password",
+    "label": ""
+  }
   ```
 
   - provider: "username-password"
   - label: Label for the username password login section
 
   **Default**: Username and password login option is enabled.
+
 - ADMIN_ENHANCED_PREVIEW: Should the enhanced preview mode be active (true|false)? When enabled, previews will be
   handled by iFraming in the Client app. This will allow the option of previewing playlists and screens.
   If disabled, only slides can be previewed. This will be with the "live" method. This preview is not as precise.
@@ -494,18 +499,23 @@ CLIENT_DEBUG=false
   waiting for being activated in the administration.
 
   **Default**: 20 s.
+
 - CLIENT_REFRESH_TOKEN_TIMEOUT: How often (milliseconds) should it be checked whether the token needs to be refreshed?
 
   **Default**: 30 s.
+
 - CLIENT_REFRESH_TOKEN_TIMEOUT: How often (milliseconds) should it be checked whether the token needs to be refreshed?
 
   **Default**: 60 s.
+
 - CLIENT_SCHEDULING_INTERVAL: How often (milliseconds) should the scheduling be run for the logged in screen?
 
   **Default**: 60 s.
+
 - CLIENT_PULL_STRATEGY_INTERVAL: How often (milliseconds) should data be pulled from the API?
 
   **Default**: 1 m. and 30 s.
+
 - CLIENT_COLOR_SCHEME: Which colour scheme should be enabled? Should be a json object as string.
   This is used to signal how changes to darkmode are handled.
   Options are:
@@ -514,6 +524,7 @@ CLIENT_DEBUG=false
     activates darkmode according to sunrise/sunset of the location given by the longitude/latitude (lat/lng).
 
   **Default**: Library mode with a lat/lng set in Denmark.
+
 - CLIENT_DEBUG: Should the Client be in debug mode (true|false). When not in debug mode the mouse pointer is hidden.
 
   **Default**: Disabled.
@@ -654,7 +665,7 @@ actual "machine" running the screen data.
 This status can be:
 
 - "+ Tilkobl": The screen is not connected to a machine.
-- ✓ (green):  The machine is connected and running the latest code.
+- ✓ (green): The machine is connected and running the latest code.
 - i (yellow circle): The machine is not running the newest released code.
 - ! (red triangle): The machine has not called the API within the last hour or the access token is expired.
 
@@ -828,7 +839,32 @@ The slide is responsible for signaling that it is done executing.
 This is done by calling the slideDone() function. If the slide should just run for X milliseconds then you can use the
 BaseSlideExecution class to handle this. See the example for this approach.
 
-##### Admin Form
+#### custom-template-name.json
+
+The `.json` should include:
+
+```
+{
+  "title": "Billede og tekst",
+  "id": "01FP2SNGFN0BZQH03KCBXHKYHG", // ULID, https://ulidgenerator.com/
+  "options": {} // Optional, can contain extra options such as `disableLivePreview` that disables live preview in the admin UI
+  "adminForm": {} // Optional, described below
+}
+```
+
+##### Admin Form not set in json
+
+It is possible to create an interactive admin form in a `.jsx`-file. As described above with renderSlide, when a template has a custom `.jsx` admin form, it needs to implement a `renderAdminForm` function in the base file.
+
+- renderAdminForm(formStateObject, onChange, handleMedia, mediaData) - Should return the JSX for the admin form.
+  - slideContent: The slide data object from the admin, could e.g. contain a title `slideContent["title"]`
+  - onSlideContentChange: A callback for changes on the slide content.
+  - handleMedia: A function that handles saving media (only necessary if the slide has media)
+  - mediaData: An object that can contain already saved media (only necessary if the slide has media)
+
+For an example of a custom template see `assets/shared/custom-templates-example/`.
+
+##### Admin Form set in json
 
 To get content into the slide the config.adminForm field should be set. This should be an array of objects with the
 following attributes:

assets/shared/custom-templates-example/custom-template-example.jsx

@@ -2,6 +2,10 @@ import { useEffect } from "react";
 import templateConfig from "./custom-template-example.json";
 import BaseSlideExecution from "../slide-utils/base-slide-execution.js";
 import { ThemeStyles } from "../slide-utils/slide-util.jsx";
+import i18next from "i18next";
+import adminTranslations from "./translations.json";
+import { useTranslation } from "react-i18next";
+import getInputFiles from "../admin-util/helper.js";
 
 /**
  * Get the ULID of the template.
@@ -38,6 +42,17 @@ function renderSlide(slide, run, slideDone) {
   );
 }
 
+function renderAdminForm(formStateObject, onChange, handleMedia, mediaData) {
+  return (
+    <CustomTemplateAdminExample
+      formStateObject={formStateObject}
+      onChange={onChange}
+      handleMedia={handleMedia}
+      mediaData={mediaData}
+    />
+  );
+}
+
 /**
  * @param {object} props Props.
  * @param {object} props.slide The slide.
@@ -82,4 +97,69 @@ function CustomTemplateExample({
   );
 }
 
-export default { id, config, renderSlide };
+/**
+ * @param {object} props Props.
+ * @param {object} props.slideContent The slide content.
+ * @param {Function} props.onSlideContentChange on slide content change.
+ * @param {Function} props.handleMedia on slide media change.
+ * @param {object} props.mediaData The media object.
+ * @returns {JSX.Element} The component.
+ */
+function CustomTemplateAdminExample({
+  slideContent,
+  onSlideContentChange,
+  handleMedia = () => {},
+  mediaData = {},
+}) {
+  const { t } = useTranslation("custom-template-admin-example");
+
+  useEffect(() => {
+    const currentLang = i18next.language;
+    if (
+      !i18next.hasResourceBundle(currentLang, "custom-template-admin-example")
+    ) {
+      i18next.addResourceBundle(
+        currentLang,
+        "custom-template-admin-example",
+        adminTranslations["custom-template-admin-example"],
+        true,
+        true,
+      );
+    }
+  }, []);
+
+  return (
+    <>
+      <h2 className="h4 mb-3">{t("header")}</h2>
+      <fieldset>
+        <legend className="h5 mb-3">{t("content-sub-header")}</legend>
+        <label className="form-label">
+          {t("slide-title-label")}
+          <textarea
+            onChange={onSlideContentChange}
+            id="title"
+            className="col-md-6 form-control"
+            rows="3"
+            defaultValue={slideContent["title"]}
+          />
+          <small className="form-text d-flex">
+            {t("slide-title-help-text")}
+          </small>
+        </label>
+        <label className="form-label mb-0 col-9">
+          {t("images-label")}
+          <FileSelector
+            files={getInputFiles(slideContent["image"], mediaData)}
+            multiple={true}
+            onFilesChange={handleMedia}
+            name="image"
+            acceptedMimetypes="image/*"
+          />
+        </label>
+        <small>{t("images-help-text")}</small>
+      </fieldset>
+    </>
+  );
+}
+
+export default { id, config, renderSlide, renderAdminForm };

assets/shared/custom-templates-example/translations.json

@@ -0,0 +1,10 @@
+{
+  "custom-template-admin-example": {
+    "header": "Example header",
+    "content-sub-header": "Indhold",
+    "slide-title-label": "Overskrift på slide",
+    "slide-title-help-text": "Her kan du skrive overskriften til slidet",
+    "images-label": "Billeder",
+    "images-help-text": "Her tilføjer du bare et billede"
+  }
+}