form-jekyll 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c9949aec210ca48d310c1d9b61680302a77780315361fe4a2344f83925f4548d
+  data.tar.gz: '08ef7fa015ad34b53f29b1dc75a45ef07bd28c95142dbeb9128f7dd7de915654'
+SHA512:
+  metadata.gz: 9e4cdf7453cff305635708a0d02614b728a3a777c0fb4464e3f58d327aa729645af94fd555cf6c3df9a0b80056e5706c766bffc18475451413426d578388ff7f
+  data.tar.gz: 7dc2246b0331309f16821eda509311019467929d6e2f181482c588e6fa1dfa367d7bfacb88d00facc156ecb41b0fc8cf6d201e34dfb660de2bca04a7cf511ae9

data/README.md

@@ -0,0 +1,83 @@
+# form-jekyll
+
+### Goals of this tool
+
+- Designers can prototype, comment, and iterate on forms as easily as they might a Google Doc.
+
+- Designers can easily give external stakeholders a realistic preview of how a form will work.
+
+### What is it?
+
+`form-jekyll` is a Jekyll theme that lets you easily build a prototype of an SF.GOV form in a YAML file. Right now, it lets you add:
+
+- Multiple field types
+- Custom error messages
+- Custom input widths, tied to the `maxlength` attribute
+- Conditionals for radio buttons, checkboxes, and text fields
+- "Less than" or "greater than" conditionals for number fields
+- Markdown-formatted content
+
+
+Since YAML is easy to read, non-technical colleagues can easily give feedback on form design and content inside a GitHub pull request. And because GitHub Pages uses Jekyll, you can easily deploy a form to a webpage and send the link to external stakeholders.
+
+### Example
+
+```
+- title: Page Title
+  fields:
+  - label: Name
+
+  - label: Phone number
+    type: phone
+    error: You need to enter a valid phone number.
+
+  - label: Do you have an email address?
+    type: radio
+    options:
+    - label: Yes
+      shows: email-field
+
+    - label: No
+      hides: email-field
+
+  - group: email-field
+    fields:
+    - label: Enter your email address here
+      type: email
+
+  - label: How did you hear about us?
+    optional: true
+```
+
+### Field properties
+
+| Property name   | Description                                                                           | Expected format       |
+|----------|---------------------------------------------------------------------------------------|-----------------------|
+| `title` | The title of the current page | Plain text |
+| `fields` | The fields within a page or `group`. | A nested list of fields |
+| `label`    | The field's label                                                                     | Plain text            |
+| `helptext` | The field's help text                                                                 | Markdown |
+| `type`     | The input type. For a full list of fields, see the file names in `_includes/fields.`  | Plain text            |
+| `options`  | The possible answers for `radio`, `checkbox`, and `select` fields.                    | A list of options     |
+| `checked`  | Determines whether a radio or checkbox option should be checked by default.            | `true`                |
+| `optional` | Determines whether a field is optional                                                | `true`                |
+| `other` | Determines whether a set of radio buttons or checkboxes has an "Other" option | `true` |
+| `error`    | The custom error message that should display if the field is invalid or blank.        | Plain text            |
+| `shows`    | The name of the `group` that should be conditionally shown if this field is checked.  | The name of a `group` |
+| `level`    |  The header level for `header` fields. For example, `level: 1` will produce an H1. | A number between `1` and `5`|
+| `group` | The name of the group of fields you wish to conditionally show or hide. | Plain text |
+| `size` | The vertical height of a textarea | `small`, `medium` or `large` |
+| `unit` | The desired units of a number field (e.g. "yards", "liters", "days") | Plain text |
+| `url` | The URL of a link. | Plain text |
+| `maxlength` | The maximum character length of a number or text field. | A number between `1` and `15` |
+| `if` | The logic that will trigger a conditional for a free-text field. | <ul><li markdown="1">Plain text or a number (for exact matches)</li><li markdown="1">`<X` to match all numbers less than X (e.g. `<49`)</li><li markdown="1">`>X` to match all numbers greater than X (e.g. `>49`)</li> |
+| `address-fields` | The inputs to show in an address fields. (All inputs are visible by default.) | A nested list containing `street`, `city`, `state` and `zip` |
+
+
+
+
+### Local development
+
+- Setup Jekyll - https://jekyllrb.com/docs/installation/
+- Install Gemfile - `bundle install`
+- Run Jekyll - `bundle exec jekyll serve`

