diff --git a/documentation/extensions/dataforms.html b/documentation/extensions/dataforms.html index de657ea21..1c2aee457 100644 --- a/documentation/extensions/dataforms.html +++ b/documentation/extensions/dataforms.html @@ -6,16 +6,132 @@ -
Data Forms

+

Data Forms

-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
-More coming soon. +
Create a Form to fill out

+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);
+
+
+ +
+ +
Answer a Form

+ +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);
+
+
\ No newline at end of file