Search This Blog

Saturday, 1 June 2013

Using the Doc.scroll method in a LiveCycle Designer Form

It is common to use the xfa.host.setFocus method to position the user on a particular field in the form. Say they have just clicked the submit button and you have detected that they have left a mandatory field empty.  You give them an error message and use xfa.host.setFocus to position them on the field.
 

The problem with this approach is that setFocus always tries to position the field in the middle of the screen.  This may then mean that the question at the top of the screen, were the eye is naturally drawn to, may not be related the message we have just shown the user.
 


We may also want to move to a non-interactive object on the form, maybe a text object that forms a section heading, or some help text.
 


To achieve this we can use the Doc.scroll method, but this means we need to calculate the y coordinate of the object.  The code I have used to perform the calculation comes from John Brinkman's blog, Layout Methods to Find Page Positions.  All we then need to do is rotate the coordinate (so the point 0,0 is at the bottom left corner of the page)
.


This method is written in JavaScript but is dependent on the FormCalc function UnitValue. To use this code in your forms you need to copy the first subform in the sample called FormCalc (see John's blog Calling FormCalc Functions from JavaScript for more details in this technique) and the script object XFAUtil. 
  


The scrollTo function definition is;


/** Scrolls the specified control to the top of the current view and optional sets focus the the specified control.
 
 * @param {form object} target   (required) -- the control to place at the top of the current view.
 
 * @param {form object} setFocus (optional) -- the control that receives focus.
 
 */

function scrollTo(target, setFocus)
 


To see this in action download the ScrollTo.pdf sample and select a form object from the drop down and click the "ScrollTo" button or "Set Focus" to compare the two methods.



I'm not sure how widely known it is, but the Adobe Reader keyboard short-cut for returning to the previous position in the form is Alt+Left Arrow (or Command + Left Arrow on a Mac).


No comments:

Post a Comment