rest/forms-brainstorming: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(→‎Patterns: better)
m (Reverted edits by Shaeha (Talk) to last version by Brian)
 
(32 intermediate revisions by 19 users not shown)
Line 3: Line 3:
This page collects ideas from [[forms-examples]] how to best encode form data into a microformat
This page collects ideas from [[forms-examples]] how to best encode form data into a microformat


DETH = Dictionaries Encoding/Transmitting HTML
== Proposal A: DETH - Dictionaries Encoding/Transmitting HTML ==


== Rules (Strawman) ==
=== Rules (Strawman) ===


# Only use [http://www.w3.org/TR/xhtml-modularization/abstract_modules.html#s_sformsmodule XHTML Basic Forms] Module
# Only use [http://www.w3.org/TR/xhtml-modularization/abstract_modules.html#s_sformsmodule XHTML Basic Forms] Module
Line 11: Line 11:
# Recommend: use a ''label'' with every ''input''
# Recommend: use a ''label'' with every ''input''
# Make the ''for'' of the ''label'' match the ''id'' of ''input''
# Make the ''for'' of the ''label'' match the ''id'' of ''input''
# Optionally, group ''label'' with ''input'' using ''<tr>'' or ''&lt;li>''
# Group ''label'' with ''input'' using ''<dl><dt><dd>''
##If ''&lt;li>'', group ''input'' inside ''label''
##If ''<tr>'', place ''label'' in first ''<td>'', and ''input'' in second.
# Always place ''submit'' and ''reset'' outside grouping
# Always place ''submit'' and ''reset'' outside grouping


== Patterns ==
=== Questions for further research ===


=== Anchor Design Pattern ===
# How to specify whether a field is optional or required?
 
## Suggestion: the label contains a * ?
 
=== Patterns ===
 
==== Anchor Design Pattern ====


  &lt;a class="deth" href="http//somesite.com/prog/adduser">label&lt;/a>
  &lt;a class="deth" href="http//somesite.com/prog/adduser">label&lt;/a>


=== Complete Forms Design Pattern ===
==== Forms Design Pattern ====


<form class="deth" action="http://somesite.com/users" method="post">
&lt;form class="deth" action="http://somesite.com/users" method="post">
&lt;ol>
  &lt;dl>
&lt;li>
  &lt;dt>&lt;label for="firstname">First name:&lt;/label>&lt;/dt>
<label for="firstname">First name:</label><input type="text" id="firstname" />
  &lt;dd>&lt;input type="text" id="firstname" />
  &lt;/li><li>
  &lt;/dd>&lt;dt>
<label for="lastname">Last name:</label><input type="text" id="lastname" />
    &lt;label for="lastname">Last name:&lt;/label>&lt;/dt>
  &lt;/li><li>
  &lt;dd>&lt;input type="text" id="lastname" />
   <input type="radio" name="sex" value="male">Male</input>
  &lt;/dd>&lt;dt>Sex&lt;/dt>
   <input type="radio" name="sex" value="female">Female</input>
   &lt;dd>&lt;input type="radio" name="sex" value="male">Male&lt;/input>
  &lt;/li><li>
   &lt;input type="radio" name="sex" value="female">Female&lt;/input>
   <input type="checkbox" name="travel" value="car">Car</input>
  &lt;/dd>&lt;dt>Travel&lt;/dt>
   <input type="checkbox" name="travel" value="bike">Bicycle</input>
   &lt;dd>  &lt;input type="checkbox" name="travel" value="car">Car&lt;/input>
  &lt;/li><li>
   &lt;input type="checkbox" name="travel" value="bike">Bicycle&lt;/input>
<label for="age">Age:
  &lt;/dd>&lt;dt>
<select>
  &lt;label for="age">Age:&lt;/dt>
     <option val=0>< 18</option>
  &lt;dd>
     <option val=18>18-64</option>
  &lt;select>
     <option val=65>65+</option>
     &lt;option val=0>&lt; 18&lt;/option>
     &lt;option val=18>18-64&lt;/option>
     &lt;option val=65>65+&lt;/option>
  &lt;/select>
  &lt;/select>
  &lt;/li><li>
  &lt;/dd>&lt;dt>
<label for="description">Description:</label>
  &lt;label for="description">Description:&lt;/label>&lt;/dt>