data/_includes/elements/helptext.html

@@ -0,0 +1,3 @@
+{% if helptext %}
+  <div class="help-text" data-valtype='help'>{{ helptext | markdownify | improve }}</div>
+{% endif %}

data/_includes/elements/label.html

@@ -0,0 +1 @@
+{{ label | markdownify | remove: '<p>' | remove: '</p>' | improve}}{% if optional %} <span class="optional">(optional)</span>{% endif %}

data/_includes/fields/address.html

@@ -0,0 +1,41 @@
+{% assign address-error = "You need to fill in a complete address." %}
+
+<fieldset class="field-address">
+  <legend>{% include elements/label.html %}</legend>
+
+  {% if address-fields contains 'street' or address-fields == 'full' %}
+    <label for="{{ name}}-line1">Address Line 1</label>
+    <input type="text" id="{{ name}}-line1" {% unless optional %}required="required" data-error="{{ address-error }}"{% endunless %}>
+
+    <label for="{{ name}}-line2">Address Line 2 {% unless optional %}<span class="optional">(optional)</span>{% endunless %}</label>
+    <input type="text" id="{{ name }}-line2">
+  {% endif %}
+
+
+  {% if address-fields contains 'city' or address-fields == 'full' %}
+    <label for="{{ name}}-city">City</label>
+    <input type="text" id="{{ name}}-city" {% unless optional %}required="required" data-error="{{ address-error }}"{% endunless %}>
+  {% endif %}
+
+  {% if address-fields contains 'state' or address-fields == 'full' %}
+    <div class="field-address-state">
+      <label for="{{ name}}-state">State</label>
+      <select id="{{ name}}-state" {% unless optional %}required="required" data-error="{{ address-error }}"{% endunless %}>
+        <option value="">Choose a state</option>
+        {% for state in site.data.states %}
+          <option value="{{ state.value }}">{{ state.text }}</option>
+        {% endfor %}
+      </select>
+    </div>
+  {% endif %}
+
+  {% if address-fields contains 'zip' or address-fields == 'full' %}
+    <div class="field-address-zip">
+      <label for="{{ name}}-zip" {% unless optional %}required="required" data-error="{{ address-error }}"{% endunless %}>ZIP Code</label>
+      <input type="text" id="{{ name}}-zip" maxlength="5" class="length-5">
+    </div>
+  {% endif %}
+
+  {% include elements/helptext.html %}
+
+</fieldset>

data/_includes/fields/checkbox.html

@@ -0,0 +1,27 @@
+<fieldset>
+  {% if options %}
+    <legend class=" control-label valtype" for="{{ name }}" data-valtype="label">{% include elements/label.html %}</legend>
+  {% endif %}
+
+  <div class="field-container valtype" data-valtype="checkboxes">
+    {% if options %}
+      {% for option in options %}
+        <label class="checkbox">
+          <input type="checkbox" value="{{ option.label  }}" name="{{ name }}"
+          {% if option.checked %}checked="checked"{% endif %}
+          {% if option.shows %} data-shows="{{ option.shows }}"{% endif %}
+          {% if option.hides %} data-hides="{{ option.hides }}"{% endif %}
+          >
+          <span>{{ option.label | markdownify | remove: '<p>' | remove: '</p>' | improve}}</span>
+        </label>
+      {% endfor %}
+    {% else %}
+      <label class="checkbox">
+        <input type="checkbox" value="{{ label  }}" name="{{ name }}" {% if checked %}checked="checked"{% endif %}>
+        <span>{{ label | markdownify | remove: '<p>' | remove: '</p>' | improve}}</span>
+      </label>
+    {% endif %}
+
+    {% include elements/helptext.html %}
+  </div>
+</fieldset>

