mirror of
https://github.com/vanitasvitae/Smack.git
synced 2024-12-24 03:27:59 +01:00
Initial version.
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@2325 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
parent
5e612ae222
commit
ee44e762ec
1 changed files with 119 additions and 3 deletions
|
@ -6,16 +6,132 @@
|
|||
|
||||
<body>
|
||||
|
||||
<div class="header">Data Forms</div><p>
|
||||
<div class="header">Data Forms</div><p>
|
||||
|
||||
Allows to gather data using Forms.<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>
|
||||
|
||||
<em>More coming soon.</em>
|
||||
<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>
|
Loading…
Reference in a new issue