hcard-input-brainstorming

This page is for documenting previous efforts at formats for web forms that input contact information (people or organizations/venues) towards brainstorming the use of hCard for input into forms for enabling hCard forms auto-fill and hCard copy + paste.

This article is a stub. You can help the microformats.org wiki by expanding it.

proposals

hCard properties on form elements

Use hCard properties as class names on form elements inside a container (such as a containing <fieldset> or the containing <form>) to indicate that those form elements accept values with the semantics of the respective hCard properties.

Example:

• how to markup a containing <form>, <fieldset>, or <div> element with the root class name vcard.
• how to markup <input type="text" > elements with hCard property names

Details:

• how to markup <select> elements (e.g. for state/region and country name, many examples)
• how to markup compound input fields, e.g. City, State Zip all in one field (per Yelp add business example)

Design goals for “input microformats”

Use the current microformat authoring conventions and schemas where possible. This goal should be understood in the light that most microformats are designed as hierarchical structures and whereas forms are not. Some breaking changes maybe required to deal with this fundamental difference, but these should be kept to a minimum.

Where possible any differences in authoring should be dealt with by creating a common superset of additional classes for auto-filling applications. This approach will limit the cognitive load on authors and allow the reuse of current parsers.

A primary design goal must be the consideration of i18n. This most effects dates and durations. The individual implementations may allow for language specific formatting, but it should not be part of this specification.

It should be reasonably easy for an author to add classes to a pre-existing form without having to change its data structure.

Auto-fill application vs generalist parsing documentation

Auto-filling a form and parsing its contents are two different operations, although they share the same conventions and schemeas. The discussion on how a microformat parser should extract values from form elements can be different to the needs of an application that can auto-fill a form using microformat data.

The input classname

To aid discovery and differentiate the use of microformats for the use of auto-fill applications we should use an input classname in conjunction with the root microformats classname. The current suggestion of appending the root classname with input ie vcard-input would break all current parsers. To add the demarcation we should use a new class input

Proposed markup:

<form class="vcard input">
<label for="name">title</label>
<input class="fn" id="name" type="text" />
<form>

This would allow authors and applications to determine the intended use case i.e. the microformat mark-up is for form auto-fill. It would also be a simple task to update the current generalist parsers to ignore the mark-up if they were looking for content only. By default, most of the current parsers would already ignore an empty form marked-up with microformats as the required properties such as fn in hCard would be blank.

Form fields should use the classname attribute

It is tempting to consider using the form field name attribute as an alternative to the classname attribute, but this would break the current authoring conventions and all current parsers. We should confine the definitions of microformat to classname and rel attributes.

Proposed markup:

<input class="fn" id="name" type="text" />

• Monday 12 April - Brighton meet-up There was full agreement for the use of the className attribute instead of the form field name attribute. The name attribute can only take a single value and does not give enough flexibility to the author of a form as the name maybe dictated by the server side code.
  • +1 Glenn Jones

Text inputs and textareas

The mapping of content into text inputs and textareas is relatively straightforward, matches are made on the classname attribute and the whole value is used to fill in the form field.

Proposed markup:

<input class="fn" id="name" type="text" />
<textarea class="note" name="bio" cols="20" rows="2"></textarea>

Multiple form fields for plural microformat properties

Where a microformat property such as street-address in hCard can contain an array of values, these values will be added in order into the collection of form fields with the same classname.

Proposed markup:

<input class="street-address" name="address1" type="text" />
<input class="street-address" name="address2" type="text" />
<input class="street-address" name="address3" type="text" />

Selects

Values can be passed into selects where a match can be found against the content or value of an option. The example below shows how a select could be used to define the type of a tel. The auto-fill application should check the content of the option first then its value attribute. Where a property such as a tel type is plural and the select element has the multiple attribute an auto-fill application should set multiple values in the select.

Proposed markup:

<div class="tel">
   <input class="value" name="telephone-number" type="text" />
   <select class="type" name="telephone-type" multiple="multiple">
      <option value="none">Select phone type</option>
      <option value="home">Home</option>
      <option value="work">Work</option>
      <option value="pref">Pref</option>
      <option value="fax">Fax</option>
      <option value="cell">Mobile</option>
      <option value="cell">Pager</option>
   </select>
</div>

Checkbox inputs

Checkbox inputs can be used much like a multiple select. The values have to match the controlled vocabulary of the microfomat property being targeted.

