XML Changes for Forms 0.5.x

[Jason Cater]

XML Changes for Forms 0.5.x

As has been hinted at in the gnue-dev list, and in IRC,
the forms GFD specification is undergoing some changes.
The main goal of James and I is to separate layout from
logic.  This of course entails breakage, or what modern
computer classes call "refactoring." ;)

We do not take changing the GFD format very lightly.
However, these are changes we have wanted to make for quite
some time now. We felt that the closer we get to Forms 1.0,
the more stable the GFD must become.  If we were going to
perform any specification cleanup, we needed to do it sooner
than later.

There is a utility in gnue/forms/utils called gfd04to05.py.
It can be run as:
  gfd04to05.py myform.gfd [destform.gfd]
If destform.gfd is not specified, then myform.gfd is backed
up and is overwritten by the new format.

Now, on to the list of changes.

(This describes existing format changes, not new features)

* blocks have been moved out of pages and into a new
  <logic> section, which is a child of <form>

* Pages have been moved into a new <layout> section,
  which is a child of <form>
  
* The height, width, and tabbed attributes of <form> are
  now attributes of <layout>. This is because those 
  attributes are more layout/display-oriented than 
  logic.

* A new tag, <field>, has been introduced that looks
  like the old <entry>, but will be a child of <block>

* <entry> has been simplified to only contain layout logic
  (positioning info, etc) and is a child of <page>.

* All blocks are transparent by default

* Transparent has been added to pages, but is set to
  false by default

* The "database" attribute of datasources was renamed to
  "connection",  so <datasource database="gnue" ..> would
  become   <datasource connection="gnue" ..>  This is to
  make it clearer that the value ties into the
  connections.conf file.

* Renamed the <database> tag to <connection> and moved into
  Common, so  reports, et al, can use.  This reinforces that
  this tag is a substitute for a connections.conf entry.

* Removed the trigger="..." attribute of buttons and, instead,
  use an On-Action trigger.

* Layout management markup has been added. Any layout-manager
  specific markup is namespace qualified.  The current "x","y",
  "width", and "height" attributes are part of GNUe:Layout:Char
  layout management.  (See example below)

So, an old form might look like:

<form tabbed="top" width="40" height="12">
  <datasource database="gnue" table="test" name="dts1"/>
  <datasource database="gnue" table="test" name="dts2"/>
  <datasource database="gnue" table="test" name="dts3"/>

  <page>
    <block name="b1" source="dts1">
      <label x=1 y=1 text="Who?"/>
      <entry x=10 y=1 name="entry1" field="myfield1"/>
      <entry x=10 y=4 name="entry2" field="myfield2"/>
    </block>
    <block name="b2" source="dts2">
      <entry x=10 y=2 name="entry3" field="myfield1"/>
      <entry x=10 y=3 name="entry4" field="myfield2"/>
    </block>
  </page>

  <page>
    <block name="b3 source="dts3">
      <label x=1 y=1 text="Who Me?"/>
      <entry x=10 y=1 name="entry5" field="myfield"/>
    </block>
  </page>
</form>


This same form would now look like:


<form>
  <datasource connection="gnue" table="test" name="dts1"/>
  <datasource connection="gnue" table="test" name="dts2"/>
  <datasource connection="gnue" table="test" name="dts3"/>

  <logic>
    <block name="b1" source="dts1">
      <field name="entry1" field="myfield1"/>
      <field name="entry2" field="myfield2"/>
    </block>
    <block name="b2" source="dts2">
      <field name="entry3" field="myfield1"/>
      <field name="entry4" field="myfield2"/>
    </block>
    <block name="b3 source="dts3">
      <field name="entry5" field="myfield"/>
    </block>
  </logic>


  <layout tabbed="top" xmlns:c="GNUe:Layout:Char" c:width="40"
c:height="12">
    <page>
      <label text="Who?" c:x=1 c:y=1 />
      <entry field="entry1" block="b1" c:x=10 c:y=1 />
      <entry field="entry3" block="b2" c:x=10 c:y=2 />
      <entry field="entry4" block="b2" c:x=10 c:y=3 />
      <entry field="entry2" block="b1" c:x=10 c:y=4 />
    </page>

    <page>
      <label text="Who Me?" c:x=1 c:y=1 />
      <entry field="entry5" block="b3" c:x=10 c:y=1 />
    </page>

  </layout>
</form>



This has a few new connotations:

  1. If the block is transparent (which it is by default), then
     the tab order on page 1 is:

         b1.entry1
         b2.entry3
         b2.entry4
         b1.entry2

     Then, at b2.entry2, if a page is transparent (not by default)
     then it focus would move to b3.entry5.  By default, however,
     pages are not transparent and focus would move back to b1.entry1.

  2. b1.entry1 can appear at multiple places on page1, or even
     on page2! There are still quite a few questions raised
     about this possibility (like trigger scope).

  3. Forms will have hooks for layout management. Don't expect other
     layout managers any time soon.  However, we wanted to break
     our format only once and be done.  Also, for the foreseeable
     future, Designer will only support the existing character-based
     format, even after a few layout manager plugins are written.

  4. The converter tries to convert trigger code, but it can only
     do so much.  The previous method of accessing a field was
     Page.Block.Field.  Of course, Blocks are independent of Pages,
     so that should read Block.Field.  The converter does basic
     conversions like this, but stuff like:
       p = Page
       b = p.Block
     would not be correctly converted.  Your form would give an error
     message.

All of these changes have been made in cvs head for the Forms product. 
However, Designer is still broken and will not read the new format. We
are currently working to correct this.