Generic Forms

Ryan Eatmon

The Jabber.org Project

reatmon@jabber.org

01/25/2001


Generic Forms

This needs to be cleaned up and edited yet...

The iq:register and iq:search namespaces are not flexible enough to handle 
a wide variety of situations.

The problem is this.  In order for an Agent or Server to user iq:register it
has to ask for information that is in the iq:register.  Let's say that I wanted
to make a BloodBank-Agent and one of the fields would be blood type.
I can't so that in the current setup.  There is no field that I could even
come close to listing as that.  I could try to use <misc/> but what if I also
wanted another piece of misc info?

And... try to do a search on the above...

I know that that <instructions/> stuff is supposed to explain how to fill out
the fields, but that's not good either.


And let me through another thing into the arena...  Why are we tied down to
Entry fields?  Why no password fields that *** the string out, and no pulldown
fields, or checkboxes?


I propose that we change the two namespaces to be alot more flexible and
defined not by the DTD but by the Agent that is asking for the informaiton.

<iq type='result' from='foo.jabber.org'>
  <query xmlns='jabber:iq:forms:register'>
    <field type='pulldown' label='Sex' key='sex' order='3'>male
      <option value='male'>Male</option>
      <option value='female'>Female</option>
    </field>
    <field type='entry' label='First Name' key='first' order='1' />
    <field type='entry' label='Last Name' key='last' order='2' />
    <field type='pulldown' label='Blood Type' key='blood_type' order='4'>A-Positive
      <option value='a+'>A-Positive</option>
      <option value='b-'>B-Negative</option>
      etc...
    </field>
    <field type='radio' label='Pints to give' key='pints' order='6'>2
      <option value='1'>One</option>
      <option value='2'>Two</option>
      <option value='3'>Three</option>
    </field>
    <field type='checkbox' label='Willing to donate' key='willing' order='5'>1</field>
  </query>
</iq>

The user would see the following in his GUI:


    First:      _________________

    Last:       -----------------

    Sex:        [ Male   \/ ]
                +-----------+
                | Male      |
                | Female    |
                +-----------+

    Blood Type: [ A-Positive   \/ ]
                +-----------------+
                | A-Positive      |
                | B-Negative      |
                |  ...            |
                |  ...            |
                +-----------------+

    Willing to Donate: [ * ]

    Pints to Give:  ( ) One
                    (*) Two
                    ( ) Three


and the user would send back:

<iq type='set' from='bob@jabber.org'>
  <query xmlns='jabber:iq:forms:register'>
    <field key='sex'>Male</field>
    <field key='first'>Bob</field>
    <field key='last'>Smith</field>
    <field key='blood_type'>b-</field>
    <field key='willing'>1</field>
    <field key='pints'>3</field>
  </query>
</iq>



Same thing with a search.  Instead of hard coding which fields the namespace 
has let's make it open.  Also let's make it so that we can have multiple kinds
of fields instead of just entry.




I propose the following "types":

entry           - generic entry box
password        - entry box but with * instead of text
pulldown        - pull down single selection
listbox-single  - listbox single selection
listbox-multi   - listbox multiple selection
checkbox        - boolean checkbox
radio           - radio fields
label           - non-editable entry or label







The iq:forms:register DTD would look this:

<?xml version="1.0" encoding="UTF-8" ?>

 <!ELEMENT query ((instructions? | field? | key? | registered? | remove?)*)>

   <!ELEMENT instructions (#PCDATA)>
   <!ELEMENT option (#PCDATA | default?)>
     <!ATTLIST field
       value CDATA #IMPLIED
     >
   <!ELEMENT field (#PCDATA | option?)*>
     <!ATTLIST field
       label CDATA #IMPLIED
       order CDATA #IMPLIED
       var CDATA #REQUIRED
       type (
         entry |
         password |
         pulldown |
         listbox-single |
         listbox-multi |
         checkbox |
         radio |
         label
       ) #IMPLIED
     >
   <!ELEMENT key (#PCDATA)>
   <!ELEMENT registered (#PCDATA)>
   <!ELEMENT remove (#PCDATA)>


And the iq:forms:search DTD would look this:

<?xml version="1.0" encoding="UTF-8" ?>

 <!ELEMENT query ((instructions? | 
                   field? |
                   item? |
                   key? |
                   truncated?
                  )*)>

   <!ELEMENT instructions (#PCDATA)>
   <!ELEMENT item ( field* )>
     <!ATTLIST item
       jid CDATA #REQUIRED
     >
   <!ELEMENT option (#PCDATA | default?)>
     <!ATTLIST field
       value CDATA #IMPLIED
     >
   <!ELEMENT field (#PCDATA | option?)*>
     <!ATTLIST field
       label CDATA #IMPLIED
       order CDATA #IMPLIED
       var CDATA #REQUIRED
       type (
         entry |
         password |
         pulldown |
         listbox-single |
         listbox-multi |
         checkbox |
         radio |
         label
       ) #IMPLIED
     >
   <!ELEMENT key (#PCDATA)>
   <!ELEMENT truncated (#PCDATA)>



where the result <field/>s have type='label' to show that they are 
non-editable entries.