Proposed markup:

<div class="tel">
   <input class="value" type="text" />
   <input class="type" name="type" value="home" type="checkbox" />Home
   <input class="type" name="type" value="work" type="checkbox" />Work
etc…
</div>

Radio inputs

Radio inputs can be used to force a single selection from a controlled vocabulary. There are very few single value controlled vocabularies in the microformats schemas, but rating in hReview would be a good example.

Proposed markup:

<input class="rating" name="rating" value="5" type="radio" />5
<input class="rating" name="rating" value="4" type="radio" />4
<input class="rating" name="rating" value="3" type="radio" />3
etc…  

Hidden input fields

In general, the use of hidden fields should be discouraged, but they are use useful for the post processing of language specific formatting. A good example of this would be hResumes use of duration to define how long someone has had a job. This is most often done with month/year drop down selects as on linkedin.com.

Proposed markup:

<select id="month-started">
   <option value="1">January</option>
   …
</select><br />
<input id="year-started" type="text" />
<input class="duration" type="hidden" onchange="someCustomFormatting()" />

In the example above the duration value is correctly passing into a hidden input which will be submitted with the form allowing the page author to build custom i18n formatting through JavaScript. The alternative would be to display an ISO duration such as “P3Y4M”. This type of interaction design could be achieved using JavaScript hijacking techniques to aid clients that do not support scripts.

HTML5 input types

Although HTML5 has new semantic input types such as search and url their primary purpose is to describe data types rather than the context of data use. We may know that the input in the example below is a date, but we only know that it is a start date of an event by the use of the classname attribute dtstart.

Proposed markup:

<div class="vevent">
<input class="dtstart" type="datetime" />

For clarity and consistency in authoring rules, an auto-fill application should not try and imply context from the input type. All the non date and number based input types search, email, url and tel should be treated as if they were a simple text input.

The color input is not supported as it is not yet used as a data type in the current or proposed schemas

DateTime, Number and Range input types

The new HTML5 DateTime input types still do not give the data context, but they do inform us of specific formatting requirements. Where possible the auto-fill application should format the DateTime value as per the type. If the passed data does not contain the DateTime fragment required for the specific format the input should be left blank.

Proposed markup:

<input class="dtstart" type="date" /> 1996-12-19
<input class="dtstart" type="month" /> 1996-12
<input class="dtstart" type="time" /> 17:39:57
<input class="dtstart" type="datetime" /> 1996-12-19T16:39:57-08:00
<input class="dtstart" type="datetime-local" /> 1996-12-19T16:39:57

The number and range inputs need to be type checked before data is past into the form fields. No invalid dates or numbers should be passed into the form fields.

Min and Max checking on form fields If a min or max attribute exists for a number or datetime input the value being passed needs to be checked to make sure it is in range before the input is updated.

Repeating microformat properties

There are a number of plural properties in mircoformats that allow multiple values. In hCard the commonly used ones are tel, email and urls. To allow a form to extend to receive an unknown number of values auto-fill applications need to support a repeating pattern. This can be achieved with a new classname “repeat” which can be used in conjunction with a microformat property. The author needs to add an instructional classname to inform the application when to perform a repeat.

Proposed markup:

<div class="tel repeat">
   <label for="tel">telephone</label>
   <input class="value" name="tel" type="text" />
</div&gt

An auto-fill application working in a browser would duplicate the whole DOM node and append it as a sibling. All element ids and form field names would be appended with an index number to keep the HTML valid. The label for attribute would also be updated to any changed id reference.

• Monday 12 April - Brighton meet-up

This was generally agreed between everyone except Tantek. There are a large number of use cases where we find repeating patterns. These patterns allow a user to add multiples of one item. The most common example in hCard is the URL property. We discussed the use of a “repeatable” class that would cause an auto-fill application to duplicate the whole DOM node and append it as a sibling underneath the original.

The word “repeatable” was preferred over “repeat”. Although there are use cases to back up this type of functionally Tantek thought it broke the layers of abstraction and we could never be a 100% sure it would not damage the layout designed by the author. Tantek rejected this as a possible solution. No agreement/conclusions were reached about this point.

• • I need to evidence this point and rediscuss it. Tantek concerns are real and need addressing before moving forward with this idea Glenn Jones

Repeating microformat structures within one form

As well as repeating mircoformat properties whole mircoformats could be repeated within one form. Again, ids and form field names would be appended with an index number.

