mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-11-14 11:42:04 +01:00
137 lines
No EOL
6.3 KiB
HTML
137 lines
No EOL
6.3 KiB
HTML
<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>XEP related:</b> <a href="http://www.xmpp.org/extensions/xep-0004.html">XEP-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> |