XMPP For The Web/Win ::: XMPP-FTW (1.16.8)

XEP-0004 Data Forms

XML to JSON

Probably the best way to demonstrate the data form XML to JSON translation is through examples, so that's what will happen.

We'll be working with this example from the xmpp.org XEP-0004 specification, i.e.

<x xmlns='jabber:x:data'
   type='{form-type}'>
  <title/>
  <instructions/>
  <field var='field-name'
         type='{field-type}'
         label='description'>
    <desc/>
    <required/>
    <value>field-value</value>
    <option label='option-label'><value>option-value</value></option>
    <option label='option-label'><value>option-value</value></option>
  </field>
</x>

Outline

The general message format of a data form from XMPP rendered to JSON looks like this:

{
  /* title: "", */
  /* instructions: "", */
  form: {
    title: 'Register with the dev room!',
    instructions: 'Please fill out all required fields',
    fields: [ ]
  }
}

Note that it caters for an optional 'title' and 'instructions' from outside of the 'x' element as well.

Data Form Results

Currently form results are not supported, the status of this feature is being tracked see Data form results issue.

Fields

The data form fields are held in the 'fields' key of the 'form' section in XMPP-FTW. The fields have a general layout that follows, any differences are outlined following. Fields are stored in an array.

[
  {
    var:         'field-name',
    type:        'field-type',
    required:    true,
    value:       'field-value',
    description: 'field-description',
    options:     [
        { label: 'option-label', value: 'option-value' },
        { label: 'option-label', value: 'option-value' }
    ]
  }
]

Notes

• The 'options' key is only defined where appropriate
• The 'description' key is only defined where appropriate
• For 'list-multi' the value of the 'value' key is an array of set values
• The user is never sent the 'FORM_TYPE' field as this is the type of data which is inferred using event names.

JSON to XML

Data form JSON reply is a much simpler affair. Form data should be sent using a 'form' key with the following general format:

form: [
  { var: 'field-type', value: 'field-value },
  { var: 'field-type', value: [ 'field-value1', 'field-value2' ] }
]

The JSON to XML tranlation uses named events to fill in the FORM_TYPE variable for the user.