Documented custom fields

README.md

@@ -80,7 +80,29 @@ First, you must rename the `settings.example.conf` into `settings.conf`, and edi
     ],
     "formOrigin": "https://example.tld",
     "language": "en",
-    "labels": true
+    "labels": true,
+	"customFields": {
+		"deadline": {
+			"label": "Development deadline",
+			"type": "select",
+			"options": [
+				"A week",
+				"A month",
+				"More than a month"
+			],
+			"required": true
+		},
+		"domain": {
+            "label": "Website domain",
+            "type": "text",
+			"required": false
+        },
+		"budget_max": {
+			"label": "Maximum budget (€)",
+			"type": "number",
+			"required": true
+		}
+	}
 }
 ```
 
@@ -94,10 +116,46 @@ The `language` string tells SMAM in which language you want your form served. Po
 
 Finally, the `labels` setting is a boolean to set whether or not labels will be displayed in the `<form></form>` block. If set to `false`, the form will still display the front-end strings ("Your name", "Your e-mail address"...), but only as placeholders in the text fields. If set to true, the said strings will appear as text fields' placeholders but also as labels outside of the fields. If not set, defaults to `true`.
 
+The `customFields` section is optional and describes custom form fields, which are described below.
+
+## Custom fields
+
+SMAM allows you to add custom fields to your form (in addition to the default ones, which are the sender's name, the sender's e-mail address, the message's subject and the message's content). These fields will be added in your form below the content's field, in a tag defined by the settings file (one of &lt;input&gt;, &lt;select&gt; and &lt;textarea&gt;). We'll see below how to set the field's type.
+
+A custom field is defined in the `customFields` section of your settings file, as described below:
+
+```json
+"field_name": {
+	"label": "My field",
+	"type": "select",
+	"required": true,
+	"options": [
+		"Option 1",
+		"Option 2",
+		"Option 3"
+	]
+}
+```
+
+* **field_name** (required) is an identifier for your field, it will only be used internally by the software.
+* **label** (required) is both the label/placeholder displayed with your field in the form and the label displayed next to the user-input value in the final e-mail.
+* **type** (required) is the type of your field. If you set it to "select", the form field will use a &lt;select&gt; tag (this will require the `options` parameters being set). "textarea" will set the field to use the &lt;textarea&gt; tag. If any other value is set here, it will be placed in the `type` attribute of an &lt;input&gt; tag. Head over [here](https://developer.mozilla.org/fr/docs/Web/HTML/Element/Input#attr-type) for a full list of accepted input types. Please not that the `checkbox` and `radio` types aren't currently supported (but will be in the future). There's no support planned for the `submit` and `reset` types.
+* **required** (optional) is a boolean. Set it to true and the field will be set as required in your form. A modern browser should prevent an user to send the form if a required field isn't filled. On top of that, SMAM's server will check the field marked as required to make sure they've been filled.
+* **options** (optional) is an array of possible values. This is currently useful only if your field is of the "select" type.
+
 ## Templating
 
 Each e-mail sent by the form follows a template described in `template.pug` (it's [Pug](pugjs.org/)). If you want to change the way the e-mails you receive are displayed in your mailbox, just edit it! You don't even need to restart the server aftewards :smile:
 
+The template also features custom fields, iterating over the `custom` object, containing the field's label and user-input value:
+
+```json
+"field_name": {
+	"label": "My field",
+	"value": "Hello"
+}
+```
+
 ## Personnalising
 
 As you might have already seen, the contact form is generated without any form of style except your browser's default one. But that doesn't meen that you have to add an ugly form to your site to receive contact e-mails, as every element has a specific id (beginning with the `form_` prefix), allowing you to use your own style on your contact form.
@@ -127,6 +185,25 @@ The generated form will look like this:
 </div>
 ```
 
+Custom fields will be formatted the same way (and with identifiers following the same guidelines) as default fields. For example, a custom field described as
+
+```json
+"budget": {
+	"label": "Maximum budget allowed",
+	"type": "number",
+	"required": true
+}
+```
+in the settings file will result in
+```html
+<div id="form_budget">
+    <label for="form_budget_input">Maximum budget allowed</label>
+    <input required="required" placeholder="Maximum budget allowed" id="form_budget_input" type="number">
+</div>
+```
+
+Please note that the field's identifier ends with the field's tag name and not its type. For example, our `budget` field above will see its identifier become `form_budget_select` if it has the "select" type, `form_budget_textarea` if it has the "textarea" type, or `form_budget_input` for any other "type" value.
+
 Now it's all yours to make good use of all these identifiers and have a magnificient contact form :wink:
 
 I think that the code in itself is clear enough, if not please tell me so I can detail everything here!