apostrophe 3.30.0 → 3.31.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.31.0 (2022-10-27)
+
+### Adds
+
+* Adds `placeholder: true` and `initialModal: false` features to improve the user experience of adding widgets to the page. Checkout the [Widget Placeholders documentation](https://v3.docs.apostrophecms.org/guide/areas-and-widgets.html#adding-placeholder-content-to-widgets) for more detail. 
+
 ## 3.30.0 (2022-10-12)
 
 ### Adds

package/modules/@apostrophecms/area/index.js

@@ -575,6 +575,8 @@ module.exports = {
         const widgetEditors = {};
         const widgetManagers = {};
         const widgetIsContextual = {};
+        const widgetHasPlaceholder = {};
+        const widgetHasInitialModal = {};
         const contextualWidgetDefaultData = {};
 
         _.each(self.widgetManagers, function (manager, name) {
@@ -584,6 +586,8 @@ module.exports = {
           widgetEditors[name] = (browserData && browserData.components && browserData.components.widgetEditor) || 'AposWidgetEditor';
           widgetManagers[name] = manager.__meta.name;
           widgetIsContextual[name] = manager.options.contextual;
+          widgetHasPlaceholder[name] = manager.options.placeholder;
+          widgetHasInitialModal[name] = !manager.options.placeholder && manager.options.initialModal !== false;
           contextualWidgetDefaultData[name] = manager.options.defaultData;
         });
 
@@ -594,6 +598,8 @@ module.exports = {
             widgetEditors
           },
           widgetIsContextual,
+          widgetHasPlaceholder,
+          widgetHasInitialModal,
           contextualWidgetDefaultData,
           widgetManagers,
           action: self.action

package/modules/@apostrophecms/area/ui/apos/components/AposAreaEditor.vue

@@ -404,6 +404,8 @@ export default {
       }
     },
     async update(widget) {
+      widget.aposPlaceholder = false;
+
       if (this.docId === window.apos.adminBar.contextId) {
         apos.bus.$emit('context-edited', {
           [`@${widget._id}`]: widget
@@ -434,9 +436,17 @@ export default {
       } else if (this.widgetIsContextual(name)) {
         return this.insert({
           widget: {
-            _id: cuid(),
             type: name,
-            ...this.contextualWidgetDefaultData(name)
+            ...this.contextualWidgetDefaultData(name),
+            aposPlaceholder: this.widgetHasPlaceholder(name)
+          },
+          index
+        });
+      } else if (!this.widgetHasInitialModal(name)) {
+        return this.insert({
+          widget: {
+            type: name,
+            aposPlaceholder: this.widgetHasPlaceholder(name)
           },
           index
         });
@@ -502,6 +512,12 @@ export default {
     widgetIsContextual(type) {
       return this.moduleOptions.widgetIsContextual[type];
     },
+    widgetHasPlaceholder(type) {
+      return this.moduleOptions.widgetHasPlaceholder[type];
+    },
+    widgetHasInitialModal(type) {
+      return this.moduleOptions.widgetHasInitialModal[type];
+    },
     widgetEditorComponent(type) {
       return this.moduleOptions.components.widgetEditors[type];
     },

package/modules/@apostrophecms/i18n/i18n/en.json

@@ -161,6 +161,7 @@
   "home": "Home",
   "image": "Image",
   "imageFile": "Image File",
+  "imagePlaceholder": "Image placeholder",
   "imageTag": "Image Tag",
   "imageTags": "Image Tags",
   "images": "Images",
@@ -263,6 +264,7 @@
   "richTextItalic": "Italic",
   "richTextLink": "Link",
   "richTextParagraph": "Paragraph (P)",
+  "richTextPlaceholder": "Start Typing Here...",
   "richTextH2": "Heading 2 (H2)",
   "richTextH3": "Heading 3 (H3)",
   "richTextH4": "Heading 4 (H4)",

package/modules/@apostrophecms/i18n/i18n/es.json

@@ -150,6 +150,7 @@
   "home": "Inicio",
   "image": "Imagen",
   "imageFile": "Archivo de Imagen",
+  "imagePlaceholder": "Marcador de posición de imagen",
   "imageTag": "Etiqueta de Imagen",
   "imageTags": "Etiquetas de Imágenes",
   "images": "Imágenes",
@@ -242,6 +243,7 @@
   "richTextItalic": "Cursiva",
   "richTextLink": "Liga",
   "richTextParagraph": "Párrafo (P)",
+  "richTextPlaceholder": "Comience a escribir aquí...",
   "richTextH2": "Título 2 (H2)",
   "richTextH3": "Título 3 (H3)",
   "richTextH4": "Título 4 (H4)",

package/modules/@apostrophecms/i18n/i18n/fr.json

@@ -148,6 +148,7 @@
   "home": "Accueil",
   "image": "Image",
   "imageFile": "Fichier d'image",
+  "imagePlaceholder": "Espace réservé pour l'image",
   "imageTag": "Tag d'image",
   "imageTags": "Tags d'image",
   "images": "Images",
@@ -249,6 +250,7 @@
   "richTextItalic": "Italique",
   "richTextLink": "Lien",
   "richTextParagraph": "Paragraphe (P)",
+  "richTextPlaceholder": "Commencez à écrire ici...",
   "richTextH2": "Titre de niveau 2 (H2)",
   "richTextH3": "Titre de niveau 3 (H3)",
   "richTextH4": "Titre de niveau 4 (H4)",

package/modules/@apostrophecms/i18n/i18n/pt-BR.json

@@ -150,6 +150,7 @@
   "home": "Home",
   "image": "Imagem",
   "imageFile": "Arquivo de Imagem",
+  "imagePlaceholder": "Espaço reservado para imagem",
   "imageTag": "Tag de Imagem",
   "imageTags": "Tags de Imagem",
   "images": "Imagens",
@@ -240,6 +241,7 @@
   "richTextItalic": "Itálico",
   "richTextLink": "Link",
   "richTextParagraph": "Parágrafo (P)",
+  "richTextPlaceholder": "Comece a digitar aqui...",
   "richTextH2": "Título 2 (H2)",
   "richTextH3": "Título 3 (H3)",
   "richTextH4": "Título 4 (H4)",

package/modules/@apostrophecms/i18n/i18n/sk.json

@@ -154,6 +154,7 @@
   "home": "Domovská stránka",
   "image": "Obrázok",
   "imageFile": "Súbor s obrázkom",
+  "imagePlaceholder": "Zástupný symbol obrázka",
   "imageTag": "Značku obrázku",
   "imageTags": "Značky obrázkov",
   "images": "Obrázky",
@@ -252,6 +253,7 @@
   "richTextItalic": "Kurzíva",
   "richTextLink": "Link",
   "richTextParagraph": "Odstavec (P)",
+  "richTextPlaceholder": "Začnite písať tu...",
   "richTextH2": "Nadpis 2 (H2)",
   "richTextH3": "Nadpis 3 (H3)",
   "richTextH4": "Nadpis 4 (H4)",

package/modules/@apostrophecms/image-widget/index.js

@@ -4,7 +4,10 @@ module.exports = {
     label: 'apostrophe:image',
     className: false,
     icon: 'image-icon',
-    dimensionAttrs: false
+    dimensionAttrs: false,
+    placeholder: true,
+    placeholderClass: false,
+    placeholderUrl: '/modules/@apostrophecms/image-widget/placeholder.jpg'
   },
   fields: {
     add: {

package/modules/@apostrophecms/image-widget/ui/src/index.scss

@@ -0,0 +1,3 @@
+.image-widget-placeholder {
+  width: 100%;
+}

package/modules/@apostrophecms/image-widget/views/widget.html

@@ -1,31 +1,39 @@
-{% if data.options.className %}
-  {% set className = data.options.className %}
-{% elif data.manager.options.className %}
-  {% set className = data.manager.options.className %}
-{% endif %}
+{% if data.widget.aposPlaceholder and data.manager.options.placeholderUrl %}
+  <img
+    src="{{ apos.asset.url(data.manager.options.placeholderUrl) }}"
+    alt="{{ __t('apostrophe:imagePlaceholder') }}"
+    class="image-widget-placeholder"
+  />
+{% else %}
+  {% if data.options.className %}
+    {% set className = data.options.className %}
+  {% elif data.manager.options.className %}
+    {% set className = data.manager.options.className %}
+  {% endif %}
 
-{% if data.options.dimensionAttrs %}
-  {% set dimensionAttrs = data.options.dimensionAttrs %}
-{% elif data.manager.options.dimensionAttrs  %}
-  {% set dimensionAttrs = data.manager.options.dimensionAttrs  %}
-{% endif %}
+  {% if data.options.dimensionAttrs %}
+    {% set dimensionAttrs = data.options.dimensionAttrs %}
+  {% elif data.manager.options.dimensionAttrs %}
+    {% set dimensionAttrs = data.manager.options.dimensionAttrs  %}
+  {% endif %}
 
-{% set attachment = apos.image.first(data.widget._image) %}
+  {% set attachment = apos.image.first(data.widget._image) %}
 
-{% if attachment %}
-  <img {% if className %} class="{{ className }}"{% endif %}
-    srcset="{{ apos.image.srcset(attachment) }}"
-    src="{{ apos.attachment.url(attachment, { size: data.options.size or 'full' }) }}"
-    alt="{{ attachment._alt or '' }}"
-    {% if dimensionAttrs %}
-      {% if attachment.width %} width="{{ apos.attachment.getWidth(attachment) }}" {% endif %}
-      {% if attachment.height %} height="{{ apos.attachment.getHeight(attachment) }}" {% endif %}
-    {% endif %}
-    {% if data.contextOptions and data.contextOptions.sizes %}
-      sizes="{{ data.contextOptions.sizes }}"
-    {% endif %}
-    {% if apos.attachment.hasFocalPoint(attachment) %}
-      style="object-position: {{ apos.attachment.focalPointToObjectPosition(attachment) }}"
-    {%- endif -%}
-  />
+  {% if attachment %}
+    <img {% if className %} class="{{ className }}"{% endif %}
+      srcset="{{ apos.image.srcset(attachment) }}"
+      src="{{ apos.attachment.url(attachment, { size: data.options.size or 'full' }) }}"
+      alt="{{ attachment._alt or '' }}"
+      {% if dimensionAttrs %}
+        {% if attachment.width %} width="{{ apos.attachment.getWidth(attachment) }}" {% endif %}
+        {% if attachment.height %} height="{{ apos.attachment.getHeight(attachment) }}" {% endif %}
+      {% endif %}
+      {% if data.contextOptions and data.contextOptions.sizes %}
+        sizes="{{ data.contextOptions.sizes }}"
+      {% endif %}
+      {% if apos.attachment.hasFocalPoint(attachment) %}
+        style="object-position: {{ apos.attachment.focalPointToObjectPosition(attachment) }}"
+      {%- endif -%}
+    />
+  {% endif %}
 {% endif %}

package/modules/@apostrophecms/rich-text-widget/index.js

@@ -9,6 +9,8 @@ module.exports = {
     icon: 'format-text-icon',
     label: 'apostrophe:richText',
     contextual: true,
+    placeholder: true,
+    placeholderText: 'apostrophe:richTextPlaceholder',
     defaultData: { content: '' },
     className: false,
     minimumDefaultOptions: {
@@ -417,7 +419,8 @@ module.exports = {
           tools: self.options.editorTools,
           defaultOptions: self.options.defaultOptions,
           tiptapTextCommands: self.options.tiptapTextCommands,
-          tiptapTypes: self.options.tiptapTypes
+          tiptapTypes: self.options.tiptapTypes,
+          placeholderText: self.options.placeholder && self.options.placeholderText
         };
         return finalData;
       }

package/modules/@apostrophecms/rich-text-widget/ui/apos/components/AposRichTextWidgetEditor.vue

@@ -28,7 +28,10 @@
     <div class="apos-rich-text-editor__editor" :class="editorModifiers">
       <editor-content :editor="editor" :class="editorOptions.className" />
     </div>
-    <div class="apos-rich-text-editor__editor_after" :class="editorModifiers">
+    <div
+      v-if="showPlaceholder !== null && (!placeholderText || !isFocused)"
+      class="apos-rich-text-editor__editor_after" :class="editorModifiers"
+    >
       {{ $t('apostrophe:emptyRichTextWidget') }}
     </div>
   </div>
@@ -45,6 +48,8 @@ import TextAlign from '@tiptap/extension-text-align';
 import Highlight from '@tiptap/extension-highlight';
 import TextStyle from '@tiptap/extension-text-style';
 import Underline from '@tiptap/extension-underline';
+import Placeholder from '@tiptap/extension-placeholder';
+
 export default {
   name: 'AposRichTextWidgetEditor',
   components: {
@@ -88,7 +93,9 @@ export default {
         },
         hasErrors: false
       },
-      pending: null
+      pending: null,
+      isFocused: null,
+      showPlaceholder: null
     };
   },
   computed: {
@@ -158,6 +165,9 @@ export default {
     tiptapTypes() {
       return this.moduleOptions.tiptapTypes;
     },
+    placeholderText() {
+      return this.moduleOptions.placeholderText;
+    },
     aposTiptapExtensions() {
       return (apos.tiptapExtensions || [])
         .map(extension => extension({
@@ -176,19 +186,63 @@ export default {
     }
   },
   mounted() {
+    const extensions = [
+      StarterKit,
+      TextAlign.configure({
+        types: [ 'heading', 'paragraph' ]
+      }),
+      Highlight,
+      TextStyle,
+      Underline,
+
+      // For this contextual widget, no need to check `widget.aposPlaceholder` value
+      // since `placeholderText` option is enough to decide whether to display it or not.
+      this.placeholderText && Placeholder.configure({
+        placeholder: () => {
+          // Avoid brief display of the placeholder when loading the page.
+          if (this.isFocused === null) {
+            return '';
+          }
+
+          // Display placeholder after loading the page.
+          if (this.showPlaceholder === null) {
+            return this.$t(this.placeholderText);
+          }
+
+          return this.showPlaceholder ? this.$t(this.placeholderText) : '';
+        }
+      })
+    ]
+      .filter(Boolean)
+      .concat(this.aposTiptapExtensions);
+
     this.editor = new Editor({
       content: this.initialContent,
       autofocus: this.autofocus,
       onUpdate: this.editorUpdate,
-      extensions: [
-        StarterKit,
-        TextAlign.configure({
-          types: [ 'heading', 'paragraph' ]
-        }),
-        Highlight,
-        TextStyle,
-        Underline
-      ].concat(this.aposTiptapExtensions)
+      extensions,
+
+      // The following events are triggered:
+      //  - before the placeholder configuration function, when loading the page
+      //  - after it, once the page is loaded and we interact with the editors
+      // To solve this issue, use another `this.showPlaceholder` variable
+      // and toggle it after the placeholder configuration function is called,
+      // thanks to nextTick.
+      // The proper thing would be to call nextTick inside the placeholder
+      // function so that it can rely on the focus state set by these event
+      // listeners, but the placeholder function is called synchronously...
+      onFocus: () => {
+        this.isFocused = true;
+        this.$nextTick(() => {
+          this.showPlaceholder = false;
+        });
+      },
+      onBlur: () => {
+        this.isFocused = false;
+        this.$nextTick(() => {
+          this.showPlaceholder = true;
+        });
+      }
     });
   },
 
@@ -336,6 +390,14 @@ export default {
     outline: none;
   }
 
+  .apos-rich-text-editor__editor ::v-deep .ProseMirror p.is-empty:first-child::before {
+    content: attr(data-placeholder);
+    float: left;
+    pointer-events: none;
+    height: 0;
+    color: var(--a-base-4);
+  }
+
   .apos-rich-text-editor__editor {
     @include apos-transition();
     position: relative;

package/modules/@apostrophecms/video-widget/index.js

@@ -14,7 +14,10 @@ module.exports = {
   options: {
     label: 'apostrophe:video',
     className: false,
-    icon: 'play-box-icon'
+    icon: 'play-box-icon',
+    placeholder: true,
+    placeholderClass: false,
+    placeholderUrl: 'https://youtu.be/Q5UX9yexEyM'
   },
   fields: {
     add: {

package/modules/@apostrophecms/video-widget/views/widget.html

@@ -1,20 +1,28 @@
-{% if data.options.className %}
-  {% set className = data.options.className %}
-{% elif data.manager.options.className %}
-  {% set className = data.manager.options.className %}
-{% endif %}
-
-{# oembed repopulates me #}
-{% if data.widget.video %}
+{% if data.widget.aposPlaceholder and data.manager.options.placeholderUrl %}
   <div
-    {% if className %} class="{{ className }}"{% endif %}
     data-apos-video-widget
-    data-apos-video-url={{ data.widget.video.url }}
+    data-apos-video-url="{{ data.manager.options.placeholderUrl }}"
   >
-    {% if data.widget.video.thumbnail %}
-    <img src="{{ data.widget.video.thumbnail }}" alt="{{ data.widget.video.thumbnail }}"/>
-    {% endif %}
   </div>
-{% elif data.user %}
-  <p {% if data.manager.options.className %} class="{{ data.manager.options.className }} {{ data.manager.options.className }}--error"{% endif %}>No video selected</p>
-{% endif %}
+{% else %}
+  {% if data.options.className %}
+    {% set className = data.options.className %}
+  {% elif data.manager.options.className %}
+    {% set className = data.manager.options.className %}
+  {% endif %}
+
+  {# oembed repopulates me #}
+  {% if data.widget.video %}
+    <div
+      {% if className %} class="{{ className }}"{% endif %}
+      data-apos-video-widget
+      data-apos-video-url={{ data.widget.video.url }}
+    >
+      {% if data.widget.video.thumbnail %}
+      <img src="{{ data.widget.video.thumbnail }}" alt="{{ data.widget.video.thumbnail }}"/>
+      {% endif %}
+    </div>
+  {% elif data.user %}
+    <p {% if data.manager.options.className %} class="{{ data.manager.options.className }} {{ data.manager.options.className }}--error"{% endif %}>No video selected</p>
+  {% endif %}
+{% endif %}

package/modules/@apostrophecms/widget-type/index.js

@@ -97,7 +97,10 @@ const _ = require('lodash');
 module.exports = {
   cascades: [ 'fields' ],
   options: {
-    neverLoadSelf: true
+    neverLoadSelf: true,
+    initialModal: true,
+    placeholder: false,
+    placeholderClass: 'apos-placeholder'
   },
   init(self) {
 
@@ -161,8 +164,24 @@ module.exports = {
           ...self.getWidgetsBundles(`${widget.type}-widget`)
         };
 
+        let effectiveWidget = widget;
+
+        if (widget.aposPlaceholder === true) {
+          // Do not render widget on preview mode:
+          if (req.query.aposEdit !== '1') {
+            return '';
+          }
+
+          effectiveWidget = { ...widget };
+          self.schema.forEach(field => {
+            if (field.placeholder !== undefined) {
+              effectiveWidget[field.name] = field.placeholder;
+            }
+          });
+        }
+
         return self.render(req, self.template, {
-          widget: widget,
+          widget: effectiveWidget,
           options: options,
           manager: self,
           contextOptions: _with
@@ -276,11 +295,14 @@ module.exports = {
         // Make sure we get default values for contextual fields so
         // `by` doesn't go missing for `@apostrophecms/image-widget`
         const output = self.apos.schema.newInstance(self.schema);
-        const schema = self.allowedSchema(req);
         output._id = self.apos.launder.id(input._id) || self.apos.util.generateId();
-        await self.apos.schema.convert(req, schema, input, output);
         output.metaType = 'widget';
         output.type = self.name;
+        output.aposPlaceholder = self.apos.launder.boolean(input.aposPlaceholder);
+        if (!output.aposPlaceholder) {
+          const schema = self.allowedSchema(req);
+          await self.apos.schema.convert(req, schema, input, output);
+        }
         return output;
       },
 
@@ -352,7 +374,7 @@ module.exports = {
           action: self.action,
           schema: schema,
           contextual: self.options.contextual,
-          skipInitialModal: self.options.skipInitialModal,
+          placeholderClass: self.options.placeholderClass,
           className: self.options.className,
           components: self.options.components
         });

package/modules/@apostrophecms/widget-type/ui/apos/components/AposWidget.vue

@@ -1,6 +1,9 @@
+<!-- eslint-disable vue/no-v-html -->
 <template>
-  <!-- eslint-disable-next-line vue/no-v-html -->
-  <div v-html="rendered" />
+  <div
+    :class="getClasses()"
+    v-html="rendered"
+  />
 </template>
 
 <script>

package/modules/@apostrophecms/widget-type/ui/apos/mixins/AposWidgetMixin.js

@@ -62,6 +62,17 @@ export default {
         this.rendered = '<p>Unable to render this widget.</p>';
         console.error('Unable to render widget. Possibly the schema has been changed and the existing widget does not pass validation.', e);
       }
+    },
+    getClasses() {
+      const { placeholderClass } = this.moduleOptions;
+
+      if (!placeholderClass) {
+        return {};
+      }
+
+      return {
+        [placeholderClass]: this.value.aposPlaceholder === true
+      };
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apostrophe",
-  "version": "3.30.0",
+  "version": "3.31.0",
   "description": "The Apostrophe Content Management System.",
   "main": "index.js",
   "scripts": {
@@ -35,6 +35,7 @@
     "@opentelemetry/semantic-conventions": "^1.0.1",
     "@tiptap/extension-highlight": "^2.0.0-beta.33",
     "@tiptap/extension-link": "^2.0.0-beta.38",
+    "@tiptap/extension-placeholder": "^2.0.0-beta.196",
     "@tiptap/extension-text-align": "^2.0.0-beta.29",
     "@tiptap/extension-text-style": "^2.0.0-beta.23",
     "@tiptap/extension-underline": "^2.0.0-beta.23",
@@ -124,16 +125,16 @@
     "eslint-config-apostrophe": "^3.4.0",
     "eslint-plugin-n": "^15.2.1",
     "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^5.1.0",
     "eslint-plugin-vue": "^7.9.0",
     "mocha": "^9.1.2",
     "nyc": "^15.1.0",
     "replace-in-file": "^6.1.0",
-    "vue-eslint-parser": "^7.1.1",
-    "webpack-bundle-analyzer": "^3.9.0",
-    "eslint-plugin-promise": "^5.1.0",
     "stylelint": "^14.6.1",
     "stylelint-declaration-strict-value": "^1.8.0",
-    "stylelint-order": "^5.0.0"
+    "stylelint-order": "^5.0.0",
+    "vue-eslint-parser": "^7.1.1",
+    "webpack-bundle-analyzer": "^3.9.0"
   },
   "browserslist": [
     "ie >= 10"

package/test/modules/placeholder-page/index.js

@@ -0,0 +1,21 @@
+module.exports = {
+  extend: '@apostrophecms/page-type',
+  options: {
+    label: 'Placeholder Test Page'
+  },
+  fields: {
+    add: {
+      main: {
+        type: 'area',
+        label: 'Main',
+        options: {
+          widgets: {
+            placeholder: {},
+            '@apostrophecms/image': {},
+            '@apostrophecms/video': {}
+          }
+        }
+      }
+    }
+  }
+};

package/test/modules/placeholder-page/views/page.html

@@ -0,0 +1,3 @@
+<h2>Placeholder Test Page</h2>
+
+{% area data.page, 'main' %}

package/test/modules/placeholder-widget/index.js

@@ -0,0 +1,36 @@
+module.exports = {
+  extend: '@apostrophecms/widget-type',
+  options: {
+    label: 'Placeholder Test Widget',
+    placeholder: true
+  },
+  fields: {
+    add: {
+      string: {
+        type: 'string',
+        label: 'String',
+        placeholder: 'String PLACEHOLDER'
+      },
+      integer: {
+        type: 'integer',
+        label: 'Integer',
+        placeholder: 0
+      },
+      float: {
+        type: 'float',
+        label: 'Float',
+        placeholder: 0.1
+      },
+      date: {
+        type: 'date',
+        label: 'Date',
+        placeholder: 'YYYY-MM-DD'
+      },
+      time: {
+        type: 'time',
+        label: 'Time',
+        placeholder: 'HH:MM:SS'
+      }
+    }
+  }
+};

package/test/modules/placeholder-widget/views/widget.html

@@ -0,0 +1,5 @@
+<ul>
+{% for key, val in data.widget %}
+  <li>{{ data.widget._id }} - {{ key }}: {{ val }}</li>
+{% endfor %}
+</ul>

package/test/widgets.js

@@ -1,154 +1,493 @@
 const t = require('../test-lib/test.js');
 const assert = require('assert');
-
-let apos;
+const { JSDOM } = require('jsdom');
 
 describe('Widgets', function() {
+  const getRenderArgs = (req, page) => ({
+    outerLayout: '@apostrophecms/template:outerLayout.html',
+    permissions: req.user && (req.user._permissions || {}),
+    scene: 'apos',
+    refreshing: false,
+    query: req.query,
+    url: req.url,
+    page
+  });
+  let apos;
+  let req;
+  let homePath;
 
   this.timeout(t.timeout);
 
-  after(async function() {
-    return t.destroy(apos);
-  });
-
-  it('should add test modules', async function() {
+  before(async function() {
     apos = await t.create({
       root: module,
       modules: {
         'args-bad-page': {},
         'args-good-page': {},
-        'args-widget': {}
+        'args-widget': {},
+        'placeholder-page': {},
+        'placeholder-widget': {}
       }
     });
-    assert(apos.modules['args-good-page']);
-    assert(apos.modules['args-bad-page']);
-    assert(apos.modules['args-widget']);
+
+    req = apos.task.getAnonReq({
+      query: {
+        aposEdit: '1'
+      }
+    });
+
+    const home = await apos.page.find(req, { level: 0 }).toObject();
+    homePath = home._id.replace(':en:published', '');
+  });
+
+  after(function() {
+    return t.destroy(apos);
   });
 
-  let testItems;
+  describe('area tag', function() {
+    let testItems = [];
 
-  it('should insert test documents', async function() {
-    const home = await apos.page.find(apos.task.getAnonReq(), { level: 0 }).toObject();
+    before(async function() {
+      testItems = [
+        {
+          _id: 'goodPageId:en:published',
+          aposLocale: 'en:published',
+          aposDocId: 'goodPageId',
+          type: 'args-good-page',
+          slug: '/good-page',
+          visibility: 'public',
+          path: `${homePath}/good-page`,
+          level: 1,
+          rank: 0,
+          metaType: 'doc',
+          main: {
+            _id: 'randomAreaId1',
+            items: [
+              {
+                _id: 'randomWidgetId1',
+                snippet: 'You can control what happens when the text reaches the edges of its content area using its attributes.',
+                metaType: 'widget',
+                type: 'args'
+              }
+            ],
+            metaType: 'area'
+          }
+        },
+        {
+          _id: 'badPageId:en:published',
+          aposLocale: 'en:published',
+          aposDocId: 'badPageId',
+          type: 'args-bad-page',
+          slug: '/bad-page',
+          visibility: 'public',
+          path: `${homePath}/bad-page`,
+          level: 1,
+          rank: 0,
+          metaType: 'doc',
+          main: {
+            _id: 'randomAreaId2',
+            items: [
+              {
+                _id: 'randomWidgetId2',
+                snippet: 'You can control what happens when the text reaches the edges of its content area using its attributes.',
+                metaType: 'widget',
+                type: 'args'
+              }
+            ],
+            metaType: 'area'
+          }
+        }
+      ];
 
-    assert(home);
-    const homeId = home._id;
+      await apos.doc.db.insertMany(testItems.map(item => ({
+        ...item,
+        aposLocale: item.aposLocale.replace(':published', ':draft'),
+        _id: item._id.replace(':published', ':draft')
+      })));
 
-    testItems = [
-      {
-        _id: 'goodPageId:en:published',
+      await apos.doc.db.insertMany(testItems);
+    });
+
+    after(async function() {
+      await apos.doc.db.deleteMany({
+        aposDocId: {
+          $in: testItems.map(item => item.aposDocId)
+        }
+      });
+    });
+
+    it('should be able to render page template with well constructed area tag', async function() {
+      const goodPageDoc = await apos.page.find(req, { slug: '/good-page' }).toObject();
+
+      const args = getRenderArgs(req, goodPageDoc);
+      const result = await apos.modules['args-good-page'].render(req, 'page', args);
+
+      assert(result.includes('<h2>Good args page</h2>'));
+      assert(result.includes('<p>You can control what happens when the text reaches the edges of its content area using its attributes.</p>'));
+      assert(result.includes('<li>color: 🟣</li>'));
+    });
+
+    it('should error while trying to render page template with poorly constructed area tag', async function() {
+      const badPageDoc = await apos.page.find(req, { slug: '/bad-page' }).toObject();
+
+      const args = getRenderArgs(req, badPageDoc);
+
+      try {
+        await apos.modules['args-bad-page'].render(req, 'page', args);
+
+        assert(false);
+      } catch (error) {
+        assert(error.toString().includes('Too many arguments were passed'));
+      }
+    });
+  });
+
+  describe('placeholders', function() {
+    const insertPage = async (apos, homePath, widgets) => {
+      const page = {
+        _id: 'placeholder-page:en:published',
         aposLocale: 'en:published',
-        aposDocId: 'goodPageId',
-        type: 'args-good-page',
-        slug: '/good-page',
+        aposDocId: 'placeholder-page',
+        type: 'placeholder-page',
+        slug: '/placeholder-page',
         visibility: 'public',
-        path: `${homeId.replace(':en:published', '')}/good-page`,
+        path: `${homePath}/placeholder-page`,
         level: 1,
         rank: 0,
+        metaType: 'doc',
         main: {
-          _id: 'randomAreaId1',
-          items: [
-            {
-              _id: 'randomWidgetId1',
-              snippet: 'You can control what happens when the text reaches the edges of its content area using its attributes.',
-              metaType: 'widget',
-              type: 'args'
-            }
-          ],
+          _id: 'area1',
+          items: widgets,
           metaType: 'area'
         }
+      };
+
+      await apos.doc.db.insertOne(page);
+      await apos.doc.db.insertOne({
+        ...page,
+        aposLocale: page.aposLocale.replace(':published', ':draft'),
+        _id: page._id.replace(':published', ':draft')
+      });
+    };
+
+    const deletePage = async (apos, page) => {
+      await apos.doc.db.deleteMany({
+        aposDocId: page.aposDocId
+      });
+    };
+
+    describe('custom widget', function() {
+      const widgetBaseData = {
+        metaType: 'widget',
+        type: 'placeholder'
+      };
+      const widgetData = {
+        ...widgetBaseData,
+        string: 'Some string',
+        integer: 2,
+        float: 2.2,
+        date: '2022-09-21',
+        time: '15:39:12'
+      };
+
+      let page;
+      let result;
+
+      before(async function() {
+        const widgets = [
+          {
+            _id: 'widget1',
+            ...widgetBaseData,
+            aposPlaceholder: true
+          },
+          {
+            _id: 'widget2',
+            ...widgetBaseData,
+            aposPlaceholder: false
+          },
+          {
+            _id: 'widget3',
+            ...widgetBaseData
+          },
+          {
+            _id: 'widget4',
+            ...widgetData
+          }
+        ];
+
+        await insertPage(apos, homePath, widgets);
+        page = await apos.page.find(req, { slug: '/placeholder-page' }).toObject();
+
+        const args = getRenderArgs(req, page);
+        result = await apos.modules['placeholder-page'].render(req, 'page', args);
+      });
+
+      after(async function() {
+        await deletePage(apos, page);
+      });
+
+      it('should render the placeholders when widget\'s `aposPlaceholder` doc field is `true`', function() {
+        assert(result.includes('<li>widget1 - aposPlaceholder: true</li>'));
+        assert(result.includes('<li>widget1 - string: String PLACEHOLDER</li>'));
+        assert(result.includes('<li>widget1 - integer: 0</li>'));
+        assert(result.includes('<li>widget1 - float: 0.1</li>'));
+        assert(result.includes('<li>widget1 - date: YYYY-MM-DD</li>'));
+        assert(result.includes('<li>widget1 - time: HH:MM:SS</li>'));
+      });
+
+      it('should not render the placeholders when widget\'s `aposPlaceholder` doc field is `false`', function() {
+        assert(result.includes('<li>widget2 - aposPlaceholder: false</li>'));
+        assert(!result.includes('<li>widget2 - string: String PLACEHOLDER</li>'));
+        assert(!result.includes('<li>widget2 - integer: 0</li>'));
+        assert(!result.includes('<li>widget2 - float: 0.1</li>'));
+        assert(!result.includes('<li>widget2 - date: YYYY-MM-DD</li>'));
+        assert(!result.includes('<li>widget2 - time: HH:MM:SS</li>'));
+      });
+
+      it('should not render the placeholders when widget\'s `aposPlaceholder` doc field is not defined', function() {
+        assert(!result.includes('<li>widget3 - string: String PLACEHOLDER</li>'));
+        assert(!result.includes('<li>widget3 - integer: 0</li>'));
+        assert(!result.includes('<li>widget3 - float: 0.1</li>'));
+        assert(!result.includes('<li>widget3 - date: YYYY-MM-DD</li>'));
+        assert(!result.includes('<li>widget3 - time: HH:MM:SS</li>'));
+
+        assert(result.includes('<li>widget4 - string: Some string</li>'));
+        assert(result.includes('<li>widget4 - integer: 2</li>'));
+        assert(result.includes('<li>widget4 - float: 2.2</li>'));
+        assert(result.includes('<li>widget4 - date: 2022-09-21</li>'));
+        assert(result.includes('<li>widget4 - time: 15:39:12</li>'));
+      });
+
+      it('should not render the placeholders on preview mode', async function() {
+        // eslint-disable-next-line no-unused-vars
+        const { aposEdit, ...query } = req.query;
+        const _nonEditingReq = {
+          ...req,
+          query
+        };
+        const args = getRenderArgs(_nonEditingReq, page);
+        const _result = await apos.modules['placeholder-page'].render(_nonEditingReq, 'page', args);
+
+        assert(!_result.includes('widget1'));
+      });
+    });
+
+    const mediaWidgetTypeToAssertion = {
+      image: {
+        placeholderUrlOverride: '/modules/@apostrophecms/my-image-widget/placeholder.webp',
+        assertAposPlaceholderTrue(document) {
+          const imgNodes = document.querySelectorAll('img');
+
+          assert(imgNodes.length === 1);
+          assert(imgNodes[0].classList.contains('image-widget-placeholder'));
+          assert(imgNodes[0].alt === 'Image placeholder');
+          assert(imgNodes[0].src === '/apos-frontend/default/modules/@apostrophecms/image-widget/placeholder.jpg');
+        },
+        assertPreviewMode(document) {
+          const imgNodes = document.querySelectorAll('img');
+
+          assert(imgNodes.length === 0);
+        },
+        assertFalsyPlaceholderUrl(document) {
+          const imgNodes = document.querySelectorAll('img');
+
+          assert(imgNodes.length === 0);
+        },
+        assertPlaceholderUrlOverride(document) {
+          const imgNodes = document.querySelectorAll('img');
+
+          assert(imgNodes.length === 1);
+          assert(imgNodes[0].classList.contains('image-widget-placeholder'));
+          assert(imgNodes[0].alt === 'Image placeholder');
+          assert(imgNodes[0].src === '/apos-frontend/default/modules/@apostrophecms/my-image-widget/placeholder.webp');
+        }
       },
-      {
-        _id: 'badPageId:en:published',
-        aposLocale: 'en:published',
-        aposDocId: 'badPageId',
-        type: 'args-bad-page',
-        slug: '/bad-page',
-        visibility: 'public',
-        path: `${homeId.replace(':en:published', '')}/bad-page`,
-        level: 1,
-        rank: 0,
-        main: {
-          _id: 'randomAreaId2',
-          items: [
-            {
-              _id: 'randomWidgetId2',
-              snippet: 'You can control what happens when the text reaches the edges of its content area using its attributes.',
-              metaType: 'widget',
-              type: 'args'
-            }
-          ],
-          metaType: 'area'
+      video: {
+        placeholderUrlOverride: 'https://vimeo.com/57946935',
+        assertAposPlaceholderTrue(document) {
+          const videoWrapperNodes = document.querySelectorAll('[data-apos-video-widget]');
+
+          assert(videoWrapperNodes.length === 1);
+          assert(videoWrapperNodes[0].dataset.aposVideoUrl === 'https://youtu.be/Q5UX9yexEyM');
+        },
+        assertPreviewMode(document) {
+          const videoWrapperNodes = document.querySelectorAll('[data-apos-video-widget]');
+
+          assert(videoWrapperNodes.length === 0);
+        },
+        assertFalsyPlaceholderUrl(document) {
+          const videoWrapperNodes = document.querySelectorAll('[data-apos-video-widget]');
+
+          assert(videoWrapperNodes.length === 0);
+        },
+        assertPlaceholderUrlOverride(document) {
+          const videoWrapperNodes = document.querySelectorAll('[data-apos-video-widget]');
+
+          assert(videoWrapperNodes.length === 1);
+          assert(videoWrapperNodes[0].dataset.aposVideoUrl === 'https://vimeo.com/57946935');
         }
       }
-    ];
+    };
+
+    Object.entries(mediaWidgetTypeToAssertion).forEach(([
+      type,
+      {
+        placeholderUrlOverride,
+        assertAposPlaceholderTrue,
+        assertPreviewMode,
+        assertFalsyPlaceholderUrl,
+        assertPlaceholderUrlOverride
+      }
+    ]) => {
+      describe(`${type} widget`, function() {
+        const widgetBaseData = {
+          metaType: 'widget',
+          type: `@apostrophecms/${type}`
+        };
+        const widgets = [
+          {
+            _id: 'widget1',
+            ...widgetBaseData,
+            aposPlaceholder: true
+          },
+          {
+            _id: 'widget2',
+            ...widgetBaseData,
+            aposPlaceholder: false
+          },
+          {
+            _id: 'widget3',
+            ...widgetBaseData
+          }
+        ];
 
-    // Insert draft versions too to match the A3 data model
-    const draftItems = await apos.doc.db.insertMany(testItems.map(item => ({
-      ...item,
-      aposLocale: item.aposLocale.replace(':published', ':draft'),
-      _id: item._id.replace(':published', ':draft')
-    })));
-    assert(draftItems.result.ok === 1);
-    assert(draftItems.insertedCount === 2);
+        let page;
+        let result;
 
-    const items = await apos.doc.db.insertMany(testItems);
+        before(async function() {
+          await insertPage(apos, homePath, widgets);
+          page = await apos.page.find(req, { slug: '/placeholder-page' }).toObject();
 
-    assert(items.result.ok === 1);
-    assert(items.insertedCount === 2);
-  });
+          const args = getRenderArgs(req, page);
+          result = await apos.modules['placeholder-page'].render(req, 'page', args);
+        });
 
-  it('should be able to render page template with well constructed area tag', async function() {
-    const req = apos.task.getAnonReq();
-
-    const goodPageDoc = await apos.page.find(req, { slug: '/good-page' })
-      .toObject();
-    goodPageDoc.metaType = 'doc';
-
-    const args = {
-      outerLayout: '@apostrophecms/template:outerLayout.html',
-      permissions: req.user && (req.user._permissions || {}),
-      scene: 'apos',
-      refreshing: false,
-      query: req.query,
-      url: req.url,
-      page: goodPageDoc
-    };
+        after(async function() {
+          await deletePage(apos, page);
+        });
 
-    let result;
-    try {
-      result = await apos.modules['args-good-page'].render(req, 'page', args);
-    } catch (error) {
-      assert(false);
-    }
+        it('should render the placeholder only when widget\'s `aposPlaceholder` doc field is `true`', function() {
+          const { document } = new JSDOM(result).window;
 
-    assert(result.indexOf('<h2>Good args page</h2>') !== -1);
-    assert(result.indexOf('<p>You can control what happens when the text reaches the edges of its content area using its attributes.</p>') !== -1);
-    assert(result.indexOf('<li>color: 🟣</li>') !== -1);
-  });
+          assertAposPlaceholderTrue(document);
+        });
 
-  it('should error while trying to render page template with poorly constructed area tag', async function() {
-    const req = apos.task.getAnonReq();
-
-    const badPageDoc = await apos.page.find(req, { slug: '/bad-page' })
-      .toObject();
-    badPageDoc.metaType = 'doc';
-
-    const args = {
-      outerLayout: '@apostrophecms/template:outerLayout.html',
-      permissions: req.user && (req.user._permissions || {}),
-      scene: 'apos',
-      refreshing: false,
-      query: req.query,
-      url: req.url,
-      page: badPageDoc
-    };
+        it('should not render the placeholders on preview mode', async function() {
+          // eslint-disable-next-line no-unused-vars
+          const { aposEdit, ...query } = req.query;
+          const _nonEditingReq = {
+            ...req,
+            query
+          };
+          const args = getRenderArgs(_nonEditingReq, page);
+          const _result = await apos.modules['placeholder-page'].render(_nonEditingReq, 'page', args);
+
+          const { document } = new JSDOM(_result).window;
+          assertPreviewMode(document);
+        });
+
+        describe('placeholderUrl - falsy', function() {
+          let _apos;
+          let _page;
+          let _result;
+
+          before(async function() {
+            // Recreate local apos instance with falsy `placeholderUrl` option set to widget module
+            _apos = await t.create({
+              root: module,
+              modules: {
+                'placeholder-page': {},
+                [`@apostrophecms/${type}-widget`]: {
+                  options: {
+                    placeholderUrl: null
+                  }
+                }
+              }
+            });
+            const _req = _apos.task.getAnonReq({
+              query: {
+                aposEdit: '1'
+              }
+            });
+
+            const home = await _apos.page.find(_req, { level: 0 }).toObject();
+            const _homePath = home._id.replace(':en:published', '');
+
+            await insertPage(_apos, _homePath, widgets);
+            _page = await _apos.page.find(_req, { slug: '/placeholder-page' }).toObject();
 
-    try {
-      await apos.modules['args-bad-page'].render(req, 'page', args);
+            const args = getRenderArgs(_req, _page);
+            _result = await _apos.modules['placeholder-page'].render(_req, 'page', args);
+          });
 
-      assert(false);
-    } catch (error) {
-      assert(error.toString().indexOf('Too many arguments were passed') !== -1);
-    }
+          after(async function() {
+            await deletePage(_apos, _page);
+            await t.destroy(_apos);
+          });
+
+          it('should not render the placeholder when widget\'s module `placeholderUrl` option is falsy', function() {
+            const { document } = new JSDOM(_result).window;
+
+            assertFalsyPlaceholderUrl(document);
+          });
+        });
+
+        describe('placeholderUrl - override', function() {
+          let _apos;
+          let _page;
+          let _result;
+
+          before(async function() {
+            // Recreate local apos instance with falsy `placeholderUrl` option set to widget module
+            _apos = await t.create({
+              root: module,
+              modules: {
+                'placeholder-page': {},
+                [`@apostrophecms/${type}-widget`]: {
+                  options: {
+                    placeholderUrl: placeholderUrlOverride
+                  }
+                }
+              }
+            });
+            const _req = _apos.task.getAnonReq({
+              query: {
+                aposEdit: '1'
+              }
+            });
+
+            const home = await _apos.page.find(_req, { level: 0 }).toObject();
+            const _homePath = home._id.replace(':en:published', '');
+
+            await insertPage(_apos, _homePath, widgets);
+            _page = await _apos.page.find(_req, { slug: '/placeholder-page' }).toObject();
+
+            const args = getRenderArgs(_req, _page);
+            _result = await _apos.modules['placeholder-page'].render(_req, 'page', args);
+          });
+
+          after(async function() {
+            await deletePage(_apos, _page);
+            await t.destroy(_apos);
+          });
+
+          it('should render the placeholder set to the widget\'s module `placeholderUrl` override', function() {
+            const { document } = new JSDOM(_result).window;
+
+            assertPlaceholderUrlOverride(document);
+          });
+        });
+      });
+    });
   });
 });