<html>
<head>
<title>Data Forms</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<div class="header">Data Forms</div><p>
Allows to exchange structured data between users and applications for common
tasks such as registration and searching using Forms.
<ul>
<li><a href="#gather">Create a Form to fill out</a></li>
<li><a href="#fillout">Answer a Form</a></li>
</ul>
<b>JEP related:</b> <a href="http://www.jabber.org/jeps/jep-0004.html">JEP-4</a>
<hr>
<div class="subheader"><a name="gather">Create a Form to fill out</a></div><p>
<b>Description</b><p>
An XMPP entity may need to gather data from another XMPP entity. Therefore, the data-gathering
entity will need to create a new Form, specify the fields that will conform the Form and finally
send the Form to the data-providing entity.</p>
<b>Usage</b><p>
In order to create a Form to fill out use the <i><b>Form</b></i>'s constructor passing the constant
<b>Form.TYPE_FORM</b> as the parameter. The next step is to create the form fields and add them to
the form. In order to create and customize a <i><b>FormField</b></i> use the <i><b>FormField</b></i>'s
constructor specifying the variable name of the field as the parameter. Then use <b>setType(String type)</b>
to set the field's type (e.g. FormField.TYPE_HIDDEN, FormField.TYPE_TEXT_SINGLE). Once we have the
<i><b>Form</b></i> instance and the <i><b>FormFields</b></i> the last step is to send <b>addField(FormField field)</b>
for each field that we want to add to the form.</p><p>
Once the form to fill out is finished we will want to send it in a message. Send <b>getDataFormToSend()</b> to
the form and add the answer as an extension to the message to send.</p>
<b>Examples</b><p>
In this example we can see how to create and send a form to fill out: <br>
<blockquote>
<pre> <font color="#3f7f5f">// Create a new form to gather data</font>
Form formToSend = new Form(Form.TYPE_FORM);
formToSend.setInstructions(
"Fill out this form to report your case.\nThe case will be created automatically.");
formToSend.setTitle("Case configurations");
<font color="#3f7f5f">// Add a hidden variable to the form</font>
FormField field = new FormField("hidden_var");
field.setType(FormField.TYPE_HIDDEN);
field.addValue("Some value for the hidden variable");
formToSend.addField(field);
<font color="#3f7f5f">// Add a fixed variable to the form</font>
field = new FormField();
field.addValue("Section 1: Case description");
formToSend.addField(field);
<font color="#3f7f5f">// Add a text-single variable to the form</font>
field = new FormField("name");
field.setLabel("Enter a name for the case");
field.setType(FormField.TYPE_TEXT_SINGLE);
formToSend.addField(field);
<font color="#3f7f5f">// Add a text-multi variable to the form</font>
field = new FormField("description");
field.setLabel("Enter a description");
field.setType(FormField.TYPE_TEXT_MULTI);
formToSend.addField(field);
<font color="#3f7f5f">// Create a chat with "user2@host.com"</font>
Chat chat = conn1.createChat("user2@host.com" );
Message msg = chat.createMessage();
msg.setBody("To enter a case please fill out this form and send it back to me");
<font color="#3f7f5f">// Add the form to fill out to the message to send</font>
msg.addExtension(formToSend.getDataFormToSend());
<font color="#3f7f5f">// Send the message with the form to fill out</font>
chat.sendMessage(msg);
</pre>
</blockquote>
<hr>
<div class="subheader"><a name="fillout">Answer a Form</a></div><p>
<b>Description</b><p>
Under many situations an XMPP entity could receive a form to fill out. For example, some hosts
may require to fill out a form in order to register new users. Smack lets the data-providing entity
to complete the form in an easy way and send it back to the data-gathering entity.</p>
<b>Usage</b><p>
The form to fill out contains useful information that could be used for rendering the form. But it
cannot be used to actually complete it. Instead it's necessary to create a new form based on the original
form whose purpose is to hold all the answers.</p><p>
In order to create a new <i><b>Form</b></i> to complete based on the original <i><b>Form</b></i> just send
<b>createAnswerForm()</b> to the original <i><b>Form</b></i>. Once you have a valid form that could be actually
completed all you have to do is send <b>setAnswer(String variable, String value)</b> to the form where variable
is the variable of the <i><b>FormField</b></i> that you want to answer and value is the String representation
of the answer. If the answer consist of several values you could then use <b>setAnswer(String variable, List values)</b>
where values is a List of Strings.</p><p>
Once the form has been completed we will want to send it back in a message. Send <b>getDataFormToSend()</b> to
the form and add the answer as an extension to the message to send back.</p>
<b>Examples</b><p>
In this example we can see how to retrieve a form to fill out, complete the form and send it back: <br>
<blockquote>
<pre> <font color="#3f7f5f">// Get the message with the form to fill out</font>
Message msg2 = chat2.nextMessage();
<font color="#3f7f5f">// Retrieve the form to fill out from the message</font>
Form formToRespond = Form.getFormFrom(msg2);
<font color="#3f7f5f">// Obtain the form to send with the replies</font>
Form completedForm = formToRespond.createAnswerForm();
<font color="#3f7f5f">// Add the answers to the form</font>
completedForm.setAnswer("name", "Credit card number invalid");
completedForm.setAnswer(
"description",
"The ATM says that my credit card number is invalid. What's going on?");
msg2 = chat2.createMessage();
msg2.setBody("To enter a case please fill out this form and send it back to me");
<font color="#3f7f5f">// Add the completed form to the message to send back</font>
msg2.addExtension(completedForm.getDataFormToSend());
<font color="#3f7f5f">// Send the message with the completed form</font>
chat2.sendMessage(msg2);
</pre>
</blockquote>
</body>
</html>