<textarea id="description">Default text</textarea>
  &lt;dd>&lt;textarea id="description">Default text&lt;/textarea>
  &lt;/li>
  &lt;/dd>
  &lt;/ol>
  &lt;/dl>
  &lt;input type="submit" value="Send" />
  &lt;input type="submit" value="Send" />
  &lt;input type="reset" />
  &lt;input type="reset" />
  &lt;/form>
  &lt;/form>
&lt;/body>
&lt;/html>


== Sample Python Binding ==


=== Table Design Pattern ===
order=[
  "firstname","lastname","sex",'"travel", "age","description"
]
dict={
  "@@tag":"form",
    "@action":"http://somesite.com/users/",
    "@class":"deth",
    "@enctype":"application/x-www-form-urlencoded",
    "@method":"post",
  "@@order":order,
  "firstname":"First name:",
  "lastname":"Last name:",
  "sex":{"@type":"radio", "male":"Male", "female":"Female"},
  "travel":{"@type":"checkbox", "car":"Car", "bike":"Bicycle"},
  "age":{"@@body":"Age:", "@type":"select",
        "0":"< 18", "18":"18-64", "65":"65+"
  },
  "description":{
    "@@body":"Description:",
    "@type":"textarea",
    "@value":"Default text"
  }
}


&lt;form class="deth" action="http//somesite.com/users" method="post">
== Proposal B: REST-oriented process ==
&lt;table class="form">
From [Kyle Cordes], for the discovery of the parameters:
&lt;tr>
 
  &lt;td>&lt;label for="firstname">First name&lt;/label>&lt;/td>
* You discover the URL of a service by some means.
  &lt;td>&lt;input type="text" id="firstname" />&lt;/td>
* You GET that URL, which returns an HTML form.
&lt;/tr>&lt;tr>
* The HTML form describes where to POST to invoke that service, and what
  &lt;td>&lt;label for="lastname">Last name&lt;/label>&lt;/td>
parameters can be passed in that POST. In some cases, it will use
  &lt;td>&lt;input type="text" id="lastname" />&lt;/td>
<selects>s to describe what options are valid for a parameter.
  &lt;/tr>&lt;tr>
* In most cases, the form will be interspersed with human readable text,
  &lt;td>&lt;label for="email">Email&lt;/label>&lt;/td>
to explain the meaning of the parameters (a machine-understandable way
  &lt;td>&lt;input type="text" id="email" />&lt;/td>
to explain parameter meaning, sounds like an AI problem...)
&lt;/tr>&lt;tr>
* You (the user of a web browser, or a piece of software
  &lt;td>&lt;label for="sex">Sex&lt;/label>&lt;/td>
programmatically using the server) populate the parameters and POST them
  &lt;td>
to the URL you discovered via the form.
    &lt;input type="radio" name="sex" value="Male">Male &lt;/input>
* You get back a response, which might be an error message about a
    &lt;input type="radio" name="sex" value="Female">Female &lt;/input>
parameter problem, or might be a respresentation of the "answer".
  &lt;/td>
 
&lt;/tr>&lt;tr>
[OlaBerg] says: This is exactly what I do, and it works great! In fact, I
  &lt;td>&lt;label for="travel">Travel&lt;/label>&lt;/td>
use it both for POST-API and GET-API. A set of forms defines a REST-ful
  &lt;td>
API.
    &lt;input type="checkbox" name="travel" value="car">Car&lt;/input>
    &lt;input type="checkbox" name="travel" value="bike">Bicycle&lt;/input>
  &lt;/td>
&lt;/tr>&lt;tr>
  &lt;td>&lt;label for="age">Age&lt;/label>&lt;/td>
  &lt;td>&lt;select>
    &lt;option val=0>&lt; 18 &lt;/option>
    &lt;option val=18>18-64 &lt;/option>
    &lt;option val=65>65+ &lt;/option>
  &lt;/td>&lt;/select>
&lt;/tr>
&lt;/table>
&lt;input type="submit" value="Send" />
&lt;input type="reset" />
&lt;/form>


=== List Design Pattern ===
== See Also ==


