Document how the form parser works

[aeneasr]

The registration form parser supports:

• numbers (float64)
• boolean
• string

It also supports json paths for traits in the form of traits[foo.bar.baz] using sjson.

Examples

• Include examples from sjson docs or build our own

Limitations

Nested Items

The way json schema works is that required propagates to deeper levels. If key baz of foo.bar.baz is always required, foo and bar must also be required.

When using form fields, this is very challenging to automate for us at the moment (explain here that go json schema is limited). Basically, the form payload would need to send {foo:{bar:{}}}, otherwise the only error you will see is that foo is required, which can then not be properly assigned to the actual <input name="traits[foo.bar.baz]"> because the keys do not match.

Workaround:

How To: Nested elements

Assuming a traits model:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "object",
      "properties": {
        "first": {
          "type": "string"
        },
        "last": {
          "type": "string"
        }
      }
    }
  }
}

You could address name.first this with a form name of:

<input type=checkbox" value="true" name="traits[path.to.my.boolean]"

• Document limitations, see Support object stubs in form payloads #45

How To: Checkbox to boolean:

If it's not checked:

<input type=checkbox" value="true" name="traits[path.to.my.boolean]" />

If the checkbox is checked:

<input type=checkbox" value="true" name="traits[path.to.my.boolean]" checked />

If the checkbox should be toggled based on the form value (e.g. when form validation fails):

<input type=checkbox" value="true" name="traits[path.to.my.boolean]" checked={{ this.value===true }} />

How To: Array elements

• Todo: Add array element docs

[aeneasr]

The new form parser no longer uses traits[path.to.my.boolean] but instead traits.path.to.my.boolean

[aeneasr]

done