data/_includes/fields/email.html

@@ -0,0 +1,12 @@
+<label class="control-label valtype" for="{{ name}}" data-valtype="label">{% include elements/label.html %}</label>
+<div class="field-container">
+  <input type="email" id="{{ name }}" placeholder="" class="form-control input-md valtype" data-valtype="placeholder"
+  {% unless optional %} required="required"{% endunless %}
+  {% if error %}
+    data-error="{{ error }}"
+  {% else %}
+    data-error="You need to enter a valid email address."
+  {% endif %}
+  >
+  {% include elements/helptext.html %}
+</div>

data/_includes/fields/file.html

@@ -0,0 +1,14 @@
+<div class="field-container">
+  <label class="control-label valtype" for="{{ name }}" data-valtype="label">
+    <span class="label">
+      {% include elements/label.html %}
+    </span>
+  <input class="input-file" id="{{ name }}" type="file"
+  {% unless optional %} required="required"{% endunless %}
+  {% if error %} data-error="{{ error }}"
+  {% else %} data-error="You need to upload a file."{% endif %}>
+  <span class="file-custom" data-filename=""></span>
+  </label>
+
+  {% include elements/helptext.html %}
+</div>

data/_includes/fields/group.html

@@ -0,0 +1,3 @@
+<div data-group="{{ group }}">
+  {% include render_field.html %}
+</div>

data/_includes/fields/header.html

@@ -0,0 +1,3 @@
+<h{{ level | default: "2"}}>
+  {{ label | markdownify | remove: '<p>' | remove: '</p>' }}
+</h{{ level | default: "2"}}>

data/_includes/fields/link.html

@@ -0,0 +1,6 @@
+<div class="field-link">
+  {% if description %}
+    <p>{{ description }}</p>
+  {% endif %}
+  <a href="{{ url }}" target="_blank">{{ label | improve}}</a>
+</div>

data/_includes/fields/number.html

@@ -0,0 +1,20 @@
+<label class="control-label valtype" for="{{ name }}" data-valtype="label">
+  {% include elements/label.html %}
+</label>
+<div class="field-container">
+  <input type="text"
+     id="{{ name }}"
+     placeholder=""
+     class="form-control input-md valtype
+     length-{{maxlength | default: '5' }}"
+     data-valtype="placeholder"
+     {% unless optional %} required="required"{% endunless %}
+     {% if "if" %} data-if="{{ if }}"{% endif %}
+     {% if shows %} data-shows="{{ shows }}"{% endif %}
+     {% if error %} data-error="{{ error }}"{% endif %}
+     {% if maxlength %} maxlength="{{maxlength | default: '5'}}"{% endif %}
+     >
+     <span class="units">{{ unit }}</span>
+
+  {% include elements/helptext.html %}
+</div>

data/_includes/fields/paragraph.html

@@ -0,0 +1 @@
+{{ label | markdownify | improve }}

data/_includes/fields/phone.html

@@ -0,0 +1,14 @@
+<label class="control-label valtype" for="{{ name }}" data-valtype="label">
+  {% include elements/label.html %}
+</label>
+<div class="field-container">
+  <input type="text" name="{{ name }}" placeholder="" class="form-control input-md valtype length-13" data-valtype="placeholder"
+  {% unless optional %} required="required"{% endunless %}
+  {% if error %}
+    data-error="{{ error }}"
+  {% else %}
+    data-error="You need to enter a valid phone number."
+  {% endif %}>
+
+  {% include elements/helptext.html %}
+</div>

