XForms for HTML Authors(为HTML使用者了解XForms的资料）

以下内容引自：http://www.w3.org/MarkUp/Forms/2003/xforms-for-html-authors.html

XForms for HTML Authors

Version date: 28 October 2003

Introduction

XForms is the new markup language for forms on the Web. This document is a quick introduction to XForms for HTML Forms authors. It shows you how to convert existing forms to their XForms equivalent. It assumes knowledge of HTML Forms, so is not a beginner's tutorial. Although there is mention of additional facilities of XForms beyond those possible in HTML Forms (marked with an asterisk on the headings), it is not a full tutorial on all features of XForms.

Table of Contents

Making the Submitted Values Explicit

Initial Values

Hidden Values

Getting Initial Values From Elsewhere*

'Editing' any XML document*

Submitting

Multiple Submissions*

Submission Methods Life after Submit*

Combining Properties*

More than One Form in a Document

Bind instead of Ref

Features Not Handled Here

*Features not present in HTML Forms

A Simple Search Form

Take this simple HTML form:

<html>

<head><title>Search</title></head>

<body>

<form action="http://example.com/search"

method="get">

Find <input type="text" name="q">

</form>

</body>

</html>

The main difference in XForms is that details of the values collected and how to submit them are gathered in the head, in an element called model; only the form controls are put in the body. So in this case the minimum you need to put in the head is:

<model>

<submission action="http://example.com/search"

method="get"

id="s"/>

</model>

(Elements and attributes in XForms are in lower case.)

The <form> element is now no longer needed; the controls in the body look like this:

What you can hopefully work out from this is that form controls have a <label> element as child, the <input> uses "ref" instead of "name", and there is a separate submit control that links to the details of the submission in the head. So the complete example is:

<h:html xmlns:h="http://www.w3.org/1999/xhtml"

xmlns="http://www.w3.org/2002/xforms">

<h:head>

<h:title>Search</h:title>

<model>

<submission action="http://example.com/search"

method="get" id="s"/>

</model>

</h:head>

<h:body>

<h:p>

</h:p>

</h:body>

</h:html>

Namespace Prefixes

Another obvious difference is the use of h: prefixes on the HTML elements. This has nothing to do with XForms, but with XML which is designed to allow you to combine different languages together. XForms is designed to be combined with different languages, not just XHTML. XML processors need to be told which language different elements belong to, though one language may be the 'default' language. In the above document, XForms has been made the default, though XHTML could have been made the default by changing the xmlns attributes in the head:

<html xmlns="http://www.w3.org/1999/xhtml"

xmlns:f="http://www.w3.org/2002/xforms">

<head>

<title>Search</title>

<f:model>

<f:submission action="http://example.com/search"

method="get" id="s"/>

</f:model>

</head>

<body>

<p>

<f:input ref="q"><f:label>Find</f:label></f:input>

<f:submit submission="s"><f:label>Go</f:label></f:submit>

</p>

</body>

</html>

The choice is yours. You can also choose to make neither the default, and prefix all elements. You can choose any prefix; h: or x: or html: or form:, it's up to you.

In the future, XHTML2 will allow you to write forms without prefixes.

Forms Controls

XForms provides equivalents of all HTML Form controls. But there is a major difference in approach: HTML mainly specifies how the control should look, while XForms specifies what the control should do. So while the HTML specification says that the select element creates a menu, and the radio type of input creates radio buttons that allow a single choice to be made, XForms has the select and select1 elements, which only specify the intent of the controls, to select zero or more, or only one, element from a list. How they are presented to the user can vary across devices, or according to a style sheet. On a mobile telephone where screen space is scarce, both might be represented with menus, while on a larger screen both might be represented with selectable buttons. You are allowed to give a hint to what you want, or you may use a stylesheet to give precise styling, but if you don't, a device, or a style sheet, may make a choice for you.

So here is how you write the equivalent of the HTML Forms controls.

Simple Text InputFirst name: <input type="text" name="firstname">

is written

<input ref="firstname"><label>First name:</label></input>

There is no need to indicate that it is text: in the absence of any other information, by default it is text (called string in XForms).

See later under 'initial values' for how to give any control an initial value.

TextareaMessage: <textarea name="message" rows="20" cols="80"></textarea>

is written

<textarea ref="message"><label>Message:</label></textarea>

Styling, such as the height and width here, is done using a style sheet. For instance, put this in your style sheet

textarea[ref="message"] { font-family: sans-serif;

height: 20em; width: 80em }

Although this mimics the HTML behavior, there is no requirement that you use a sans serif font, nor that you specify the width in rows and columns like this: you could use lengths, or percentages, or whatever:

textarea[ref="message"] { font-family: serif;

height: 2cm; width: 20% }

If you want all your textareas to have the same dimensions, you can use

textarea { font-family: sans-serif;

height: 20em; width: 80em }

The easiest way to include a style sheet in your document is to add this at the beginning of the document:

<?xml version="1.0"?>

<?xml-stylesheet href="style.css" type="text/css"?>

where 'style.css' is the name of your stylesheet.

Radio Buttons

Radio buttons select one value from a number of alternatives:

Gender:

<input type="radio" name="sex" value="M"> Male

<input type="radio" name="sex" value="F"> Female

becomes

<label>Gender:</label>

<item>

</item>

<item>

<label>Female</label><value>F</value>

</item>

</select1>

Bear in mind that this may be presented as any one of radio buttons, a (scrollable) select area, or a menu. You may include a hint appearance="full" on the <select1> to suggest that it should be presented as radio buttons. (Use appearance="compact" to suggest a select area and appearance="minimal" to suggest a menu).

The section on 'initial values' later says how to preselect a value.

Checkboxes

Checkboxes select zero or more from a list.

Flavors:

<input type="checkbox" name="flavors" value="v"> Vanilla

<input type="checkbox" name="flavors" value="s"> Strawberry

<input type="checkbox" name="flavors" value="c"> Chocolate

is written

<label>Flavors:</label>

<item>

<label>Vanilla</label><value>v</value>

</item>

<item>

<label>Strawberry</label><value>s</value>

</item>

<item>

<label>Chocolate</label><value>c</value>

</item>

</select>

The section on 'initial values' says how to pre-check values.

Menus

Depending on the presence of the multiple attribute in HTML, menus select one, or zero or more from a list of options. You either use <select1> to select a single choice, or <select> to select zero or more.

Month:

<option value="Mar">March</option>

<option value="Apr">April</option>

</select>

would be written:

<label>Month:</label>

<item><label>March</label><value>Mar</value></item>

<item><label>April</label><value>Apr</value></item>

</select>

If multiple isn't present on the HTML select, then use select1 instead.

The section on 'initial values' says how to preselect values.

File Select<form method="post" enctype="multipart/form-data" ...>

...

File: <input type="file" name="attachment">

is written

...

PasswordsPassword: <input type="password" name="pw">

is written

<secret ref="pw"><label>Password:</label></secret>

Reset

Ten years of experience with HTML Forms has shown that hardly anyone actually uses reset buttons, and yet very many Web forms include them. A problem is that often the reset button with the text "Reset" is larger than the submission button that is often marked "OK", with the result that people accidently click on reset when they mean to click on OK, sometimes losing a lot of work (few if any browsers offer an undo). Therefore, while it is possible to create a reset button in XForms, it is deliberately harder to do, in order to discourage people unless they really want one:

is therefore written

<label>Clear all fields</label>

</trigger>

Buttons

Buttons have no predefined behavior, but have a behavior attached to them which is triggered when a relevant event occurs.

The button element

can be written

<h:script ev:event="DOMActivate" type="text/javascript">show()</h:script>

</trigger>

</trigger>

where "#show" locates the element (for instance a script element) that implements the behavior:

XForms has a number of built in actions that can be executed by a button; see the reset button above for an example.

The fact that the event attribute has a prefix, means that you have to add the following XML Namespace to the head:

xmlns:ev="http://www.w3.org/2001/xml-events"

Image Buttons<input type="image" src="..." ...>

is written by putting an image into the <label> element:

<trigger...><label><h:img src="..." .../></label></trigger>

or by specifying it in a stylesheet

with a stylesheet rule

trigger#activate {background-image: url(button.png);

background-repeat: none}

