+
-Allows to gather data using Forms.
+Allows to exchange structured data between users and applications for common +tasks such as registration and searching using Forms. +
JEP related: JEP-4+Description
+ +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.
+ +Usage+ +In order to create a Form to fill out use the Form's constructor passing the constant +Form.TYPE_FORM 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 FormField use the FormField's +constructor specifying the variable name of the field as the parameter. Then use setType(String type) +to set the field's type (e.g. FormField.TYPE_HIDDEN, FormField.TYPE_TEXT_SINGLE). Once we have the +Form instance and the FormFields the last step is to send addField(FormField field) +for each field that we want to add to the form.
+ +Once the form to fill out is finished we will want to send it in a message. Send getDataFormToSend() to +the form and add the answer as an extension to the message to send.
+ +Examples
+
+In this example we can see how to create and send a form to fill out:
+
+ // Create a new form to gather data
+ 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");
+ // Add a hidden variable to the form
+ FormField field = new FormField("hidden_var");
+ field.setType(FormField.TYPE_HIDDEN);
+ field.addValue("Some value for the hidden variable");
+ formToSend.addField(field);
+ // Add a fixed variable to the form
+ field = new FormField();
+ field.addValue("Section 1: Case description");
+ formToSend.addField(field);
+ // Add a text-single variable to the form
+ field = new FormField("name");
+ field.setLabel("Enter a name for the case");
+ field.setType(FormField.TYPE_TEXT_SINGLE);
+ formToSend.addField(field);
+ // Add a text-multi variable to the form
+ field = new FormField("description");
+ field.setLabel("Enter a description");
+ field.setType(FormField.TYPE_TEXT_MULTI);
+ formToSend.addField(field);
+
+ // Create a chat with "user2@host.com"
+ 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");
+ // Add the form to fill out to the message to send
+ msg.addExtension(formToSend.getDataFormToSend());
+
+ // Send the message with the form to fill out
+ chat.sendMessage(msg);
+
+
+
++ +Description
+ +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.
+ +Usage+ +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.
+ +In order to create a new Form to complete based on the original Form just send +createAnswerForm() to the original Form. Once you have a valid form that could be actually +completed all you have to do is send setAnswer(String variable, String value) to the form where variable +is the variable of the FormField 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 setAnswer(String variable, List values) +where values is a List of Strings.
+ +Once the form has been completed we will want to send it back in a message. Send getDataFormToSend() to +the form and add the answer as an extension to the message to send back.
+ +Examples
+
+In this example we can see how to retrieve a form to fill out, complete the form and send it back:
+
+ // Get the message with the form to fill out
+ Message msg2 = chat2.nextMessage();
+ // Retrieve the form to fill out from the message
+ Form formToRespond = Form.getFormFrom(msg2);
+ // Obtain the form to send with the replies
+ Form completedForm = formToRespond.createAnswerForm();
+ // Add the answers to the form
+ 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");
+ // Add the completed form to the message to send back
+ msg2.addExtension(completedForm.getDataFormToSend());
+ // Send the message with the completed form
+ chat2.sendMessage(msg2);
+
+