data/_includes/fields/price.html

@@ -0,0 +1,16 @@
+<label class="control-label valtype" for="{{ name }}" data-valtype="label">
+  {% include elements/label.html %}
+</label>
+
+<div class="field-container">
+  <div class="prepended dollar">$</div>
+  <input type="text" name="{{ name }}" placeholder="" class="form-control input-md valtype" data-valtype="placeholder"
+  {% unless optional %} required="required"{% endunless %}
+  {% if error %}
+    data-error="{{ error }}"
+  {% else %}
+    data-error="You need to enter a valid price."
+  {% endif %}>
+
+  {% include elements/helptext.html %}
+</div>

data/_includes/fields/radio.html

@@ -0,0 +1,34 @@
+<fieldset>
+  <legend class=" control-label valtype" for="{{ name }}" data-valtype="label">
+    {% include elements/label.html %}
+  </legend>
+  <div class="field-container valtype" data-valtype="radios">
+    {% for option in options %}
+      <label class="radio">
+        <input type="radio" value="{{ option.label  }}" name="{{ name }}"
+        {% if option.checked %} checked="checked"{% endif %}
+        {% if option.shows %} data-shows="{{ option.shows }}"{% endif %}
+        {% if option.hides %} data-hides="{{ option.hides }}"{% endif %}
+        {% unless optional %} required="required"{% endunless %}
+        {% if error %}
+          data-error="{{ error }}"
+        {% else %}
+          data-error="You must select an option."
+        {% endif %}>
+        <span>{{ option.label | markdownify | remove: '<p>' | remove: '</p>' | improve }}</span>
+      </label>
+    {% endfor %}
+    {% if other %}
+      <label class="other-label radio">
+        <input type="radio" value="Other" name="{{ name }}">
+        <span>Other</span>
+      </label>
+      <div class="other-input">
+        <label for="{{ name }}-other">Write more information here</label>
+        <input type="text">
+      </div>
+    {% endif %}
+
+    {% include elements/helptext.html %}
+  </div>
+</fieldset>

data/_includes/fields/select.html

@@ -0,0 +1,15 @@
+<label class="control-label valtype" for="{{ name }}" data-valtype="label">
+  {% include elements/label.html %}
+</label>
+<div class="field-container">
+  <select class="form-control input-md valtype" data-valtype="option" name="{{ name }}"
+  {% unless optional %} required="required"{% endunless %}
+  {% if error %} data-error="{{ error }}" {% endif %}>
+  {{ options }}
+  {% for option in options %}
+    <option value="{{ option.label }}">{{ option.label }}</option>
+  {% endfor %}
+  </select>
+
+  {% include elements/helptext.html %}
+</div>

data/_includes/fields/text.html

@@ -0,0 +1,18 @@
+<label class="control-label valtype" for="{{ name }}" data-valtype="label">
+  {% include elements/label.html %}
+</label>
+<div class="field-container">
+  <input type="text"
+     id="{{ name }}"
+     placeholder=""
+     class="form-control input-md valtype
+     {% if maxlength %} length-{{ maxlength }}{% endif %}"
+     data-valtype="placeholder"
+     {% unless optional %} required="required"{% endunless %}
+     {% if "if" %} data-if="{{ if }}"{% endif %}
+     {% if shows %} data-shows="{{ shows }}"{% endif %}
+     {% if error %} data-error="{{ error }}"{% endif %}
+     {% if maxlength %} maxlength="{{ maxlength }}"{% endif %}
+     >
+  {% include elements/helptext.html %}
+</div>

data/_includes/fields/textarea.html

@@ -0,0 +1,12 @@
+<label class="control-label valtype" for="{{ name }}" data-valtype="label">
+  {% include elements/label.html %}
+</label>
+<div class="field-container">
+  <div class="textarea">
+    <textarea class="form-control valtype textarea-{{ size | default: 'small' }}" data-valtype="textarea" name="{{ name }}"
+    {% unless optional %} required="required"{% endunless %}
+    {% if error %} data-error="{{ error }}"{% endif %} /> </textarea>
+
+    {% include elements/helptext.html %}
+  </div>
+</div>

