From f0c5d1db74e6a9b4887ec7c13548a3c99720e9cd Mon Sep 17 00:00:00 2001 From: Jesus Fuentes Date: Sun, 1 Apr 2018 09:57:13 -0500 Subject: [PATCH] Update/Edit documentation --- documentation/extensions/dataforms.md | 74 ++++++++++++++++----------- 1 file changed, 45 insertions(+), 29 deletions(-) diff --git a/documentation/extensions/dataforms.md b/documentation/extensions/dataforms.md index 7685fd5cc..0dd24f3f1 100644 --- a/documentation/extensions/dataforms.md +++ b/documentation/extensions/dataforms.md @@ -3,7 +3,7 @@ Data Forms [Back](index.md) -Allows to exchange structured data between users and applications for common +Allows the exchange of structured data between users and applications for common tasks such as registration and searching using Forms. * Create a Form to fill out @@ -18,7 +18,7 @@ Create a Form to fill out 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 +that will conform to the Form and finally send the Form to the data-providing entity. **Usage** @@ -27,9 +27,9 @@ In order to create a Form to fill out use the _**Form**_'s constructor passing the constant **DataForm.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 +name of the field as the parameter. Then use **setType(FormField.Type 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. @@ -43,36 +43,43 @@ 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(DataForm.type.form); -formToSend.setInstructions(Fill out this form to report your case.\nThe case will be created automatically."); +Form formToSend = new Form(DataForm.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.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); +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); +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(); +Chat chat = ChatManager.getInstanceFor(conn1).chatWith("user2@host.com" ); +Message msg = new Message(); msg.setBody("To enter a case please fill out this form and send it back"); + // 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); +chat.send(msg); ``` Answer a Form @@ -94,10 +101,10 @@ 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 +you have a valid form that can be 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 +the String representation of the answer. If the answer consists of several values you could then use **setAnswer(String variable, List values)** where values is a List of Strings. @@ -112,18 +119,27 @@ 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"); -msg2 = chat2.createMessage(); -msg2.setBody("To enter a case please fill out this form and send it back"): -// Add the completed form to the message to send back -msg2.addExtension(completedForm.getDataFormToSend()); -// Send the message with the completed form -chat2.sendMessage(msg2); +Chat chat2 = ChatManager.getInstanceFor(conn).addIncomingListener( + new IncomingChatMessageListener() { + @Override public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) { + // Retrieve the form to fill out from the message + Form formToRespond = Form.getFormFrom(message); + + // 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"); + + Message msg2 = new Message(); + msg2.setBody("To enter a case please fill out this form and send it back"); + + // Add the completed form to the message to send back + msg2.addExtension(completedForm.getDataFormToSend()); + + // Send the message with the completed form + chat.send(msg2); + } + }); ```