&lt;form class="deth" action="http//somesite.com/users" method="post">
* [http://www.opendarwin.org/~drernie/rest-api.html REST self-describing API proposal]
&lt;ol>
* [http://opensearch.a9.com/ OpenSearch search results standard (REST-like)]
&lt;li>
* [[rest-brainstorming]]
  &lt;label for="firstname">First name&lt;input type="text" id="firstname" />&lt;/label>
&lt;/li>&lt;li>
  &lt;label for="lastname">Last name&lt;input type="text" id="lastname" />&lt;/label>
&lt;/li>&lt;li>
  &lt;label for="email">Email&lt;input type="text" id="email" />&lt;/label>
&lt;/li>&lt;li>
  &lt;label for="sex">Sex 
    &lt;input type="radio" name="sex" value="Male">Male &lt;/input>
    &lt;input type="radio" name="sex" value="Female">Female &lt;/input>
  &lt;/label>
&lt;/li>&lt;li>
  &lt;label for="travel">Travel 
    &lt;input type="checkbox" name="travel" value="car">Car&lt;/input>
    &lt;input type="checkbox" name="travel" value="bike">Bicycle&lt;/input>
  &lt;/label>
&lt;/li>&lt;li>
  &lt;label for="age">Age
  &lt;select>
    &lt;option val=0>&lt; 18 &lt;/option>
    &lt;option val=18>18-64 &lt;/option>
    &lt;option val=65>65+ &lt;/option>
  &lt;/select>
&lt;/label>
&lt;/li>
&lt;/ol>
&lt;input type="submit" value="Send" />
&lt;input type="reset" />
&lt;/form>

Latest revision as of 16:11, 16 September 2010

Forms Brainstorming

This page collects ideas from forms-examples how to best encode form data into a microformat

Proposal A: DETH - Dictionaries Encoding/Transmitting HTML

Rules (Strawman)

  1. Only use XHTML Basic Forms Module
  2. Must use action with appropriate URI (no scripts)
  3. Recommend: use a label with every input
  4. Make the for of the label match the id of input
  5. Group label with input using
  6. Always place submit and reset outside grouping

Questions for further research

  1. How to specify whether a field is optional or required?
    1. Suggestion: the label contains a * ?

Patterns

Anchor Design Pattern

<a class="deth" href="http//somesite.com/prog/adduser">label</a>

Forms Design Pattern

<form class="deth" action="http://somesite.com/users" method="post">
 <dl>
 <dt><label for="firstname">First name:</label></dt>
  <dd><input type="text" id="firstname" />
</dd><dt>
   <label for="lastname">Last name:</label></dt>
  <dd><input type="text" id="lastname" />
</dd><dt>Sex</dt>
  <dd><input type="radio" name="sex" value="male">Male</input>
  <input type="radio" name="sex" value="female">Female</input>
</dd><dt>Travel</dt>
  <dd>  <input type="checkbox" name="travel" value="car">Car</input>
  <input type="checkbox" name="travel" value="bike">Bicycle</input>
</dd><dt>
 <label for="age">Age:</dt>
  <dd>
 <select>
   <option val=0>< 18</option>
   <option val=18>18-64</option>
   <option val=65>65+</option>
</select>
</dd><dt>
 <label for="description">Description:</label></dt>
  <dd><textarea id="description">Default text</textarea>
</dd>
</dl>
<input type="submit" value="Send" />
<input type="reset" />
</form>

Sample Python Binding

order=[
 "firstname","lastname","sex",'"travel", "age","description"
]
dict={
 "@@tag":"form",
   "@action":"http://somesite.com/users/",
   "@class":"deth",
   "@enctype":"application/x-www-form-urlencoded",
   "@method":"post",
 "@@order":order,
 "firstname":"First name:",
 "lastname":"Last name:",
 "sex":{"@type":"radio", "male":"Male", "female":"Female"},
 "travel":{"@type":"checkbox", "car":"Car", "bike":"Bicycle"},
 "age":{"@@body":"Age:", "@type":"select",
        "0":"< 18", "18":"18-64", "65":"65+"
  },
 "description":{
   "@@body":"Description:",
   "@type":"textarea",
   "@value":"Default text"
  }
}

Proposal B: REST-oriented process

From [Kyle Cordes], for the discovery of the parameters:

  • You discover the URL of a service by some means.
  • You GET that URL, which returns an HTML form.
  • The HTML form describes where to POST to invoke that service, and what

parameters can be passed in that POST. In some cases, it will use <selects>s to describe what options are valid for a parameter.

  • In most cases, the form will be interspersed with human readable text,

to explain the meaning of the parameters (a machine-understandable way to explain parameter meaning, sounds like an AI problem...)

  • You (the user of a web browser, or a piece of software

programmatically using the server) populate the parameters and POST them to the URL you discovered via the form.

  • You get back a response, which might be an error message about a

parameter problem, or might be a respresentation of the "answer".

[OlaBerg] says: This is exactly what I do, and it works great! In fact, I use it both for POST-API and GET-API. A set of forms defines a REST-ful API.

See Also