Debug Your Form Layout

Today I want to share with you a work-in-progress of a tool that you can use to debug your form layout.  The sample builds on some concepts from previous blog entries:

  • The form dom debugger that used script access to graphically display the form and data doms
  • The reporter form that loaded/opened a PDF and generated a summary of the contents.
  • The form demonstrating how to calculate layout positions

The motivation for the debugger form is simply that once you step outside the simple layout scenarios, form layout can be a complex area to debug.

The layout debugger form loads and opens an XFA/PDF and will graphically display the form dom and the page layout.  To get a feel for how it works, save this sample form to disk and then open it from the layout debugger form.  Some notes to guide you:

  • Before you opened the form there was a checkbox: "show boilerplate".  This allows you to include/exclude the static text/images/lines/rectangles etc. that occur on your form.  Often these have no impact on layout problems and there is less noise if we do not include them.
  • The left hand side of the page displays the form dom in much the same way that the form dom debugger did.  As before, you can expand/collapse the hierarchy and use the arrow buttons to scroll up or down half a page at a time.
  • The right hand side of the form shows a graphical display of the pages.  Each page is numbered and scaled proportionately.  Each page has its content area(s) drawn in a dashed line.
  • When you mouse into a field in the hierarchy, the pages are highlighted with the extent(s) of the corresponding object.  If the object has split across multiple content areas, it will display as multiple rectangular areas.  You’ll note that when you select the root of the form dom that it spans all pages.
  • There are a set of XFA properties that impact layout.  Things like: presence, layout, break, keep, overflow, etc. Each object in the form dom hierarchy displays the names of any layout properties that do not correspond to their default values.  When you mouse into the hierarchy field, the expanded property values are displayed in the top right corner of the page.
  • The hierarchy is colour coded.  Grey entries are not-splittable.  Green entries are splittable, yellow entries are overflow leader/trailer subforms that were added  by the layout process.  If you scroll to the bottom of the form hierarchy you will see a couple of "hdr" subforms that layout added.  Note that near the top of the hierarchy the first occurrence  of "hdr" appears because of its place in the form dom — not because layout added it.
  • While you are scrolled to the bottom, click on the "Date" field under page 1.  You will see it appear with a yellow warning icon.  This is because it was positioned off the page.  Adding warnings is an area where I need to do much more work.  It should be possible to detect more conditions that frequently cause layout problems.
  • When you click on a hierarchy object that is hidden, nothing in the page display gets highlighted.  That is because hidden objects are excluded from layout.

As I said, this is a work in progress.  But I felt it was far enough along to share.  I have more plans for it.  If you have specific ideas of how to improve it, please let me know.

June Update

There is a follow-up debugger effort that supercedes the sample in this entry. Please have a look here.