Mercury-IM/Smack
Mercury-IM/Smack
1
0
Fork 0
mirror of https://codeberg.org/Mercury-IM/Smack synced 2024-11-22 06:12:05 +01:00
Code Issues Releases Wiki Activity

Update/Edit documentation

Browse source
This commit is contained in:
Jesus Fuentes 2018-04-01 09:57:13 -05:00
parent a9ca1a0989
commit f0c5d1db74
1 changed files with 45 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
documentation/extensions/dataforms.md
View file

@ -3,7 +3,7 @@ Data Forms
[Back](index.md) [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. tasks such as registration and searching using Forms.
* Create a Form to fill out * 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, 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 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. entity.
**Usage** **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 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 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 _**FormField**_ use the _**FormField**_'s constructor specifying the variable
name of the field as the parameter. Then use **setType(String type)** to set 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). 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 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 to send **addField(FormField field)** for each field that we want to add to
the form. 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 // Create a new form to gather data
Form formToSend = new Form(DataForm.type.form); Form formToSend = new Form(DataForm.Type.form);
formToSend.setInstructions(Fill out this form to report your case.\nThe case will be created automatically."); formToSend.setInstructions("Fill out this form to report your case.\nThe case will be created automatically.");
formToSend.setTitle("Case configurations"); formToSend.setTitle("Case configurations");
// Add a hidden variable to the form // Add a hidden variable to the form
FormField field = new FormField("hidden_var"); FormField field = new FormField("hidden_var");
field.setType(FormField.type.hidden); field.setType(FormField.Type.hidden);
field.addValue("Some value for the hidden variable"); field.addValue("Some value for the hidden variable");
formToSend.addField(field); formToSend.addField(field);
// Add a fixed variable to the form // Add a fixed variable to the form
field = new FormField(); field = new FormField();
field.addValue("Section 1: Case description"); field.addValue("Section 1: Case description");
formToSend.addField(field); formToSend.addField(field);
// Add a text-single variable to the form // Add a text-single variable to the form
field = new FormField("name"); field = new FormField("name");
field.setLabel("Enter a name for the case"); field.setLabel("Enter a name for the case");
field.setType(FormField.type.text_single); field.setType(FormField.Type.text_single);
formToSend.addField(field); formToSend.addField(field);
// Add a text-multi variable to the form // Add a text-multi variable to the form
field = new FormField("description"); field = new FormField("description");
field.setLabel("Enter a description"); field.setLabel("Enter a description");
field.setType(FormField.type.text_multi); field.setType(FormField.Type.text_multi);
formToSend.addField(field); formToSend.addField(field);
// Create a chat with "user2@host.com" // Create a chat with "user2@host.com"
Chat chat = conn1.createChat("user2@host.com" ); Chat chat = ChatManager.getInstanceFor(conn1).chatWith("user2@host.com" );
Message msg = chat.createMessage(); Message msg = new Message();
msg.setBody("To enter a case please fill out this form and send it back"); 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 // Add the form to fill out to the message to send
msg.addExtension(formToSend.getDataFormToSend()); msg.addExtension(formToSend.getDataFormToSend());
// Send the message with the form to fill out // Send the message with the form to fill out
chat.sendMessage(msg); chat.send(msg);
``` ```
Answer a Form 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 In order to create a new _**Form**_ to complete based on the original
_**Form**_ just send **createAnswerForm()** to the original _**Form**_. Once _**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 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 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 you could then use **setAnswer(String variable, List values)** where
values is a List of Strings. values is a List of Strings.
@ -112,18 +119,27 @@ form and send it back:
``` ```
// Get the message with the form to fill out // Get the message with the form to fill out
Message msg2 = chat2.nextMessage(); Chat chat2 = ChatManager.getInstanceFor(conn).addIncomingListener(
// Retrieve the form to fill out from the message new IncomingChatMessageListener() {
Form formToRespond = Form.getFormFrom(msg2); @Override public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) {
// Obtain the form to send with the replies // Retrieve the form to fill out from the message
Form completedForm = formToRespond.createAnswerForm(); Form formToRespond = Form.getFormFrom(message);
// Add the answers to the form
completedForm.setAnswer("name", "Credit card number invalid"); // Obtain the form to send with the replies
completedForm.setAnswer("description", "The ATM says that my credit card number is invalid"); Form completedForm = formToRespond.createAnswerForm();
msg2 = chat2.createMessage();
msg2.setBody("To enter a case please fill out this form and send it back"): // Add the answers to the form
// Add the completed form to the message to send back completedForm.setAnswer("name", "Credit card number invalid");
msg2.addExtension(completedForm.getDataFormToSend()); completedForm.setAnswer("description", "The ATM says that my credit card number is invalid");
// Send the message with the completed form
chat2.sendMessage(msg2); 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);
}
});
``` ```