Proposed markup:

<form>
<div class=" vcard repeat">
<label for="name">Name</label>
<input class="fn" name="name" type="text" />
</div>
...
</form>

• Monday 12 April - Brighton meet-up

This item is similar to the previous item and as such everyone took a similar point of view. Jeremy believed that he could see good real world uses for this pattern of mark-up. Again “repeatable” would be a better className. Tantek’s previous objections were carried forward to this pattern.

• • Again, I need to evidence this point and rediscuss it. Glenn Jones

Defining types in the classname attribute

Most forms do not use hierarchical structures and as such the type/value structure used in microformats are less common in forms. Using the classname and type together allows the author to target a specific type/value i.e. a mobile telephone number or preferred email address.

Proposed markup:

<input class="tel cell" name="mobile-number" type="text" />
<input class="tel fax" name="fax-number" type="text" />

• Monday 12 April - Brighton meet-up

There is a problem adding ‘type’ information i.e. home, work and pref to inputs that take telephone numbers or email addresses. There are many use cases where the author wants to define a specific ‘type’ of a property, such as a mobile telephone number, to a single input. To accommodate this we somehow have to add the ‘type’ metadata as well as the property name.

In the current version of microformats, most people at the meeting were happy with the type information being added into the className attribute. For version 2 of microformats, Tantek suggested adding a prefix of ‘l’ standing for label.

<input class="p-tel l-cell" name="mobile-number" type="text" />
<input class="p-tel l-fax" name="fax-number" type="text" />

There was some discussion of using the HTML label element to define the microformat property. But it was dropped as we could not think of an authoring use case and it would add complexity.

• • +1 To follow the most common pattern of form authoring we need to be able to add types into the className attribute of an form field.Glenn Jones

String Concatenation

There are a number of circumstances where concatenating a plural microfromats property into a single string is required. The most common string concatenations involve a combination of spaces and/or comma’s. Auto-fill applications should concatenate three different patterns; comma-space-delimited, comma-delimited and space-delimited. These format operators have to be placed in the same classname attribute as the microformat property name. The concatenated string should be trimmed and there should be no trailing spaces or commas at the end of the string.

Proposed markup:

<input class="category comma-space-delimited" name="tags" type="text" />

• Monday 12 April - Brighton meet-up

There are a number of circumstances where concatenating a plural microfromats property into a single string is required. The best example of this is a number of individual tags into a single string. Jeremy suggested using the multiple attribute or a className multiple. As the multiple attribute can currently only be applied to a file input or a select element we will have to use the word ‘multiple’ in the class attribute. There was some discussion about dropping the formatting instructions.

<input class="category multiple" name="tags" type="text" />

or

<input class="category multiple space-delimited" name="tags" type="text" />

• • +1 I like the idea of breaking this down and using the word multiple.Glenn Jones

Logical operators "or"

There are number of circumstances where an “or” operator would be useful. If a classname attribute with more than one microformat property and the “or “ operator the auto fill application will make a selection between the properties. The first non-null value will be used. Where the microformat property is a multiple value all the values of the first property are used before any subsequent properties.

Proposed markup:

<input class="title role or" name="job-title" type="text" />
<input class="extended-address street-address or" name="address1" type="text" />
<input class="extended-address street-address or" name="address2" type="text" />
<input class="extended-address street-address or" name="address3" type="text" />

• Monday 12 April - Brighton meet-up

There are times where an author may wish to use more than one property if it’s available. If we were to use this pattern the “or” is not required. Tantek pointed out that there is no order to the className attribute and we should not force one artificially to enable this feature.

• • +1 Tantek's point is the death nail for this idea. I think it should now be dropped.Glenn Jones

Additional – Inputs inheriting parent className values

As we talked at the Brighton meet-up, it became apparent that it would be useful for a form element to inherit its parent className value. The form field would have to be the only form field of the parent. This type of structure would be required to ease the authoring of the ‘repeatable pattern’.

The group’s solution:

<p class="tel repeatable">
<label for="telephone">Phone: </label>
<input name="telephone" type="text" />
</p>

<input type="vcard">

Hey, that would be nice: if "vcard" were just an input type in forms. My browser could fill it in with my vCard, or with a vCard read from disk, or with data scraped from an hCard somewhere online. I wonder how doable this is using a JS shim?

see also

• hcard-input
• hcard-input-examples
• hcard-input-formats
• hcard-input-repeatable