(Likewise for <submit>.)

OptgroupDrink:

<option value="h2o">Water</option>

<option value="oj">Juice</option>

</optgroup>

<option value="ww">White Wine</option>

</optgroup>

</select>

is written

<label>Drink:</label>

<label>Soft drinks</label>

<item><label>Water</label><value>h2o</value></item>

<item><label>Juice</label><value>oj</value></item>

</choices>

<item><label>White wine</label><value>ww</value></item>

</choices>

</select1>

Grouping Controls<fieldset>

<legend>Personal Information</legend>

Last Name: <input name="lastname" type="text">

First Name: <input name="firstname" type="text">

Address: <input name="address" type="text">

</fieldset>

is written

<group>

<label>Personal Information</label>

<input ref="firstname"><label>First name:</label></input>

<input ref="address"><label>Address:</label></input>

</group>

Note the consistent use of <label>.

Output Controls*

XForms has two controls that are not in HTML, output and range.

The output control allows you to include values as text in the document.

Your current total is: <output ref="sum"/>

<output ref="sum"><label>Total</label></output>

This can be used to allow the user to preview values being submitted.

You can also calculate values:

Total volume: <output value="height * width * depth"/>

(where height, width and depth are values collected by other controls.)

Range Controls*

This control allows you to specify a constraint on a value.