data/_includes/pagination.html

@@ -0,0 +1,14 @@
+{% if forloop.length > 1 %}
+  <div class="form-group pagination">
+    {% if forloop.first %}
+      <a href="javascript:void(0);" class="btn btn-lg form-section-next">Start</a>
+    {% else %}
+      <a href="javascript:void(0);" class="btn btn-lg form-section-prev">Previous</a>
+      {% if forloop.last %}
+        <a href="javascript:void(0);" id="submit" class="btn btn-lg submit">Submit</a>
+      {% else %}
+        <a href="javascript:void(0);" class="btn btn-lg form-section-next">Next</a>
+      {% endif %}
+    {% endif %}
+  </div>
+{% endif %}

data/_includes/render_field.html

@@ -0,0 +1,55 @@
+{% for field in fields %}
+  {% comment %}
+    Assign variables
+  {% endcomment %}
+
+  {% if field.address-fields %}
+    {% assign address-fields = field.address-fields %}
+  {% else %}
+    {% assign address-fields = 'full' %}
+  {% endif %}
+
+  {% assign description = field.description %}
+  {% assign error = field.error %}
+  {% assign fields = field.fields %}
+  {% assign group = field.group %}
+  {% assign helptext = field.helptext %}
+  {% assign if = field.if %}
+  {% assign label = field.label %}
+  {% assign level = field.level %}
+  {% assign maxlength = field.maxlength %}
+  {% capture name %}{{ label | slugify }}-field-{{ forloop.index }}{% endcapture %}
+  {% assign optional = field.optional %}
+  {% assign options = field.options %}
+  {% assign other = field.other %}
+  {% assign shows = field.shows %}
+  {% assign size = field.size %}
+  {% assign unit = field.unit %}
+  {% assign url = field.url %}
+
+  {% comment %}
+    Render each field
+  {% endcomment %}
+
+  {% capture includepath %}fields/{{field.type}}.html{% endcapture %}
+
+  {% if field.group %}
+    {% include fields/group.html %}
+  {% elsif field.type == 'header' %}
+    {% include {{ includepath }} %}
+  {% elsif field.type == 'paragraph' %}
+    {% include {{ includepath }} %}
+  {% elsif field.type == 'link' %}
+    {% include {{ includepath }} %}
+  {% else %}
+    <div class="form-group field-{{ field.type }}">
+      {% if field.type %}
+        {% include {{ includepath }} %}
+      {% else %}
+        {% include fields/text.html %}
+      {% endif %}
+      <p class="help-block with-errors"></p>
+    </div>
+  {% endif %}
+
+{% endfor %}

data/_includes/render_form.html

@@ -0,0 +1,34 @@
+{% capture currentform %}{{ include.form }}{% endcapture %}
+
+{% for page in site.data[currentform] %}
+
+  {% assign fields = page.fields %}
+  {% assign label = page.title %}
+
+  <div class="form-section"{% if page.group %} data-group="{{ page.group }}"{% endif %}>
+
+    {% comment %} Page headers {% endcomment %}
+    <header class="hero-banner default">
+      <h1>
+        {{ label | markdownify | remove: '<p>' | remove: '</p>' }}
+      </h1>
+      {% if page.description %}
+        {{ page.description | markdownify | improve }}
+      {% endif %}
+    </header>
+
+    <div class="form-content">
+      <div class="form-content-inner">
+
+        <div class="nav-on-top">
+          {% include pagination.html %}
+        </div>
+        {% comment %} Render fields in the page {% endcomment %}
+        {% include render_field.html %}
+
+        {% include pagination.html %}
+      </div>
+    </div>
+
+  </div>
+{% endfor %}