what forms could look like in halo

an_example.md

example: http://halform.herokuapp.com/

description.txt

# Form Properties
title
description
target
method
headers
fields
fielsets ??
 
# Shared Field Properties
type
validators
title
help
 
# Field Types
Text
Number
Password
TextArea
Checkbox
Checkboxes
Hidden
Select
Radio
Date
DateTime
List
Object
 
# Field Validators
required
email
url
match
regexp

example.halo.json

{
  "_links": { "self": { "href": "/users" } },
  "_forms": {
    "create-user": {
      "title": "Create a new widget",
      "description": "Enter your widget info and submit to create a new widget",
      "target": "/widgets/{id}",
      "method": "PUT",
      "headers": {
        "Content-Type": "application/json"
      },
      "fields": {
        "name": { "type": "Text", "validators": [ "required" ] },
        "email": { "type": "Text", "validators": [ "required", "email" ] },
        "age": { "type": "Number" },
        "homepage": { "type": "Text", "dataType": "url", "validators": [ "url" ] },
        "password": { "type": "Password" },
        "likes": { "type": "Checkboxes", "options": [ "Computers", "Combat", "Cats" ] },
        "ninja": { "type": "Hidden", "value": "This is a hidden field" },
        "size": { "type": "Select", "options": [ "large", "small" ] },
        "has_answer": { "type": "Radio", "options": [ "yes", "no", "wtf" ] },
        "dob": { "type": "Date" },
        "favourite_datetime": { "type": "DateTime" },
        "things_to_do_before_death": { "type": "List" }
      }
    }
  }
}

Thanks for pointing me towards this @fosdev. Liking the look of it! Some thoughts, mainly on the previous comments...

The reason you might want validators as objects is they may need to be parameterized, e.g. you may want to limit a number to a range. Probably worth cribbing off the HTML5 form validation stuff for this.

Like the edit link relation idea.

Agree with @xaethos on staying clear of presentational types like checkbox and towards the underlying semantic types like boolean.

You might want to make the list of options able to be a link, which would be another way of dealing with very long option lists; I've seen lists in the thousands too. This would also allow caching of the options separately from the form (and with different conditions).

Not entirely sold on recursive form embedding at this point.

Anyway, like I said, looking cool, thanks!

I understand that maybe @mikekelly wants to transparently load this JSON from a client-side JavaScript client and represent elements on screen, so that's why he set Checkbox at the form representation. I like that, but I agree that Checkbox does not reflects the object on the api.

Maybe we can have a separated option for "interface suggestions"?

"likes": {
  "type": "array<string>",
  "options": [ "cats", "dogs", "apples", "oranges" ],
  "multiple": true,
  "interface": "input[type=checkbox]"
},
"countries": {
  "type": "array<string>",
  "options": [ "United States of America", "Brazil", "Italy" ],
  "multiple": true,
  "interface": "select"
},
"under_age_13": {
  "type": "boolean",
  "default": true,
  "interface": "select"
}

This can be entirely optional and simply ignored on backend integration (let's say an API to API integration), but is really relevant when you want to dynamically load a resource and represent it on screen.

Not sure if "interface" is the best name -- maybe "suggested_representation"?

@mikekelly Presume you are aware of this: http://tools.ietf.org/html/rfc6861. I think it would be useful to consider accommodating this so that one could actually externally define the form and thus look it up as you are working on controls for HALO. Given there is a spec and per my earlier comment on keeping things DRY, this would be a nice option to be able to use as well as whatever the full convention ends up being.