A user agent may represent this as a slider or similar.

Hidden Controls

As you will see in the next section, there is no need for hidden controls in XForms.

Submitted Values

The attribute named ref on each control actually refers to a child of an instance element in the model, where the values are gathered before submission. If there is no instance element there (as in the search example above), then one is silently created.

Making the Submitted Values Explicit

Although it is perfectly allowable to let the system create your instance for you, there are reasons why it is a good idea to include one anyway, like this for the search example:

<model>

<submission action="http://example.com/search"

method="get" id="s"/>

</model>

From this you immediately see that the only data value submitted is called "q". The most obvious advantage of this is the documentation value of being able to see what is being submitted, but the system will now also check that when you say ref="q" that there really is a q in the instance.

Note that it is essential, for reasons we won't go into detail here, that you put the xmlns="" on your instance data, to tell the processor that the elements here are neither XHTML nor XForms elements.

(Note that we've used the tag <data> here, but you can choose any tag you like.)

Initial Values

For initialising controls including initialising checked boxes, and selected menu items etc., you just supply an instance with pre-filled values. For the search example:

<instance><data xmlns=""><q>Keywords</q></data></instance>

would pre-fill the text control with the word Keywords.

Similarly for the example in the checkboxes section, which looks like this:

<label>Flavors:</label>

<item>

<label>Vanilla</label><value>v</value>

</item>

<item>

<label>Strawberry</label><value>s</value>

</item>

<item>

<label>Chocolate</label><value>c</value>

</item>

</select>

You can preselect the vanilla and strawberry checkboxes like this:

Similarly for the menus example, which looked like this:

<label>Month:</label>

<item><label>March</label><value>Mar</value></item>

<item><label>April</label><value>Apr</value></item>

</select>

You can preselect March and April like this:

And for the optgroup example:

<label>Drink:</label>

<label>Soft drinks</label>

<item><label>Water</label><value>h2o</value></item>

<item><label>Juice</label><value>oj</value></item>

</choices>

<item><label>White wine</label><value>ww</value></item>

</choices>

</select1>

Preselect the value none like this:

Hidden Values

The reason that XForms does not need hidden controls is that any values in the instance that haven't been bound to by a control are by definition not visible to the user. So if we want to add a hidden value results to the search form, we change the instance to:

Getting Initial Values From Elsewhere*

You don't have to specify the initial instance in the document itself, because you can load it from an external resource, like this:

and the document t21.xml can then contain your data, like

(You don't need the xmlns="" in external instances, though it doesn't do any harm either.)

'Editing' any XML document*

Loading external instances gives you immense power. This is because the ref attribute on the forms controls doesn't just let you select an identifier as HTML's name does, but in fact can be any XPath expression. XPath lets you select any element or attribute in an XML document.

This means that once you have learnt XPath, you can bring in any XML document as instance, even an XHTML document, bind controls to it, and submit it. For instance to bind to the <title> element in an XHTML document, you can use

<input ref="h:html/h:head/h:title">...

(i.e. the title element within the head element within the html element, all in the XHTML namespace), or

<input ref="h:html/h:body/@class">...

which is the class attribute on the body element.

For example, suppose a shop has very unpredictable opening hours (perhaps it depends on the weather), and they want to have a Web page that people can go to to see if it is open. Suppose the page in question has a single paragraph in the body:

<p>The shop is <strong>closed</strong> today.</p>

Well, rather than teaching the shop staff how to write HTML to update this, we can make a simple form to edit the page instead:

<model>

<submission action="http://www.example.com/shop/status.xhtml"

method="put" id="change"/>

</model

...

<item><label>Closed</label><value>closed</value></item>

</select1>

Note that for this to work, the page in question that is being changed must be correct XHTML, (and not HTML, since only XHTML is an XML document), and your server must accept the "put" method (not all servers do).

Submitting

Multiple Submissions*

HTML only allows you to submit the data to one server, in a single way.

XForms allows you to have different submit controls binding to different submission elements in the head to submit the data to different servers, or in different ways.

For instance, the search example could allow the user to submit the search string to different search engines:

<model>

<submission action="http://example.com/search"

method="get" id="com"/>

<submission action="http://example.org/search"

method="get" id="org"/>

</model>

and then in the body:

<submit submission="org"><label>Search example.org</label></submit>

<submit submission="com"><label>Search example.com</label></submit>

Submission Methods

Just as with HTML there are a number of ways to submit the data. In HTML how to submit is expressed in two attributes, method and enctype; in Xforms it is expressed in method only:

HTML and XForms Equivalent Submission Methods

HTML

XForms

method="get"

method="post"

enctype="application/x-www-form-urlencoded"

method="urlencoded-post"

method="post"

enctype="multipart/form-data"

method="form-data-post"

There are some new ways of submission; the most interesting are method="post" which posts the results as an XML document, and method="put" which puts the results as an XML document. An interesting use of this is something like:

which saves your results to the local filestore by using the file: scheme.

Since, as shown above, you can have more than one submission per form, this means that for a large form, you could have separate 'save to disk' and 'submit' buttons.

Life after Submit*

The default when values have been submitted is for the result returned by the server to replace the whole document, just as with HTML. However, there are other options, specified with the attribute replace on the submission element. The value replace="instance" replaces only the instance, and replace="none" leaves the form document as-is without replacing it.

For instance, for an address-change form for a bank, you can provide two buttons, one to prefill the form with name and address based on the account number, and one to submit the changed results:

<model>

</data></instance>

<submission method="get" action="http://example.com/prefill"

id="prefill" replace="instance"/>

<submission method="get" action="http://example.com/change"

id="change" replace="none"/>

</model>

...

<input ref="accountnumber"><label>Account Number</label></input>

<textarea ref="address"><label>Address</label></textarea>

<submit submission="change"><label>Submit</label></submit>

The 'find' button will replace the instance with a new instance containing the details of the person with the account number, which you can then change; the 'submit' button will then send the changed instance back, leaving the form as-is in the browser to allow further changes or to input a new account number to prefill.

Controlling Controls

In HTML you can specify that controls are disabled, or read-only but the only way you can change the property is with scripting.

XForms offers easy ways to control these properties, but has other properties you can specify as well:

that a value is required (that a value must be supplied before the form can be submitted)

that the value is constrained in some way (for instance that the year of birth is earlier than the year of death)

that the value must conform to a type (for instance that it must be an integer), or

that it is calculated from other values (for instance that the total is the sum of some other values).

Note that in XForms it is the collected value that has the property, not the control, but the property shows up on all controls bound to the value.

These properties use a <bind> element that goes in the <model>. To use bind, you must have an explicit <instance> element.

Disabled Controls

To disable controls you use the relevant property. For instance, to say that the credit card number only needs to be filled in if the person is paying by credit, you can write:

<model>

</data></instance>

</model>

This states that the fields cc and expires are only relevant when method has the value credit, and will therefore be disabled for other values of method. You have to say "../method" rather than just method, because in a bind you are talking about the thing referred to in the nodeset (which might be a structured element itself). It is as if you have done a 'change directory' to that element. If you said just "method", it would refer to a child element of cc or expires. You can also use absolute addressing, like /data/method, which would have the same effect as ../method in this case.

A browser is free to decide how disabled controls are presented (and it may also allow you to specify in a stylesheet how they should look), but typically they will be grayed out in the normal way.

The controls could be written like this (but note that there is no indication that they may get disabled: that is inherited from the value they refer to):

<select1 ref="method"><label>Method of payment:</label>

<item><label>Credit card</label><value>credit</value></item>

</select1>

<input ref="cc"><label>Card number:</label></input>

<input ref="expires"><label>Expiry date:</label></input>

If we used a structured instance, we could simplify this:

<model>

<cc>

</cc>

</data></instance>

</model>

and the controls then reference the children of 'cc':

<input ref="cc/number"><label>Card number:</label></input>

<input ref="cc/expires"><label>Expiry date:</label></input>

although grouping can be used to reset the context of the refs:

<input ref="number"><label>Card number:</label></input>

<input ref="expires"><label>Expiry date:</label></input>

</group>

Readonly Controls

Similarly to relevant, you can specify a condition under which a value is read-only. For instance:

<model>

<variant>basic</variant><color>black</color>

</data></instance>

</model>

This example says that the default value of color is black, and can't be changed if variant has the value basic.

Required Controls*

A useful new feature in XForms is the ability to state that a value must be supplied before the form is submitted. The simplest case is just to say that a value is always required. For instance, with the search example:

<model>

</model>

but like the readonly and relevant attributes, you can use any XPath expression to make a value conditionally required:

which says that the value for state is required when the value for country is "USA".

It is up to the browser to decide how to tell you that a value is required, but it may also allow you to define it in a stylesheet.

Constraint Property*

This property allows you to add extra constraints to a value. For instance:

constrains the year to be after 1970. Note the XPath use of "." to mean "this value". (">" has to be written as > because of XML rules, but you should be used to that already).

Calculate Property*

It is possible to indicate that a value in the instance is calculated from other values. For instance:

When a value is calculated like this, it automatically becomes readonly.

There are a number of functions available, including arithmetic, string manipulation, date handling, and conditionals using 'if'.

Types*

Another useful new feature is the ability to give a value a type. The browser can then check that the values match the required type.

For instance, if the search example is actually only for searching for numbers (for instance for searching in a bug database), then we only have to add:

This will prevent the value being submitted unless it is an integer.

(You then need to add xmlns:xsd="http://www.w3.org/2001/XMLSchema" to the root element.)

If you want to collect the URL of someone's homepage, then you can specify

You will find that some user agents do special things when they know the data type of a value. For instance, when they know that the value is a date, they pop up a date picker rather than require you to type in the characters of the date.

There are a number of useful built-in types you can use, including:

xsd:string, xsd:normalizedString (a string with whitespace characters replaced by the space character).

xsd:integer, xsd:nonPositiveInteger, xsd:negativeInteger, xsd:nonNegativeInteger, xsd:positiveInteger

xsd:boolean

xsd:decimal, xsd:double

xsd:date, xsd:time, xsd:dateTime

xsd:anyURI (A URI)

xforms:listItems (A space-separated list of strings for use with select)

xforms:listItem (A string without any spaces)

Combining Properties

If you have several binds referring to the same value, you can combine them: