Merge pull request #296 from os2display/feature/documentation-and-screen-layouts

Screen layout commands and expanded documentation

Author: tuj

.gitignore

@@ -1,6 +1,9 @@
 # Ignore custom templates folder.
 /assets/shared/custom-templates/*
 
+# Ignore custom screen layouts folder.
+/assets/shared/custom-screen-layouts/*
+
 # Ignore the public/fixtures folder.
 /public/fixtures
 

CHANGELOG.md

@@ -23,6 +23,7 @@ All notable changes to this project will be documented in this file.
 - Removed themes.
 - Added command to migrate config.json files.
 - Fix data fetching bug
+- Refactored screen layout commands.
 
 ### NB! Prior to 3.x the project was split into separate repositories
 

README.md

@@ -143,12 +143,12 @@ tasks:
   coding-standards:markdown:apply:
     desc: "Apply coding standards for Markdown."
     cmds:
-      - docker compose run --rm --volume "$PWD:/md" markdownlint markdownlint  --ignore '**/node_modules/**' --ignore '**/vendor/**' '*.md' 'documentation/*.md' --fix
+      - docker compose run --rm --volume "$PWD:/md" markdownlint markdownlint  --ignore '**/node_modules/**' --ignore '**/vendor/**' '*.md' 'docs/**/*.md' --fix
 
   coding-standards:markdown:check:
     desc: "Check coding standards for Markdown."
     cmds:
-      - docker compose run --rm --volume "$PWD:/md" markdownlint markdownlint  --ignore '**/node_modules/**' --ignore '**/vendor/**' '*.md' 'documentation/*.md'
+      - docker compose run --rm --volume "$PWD:/md" markdownlint markdownlint  --ignore '**/node_modules/**' --ignore '**/vendor/**' '*.md' 'docs/**/*.md'
 
   coding-standards:php:apply:
     desc: "Apply coding standards for PHP."

Taskfile.yml

@@ -82,3 +82,19 @@ docker compose exec phpfpm bin/console app:templates:install
 
 - Use `--all` option for installing all available templates.
 - Use `--update` option for updating existing templates.
+
+#### 6 - Run screen layout list command to see status for installed screen layouts
+
+```shell
+docker compose exec phpfpm bin/console app:screen-layouts:list
+```
+
+#### 7 - Run screen layout install for enabling screen layouts
+
+```shell
+docker compose exec phpfpm bin/console app:screen-layouts:install
+```
+
+- Use `--all` option for installing all available templates.
+- Use `--update` option for updating existing templates.
+- Use `--cleanupRegions` option for cleaning up regions that are no longer connected to a layout.

UPGRADE.md

@@ -3,14 +3,29 @@ import templateConfig from "./custom-template-example.json";
 import BaseSlideExecution from "../slide-utils/base-slide-execution.js";
 import { ThemeStyles } from "../slide-utils/slide-util.jsx";
 
+/**
+ * Get the ULID of the template.
+ * @return {string} The ULID of the template.
+ */
 function id() {
   return templateConfig.id;
 }
 
+/**
+ * Get the config object of the template.
+ * @return {{title: string, id: string, options: {}, adminForm: {}}}
+ */
 function config() {
   return templateConfig;
 }
 
+/**
+ * Render the slide.
+ * @param {object} slide The slide data.
+ * @param {string} run A date string set when the slide should start running.
+ * @param slideDone A function to invoke when the slide is done playing.
+ * @return {JSX.Element} The component.
+ */
 function renderSlide(slide, run, slideDone) {
   return (
     <CustomTemplateExample
@@ -27,9 +42,9 @@ function renderSlide(slide, run, slideDone) {
  * @param {object} props Props.
  * @param {object} props.slide The slide.
  * @param {object} props.content The slide content.
- * @param {boolean} props.run Whether or not the slide should start running.
- * @param {Function} props.slideDone Function to invoke when the slide is done playing.
- * @param {string} props.executionId Unique id for the instance.
+ * @param {string} props.run A date string set when the slide should start running.
+ * @param {Function} props.slideDone A function to invoke when the slide is done playing.
+ * @param {string} props.executionId A unique id for the instance.
  * @returns {JSX.Element} The component.
  */
 function CustomTemplateExample({
@@ -60,7 +75,9 @@ function CustomTemplateExample({
         <h1 className="title">{title}</h1>
       </div>
 
-      <ThemeStyles id={executionId} css={slide?.theme?.cssStyles} />
+      {slide?.theme?.cssStyles && (
+        <ThemeStyles id={executionId} css={slide.theme.cssStyles} />
+      )}
     </>
   );
 }