Merge pull request #711 from alphagov/template-guidance

Give users more help about what to put in their templates

app/assets/javascripts/placeholderHint.js

@@ -1,75 +0,0 @@
-(function(Modules) {
-  "use strict";
-
-  if (
-    !('oninput' in document.createElement('input'))
-  ) return;
-
-  const tagPattern = /\(\([^\)\(]+\)\)/g;
-
-  Modules.PlaceholderHint = function() {
-
-    this.start = function(component) {
-
-      this.$component = $(component);
-      this.originalHTML = this.$component.html();
-      this.$allTextboxes = $(this.$component.data('textboxes-selector'));
-      this.$targetTextbox = $(this.$component.data('target-textbox-selector'));
-
-      this.$component
-        .on('click', '.placeholder-hint-action', this.demo);
-      
-      this.$allTextboxes
-        .on('input', this.hint)
-        .trigger('input');
-
-    };
-
-    this.getPlaceholderHint = function() {
-
-      let placeholders = this.listPlaceholdersWithoutBrackets();
-
-      if (0 === placeholders.length) {
-        return `
-          ${this.originalHTML}
-          <span class='placeholder-hint-action' tabindex='0' role='button'>Show me how</span>
-        `;
-      }
-      if (1 === placeholders.length) {
-          return `
-            ${this.originalHTML}
-            <p>You’ll populate the ‘${placeholders[0]}’ field when you send messages using this template</p>
-          `;
-      }    
-      return `
-        ${this.originalHTML}
-        <p>You’ll populate your fields when you send some messages</p>
-      `;
-
-    };
-
-    this.escapedMessages = () => $('<div/>').text(
-      this.$allTextboxes.map(function() {
-          return $(this).val();
-      }).get()
-    ).html();
-
-    this.listPlaceholders = () => this.escapedMessages().match(tagPattern) || [];
-
-    this.listPlaceholdersWithoutBrackets = () => this.listPlaceholders().map(
-      placeholder => placeholder.substring(2, placeholder.length - 2)
-    );
-
-    this.renderDemo = () => this.$targetTextbox.val((i, current) => `Dear ((name)), ${current}`);
-
-    this.hint = () => this.$component.html(
-      this.getPlaceholderHint()
-    );
-
-    this.demo = () => (
-      this.renderDemo() && this.$targetTextbox.trigger('input') && this.hint()
-    );
-
-  };
-
-})(window.GOVUK.Modules);

app/assets/stylesheets/components/secondary-button.scss

@@ -6,3 +6,12 @@
   padding-right: 0;
   text-align: center;
 }
+
+.tertiary-button {
+  @include button($grey-3);
+  padding: 0.3em 0.1em 0.2em 0.1em;
+  width: 100%;
+  padding-left: 0;
+  padding-right: 0;
+  text-align: left;
+}

app/main/forms.py

@@ -198,7 +198,7 @@ class SMSTemplateForm(Form):
         validators=[DataRequired(message="Can’t be empty")])
 
     template_content = TextAreaField(
-        u'Message content',
+        u'Message',
         validators=[
             DataRequired(message="Can’t be empty"),
             NoCommasInPlaceHolders()

app/templates/partials/templates/guidance-character-count.html

@@ -0,0 +1,12 @@
+<details>
+  <summary class="button tertiary-button">Message length</summary>
+  <div id="guidance-personalisation">
+    <p>
+      If your message is long then it will
+      cost more.
+    </p>
+    <p>
+      See <a href="{{ url_for('.pricing') }}">pricing</a> for details.
+    </p>
+  </div>
+</details>

app/templates/partials/templates/guidance-links.html

@@ -0,0 +1,8 @@
+<details>
+  <summary class="button tertiary-button">Links and URLs</summary>
+  <div id="guidance-personalisation">
+    <p>
+      Always use full URLs, starting with https://
+    </p>
+  </div>
+</details>

app/templates/partials/templates/guidance-personalisation.html

@@ -0,0 +1,14 @@
+<details>
+  <summary class="button tertiary-button">Personalisation</summary>
+  <div id="guidance-personalisation">
+    <p>
+      Use double brackets to add personalisation.
+    </p>
+    <p>
+      Correct: ((name))
+    </p>
+    <p>
+      Incorrect: ((Helen))
+    </p>
+  </div>
+</details>

app/templates/views/edit-email-template.html

@@ -16,9 +16,9 @@
       <div class="grid-row">
         <div class="column-two-thirds">
           {{ textbox(form.name, width='1-1', hint='Your recipients won’t see this', rows=10) }}
+          {{ textbox(form.subject, width='1-1', highlight_tags=True, rows=2) }}
         </div>
         <div class="column-two-thirds">
-          {{ textbox(form.subject, width='1-1', highlight_tags=True, rows=2) }}
           {{ textbox(form.template_content, highlight_tags=True, width='1-1', rows=8) }}
           {{ page_footer(
             'Save',
@@ -26,13 +26,11 @@
             delete_link_text='Delete this template'
           ) }}
         </div>
-        <div class="column-one-third">
+        <aside class="column-one-third">
-          <label for='template_content' class='placeholder-hint banner-mode' data-textboxes-selector='#template_content,#subject' data-target-textbox-selector="#template_content">
+          <h2 style="margin: 0 0 5px 0;">Help</h2>
-            <div class="" id="placeholder-hint" aria-live="polite">
+          {% include "partials/templates/guidance-personalisation.html" %}
-              <p>Anything in ((double brackets)) gets replaced when you send this message</p>
+          {% include "partials/templates/guidance-links.html" %}
-            </div>
+        </aside>
-          </label>
-        </div>
       </div>
     </form>
 

app/templates/views/edit-sms-template.html

@@ -18,20 +18,19 @@
           {{ textbox(form.name, width='1-1', hint='Your recipients won’t see this') }}
         </div>
         <div class="column-two-thirds">
-          {{ textbox(form.template_content, highlight_tags=True, width='1-1') }}
+          {{ textbox(form.template_content, highlight_tags=True, width='1-1', rows=5) }}
           {{ page_footer(
             'Save',
             delete_link=url_for('.delete_service_template', service_id=current_service.id, template_id=template_id) if template_id or None,
             delete_link_text='Delete this template'
           ) }}
         </div>
-        <div class="column-one-third">
+        <aside class="column-one-third">
-          <label for='template_content' class='placeholder-hint banner-mode' data-textboxes-selector='#template_content' data-target-textbox-selector="#template_content">
+          <h2 style="margin: 0 0 5px 0;">Help</h2>
-            <div class="" id="placeholder-hint" aria-live="polite">
+          {% include "partials/templates/guidance-personalisation.html" %}
-              <p>Anything in ((double brackets)) gets replaced when you send this message</p>
+          {% include "partials/templates/guidance-links.html" %}
-            </div>
+          {% include "partials/templates/guidance-character-count.html" %}
-          </label>
+        </aside>
-        </div>
       </div>
     </form>
 

gulpfile.babel.js

@@ -60,7 +60,6 @@ gulp.task('javascripts', () => gulp
     paths.src + 'javascripts/fileUpload.js',
     paths.src + 'javascripts/updateContent.js',
     paths.src + 'javascripts/expandCollapse.js',
-    paths.src + 'javascripts/placeholderHint.js',
     paths.src + 'javascripts/main.js'
   ])
   .pipe(plugins.babel({