Stefan Cameron on Forms
Building intelligent forms using Adobe LiveCycle Designer

Disabling All Fields Within a Subform

I thought I would point-out a nice improvement that was made to XFA <subform> elements back in XFA 2.8: The addition of the access property.

In days of yore, if you wanted to disable all fields and exclusion groups (for the sake of brevity, I’ll refer to these collectively as “fields” in this article) in a particular section of your form, you would’ve had to write a script that recursively drilled down into all children of that section looking for fields to disable. This is because the access attribute only applied to fields.

With this change, assuming the section in question is contained within a subform, you can now easily disable all fields contained within it simply by setting the subform‘s access attribute to “readOnly”!

The following table describes the four levels of restrictiveness (in XFA 2.8, from the highest level to the lowest) that can be imposed on fields using the access attribute, either directly on a field or by a parent subform:

Level Access Value
Effect
1 nonInteractive Value can be loaded and calculations performed only upon form initialization.
2 protected The user cannot change the value directly and the field does not participate in the tabbing sequence. The field does not generate any events.
3 readOnly While the user may not change the value directly, it may be altered via scripts. The field still participates in the tabbing sequence and all events are generated except those related to direct user interaction.
4 open (default) The field is fully interactive and responds to direct user interaction.

When a subform imposes restrictions on the fields it contains (meaning all fields within any level of nesting, not just immediate children), the inheritance on child fields and subforms follows that of the most restrictive parent imposition. For example, if a subform imposes access=”protected” and a child subform has access=”readOnly”, all of the inner subform’s children, including the inner subform itself, will effectively have a “protected” access level.

The explanations of the various access types in the table above are summarized. “Access Restrictions” on page 48 of the XFA 2.8 specification has more precise, albeit more technical, explanations of each level of restrictiveness.

Setting Access by Script

Setting the access attribute of a field or subform by script is simple, both in JavaScript and FormCalc:

// set access level to read-only:
FormObject.access = "readOnly";

If you wanted to disable all fields in the entire form with a single line of script, you would simply set the root subform’s access attribute to something other than “open”, as appropriate:

// if the root subform's name is "form1":
xfa.form.form1.access = "nonInteractive"

Posted by Stefan Cameron on March 8th, 2010
Filed under Scripting,Tutorials,XFA
Both comments and pings are currently closed.

11 Responses to “Disabling All Fields Within a Subform”

  1. Stephanie on May 6th, 2010

    Thanks for the great post, but… I can’t get it to work on my form. I have a field that enables or disables the access of the fields inside a subform. I’m not sure exactly why it won’t work (this is a common feeling for me– I am frequently confused by everything in LiveCycle, especially as I am not a JavaScript guru… yet).

    I tried referencing the relative SOM as well as the absolute SOM in my script. I tried referencing the absolute SOM and adding “xfa.form” to the beginning of it. None of these resulted in the subform’s fields being uneditable. I think I just can’t figure out how to correctly attach access to the subform. When I used the relative SOM and typed “.access,” the little autocomplete window popped up, so apparently access is an option. It just doesn’t actually *work*.

    The subform itself has 20 radio button groups inside it, so making the whole form turn on and off (without affecting its visibility) would be a huge boon.

  2. Stephanie on May 6th, 2010

    OK, I figured out how to call the SOM from the root. And I even set up a test case using a really simple form with nothing but a text drop-down and a subform with radio buttons. In both cases, I was unable to get the subform’s access property to change. “Access” shows up in the autocomplete, but then nothing happens when I set it to readOnly.

    I’m using LiveCycle version 8.2.1.4029, and Acrobat Pro version 9.3.1. I’ve read the scripting reference and searched exhaustively online and in the various adobe forums for the answer. I am coming up with your post and then with legacy hacks that I don’t really understand (and which, if you’re correct about this property, should be unnecessary).

    Here’s my script from the simplified/test form:

    form1.#subform[0].DropDownList1::exit – (JavaScript, client)
    if (this.rawValue==”1″) {
    xfa.form.form1.Subform1.access=”open”;
    }
    else {
    xfa.form.form1.Subform1.access=”readOnly”;
    }

    When opening the form, the fields are all editable, and when changing the drop-down, they do not change to read only.

    I also tried adding an “initialize” script to the subform itself using
    this.access=”readOnly”;
    to try and just have the subform fields default to read-only. But that didn’t change the fields either.

    In essence: Everything I read says this should work. But it simply doesn’t. The fields inside the subform do not inherit the subform’s access property.

    Any suggestions?

  3. Mary on May 7th, 2010

    I’m having exactly the same problem Stephanie has reported. I’m using LiveCycle 8.1.1.2188.1.406459 & Adobe Reader 8.1.3 (Government).

    Scriptng works fine to modiy the access property of fields named explicitly, but setting the subform’s access property has no effect on the controls it contains. I tried it using both JavaScript and FormCalc, with no luck.

  4. Mary on May 7th, 2010

    I just noticed that the XFA 2.8 (in which the access property was added to the subform element) is “supported by Acrobat Pro 9.0, Adobe Reader 9.0, LiveCycle Designer ES version 8.2, and LiveCycle ES version 8.2″ according to the XFA link in the original post.

    Given the LiveCycle Designer (8.1.1.2188.1.406459) and Reader (8.1.3) versions I’m stuck with, I guess I will remain out of luck.

  5. Stephanie on May 10th, 2010

    I have Acrobat Pro 9, so I know that’s not the issue for me, at least.

    I’m also investigating why Livecycle crashes so often. Seems buggy.

  6. Stefan Cameron on May 10th, 2010

    @Stephanie,

    It sounds like you’re doing the right thing. The only gotcha I can think of is that while you’re using a version of Designer and Acrobat that do support XFA 2.8 (which means you have access to this new subform feature), your form itself is not behaving like an XFA 2.8 form due to compatibility settings that may have inadvertently been set on your form.

    You should verify that your form is targeting Acrobat 9.0+ in the “File > Form Properties > Default tab > Target Version property”. You should also make sure that the <?originalXFAVersion …?> processing instruction, as mentioned in the post I liked to above, doesn’t exist in your form’s XML Source.

    Then try setting the subform’s access property.

  7. Stephanie on May 11th, 2010

    Aha! That did the trick. Thank you, Stefan– I thought I’d set the targeting correctly, but I guess I hadn’t.

    Now if I could just get LiveCycle to stop crashing every time I edit a numeric field…. ;)

  8. Stefan Cameron on May 16th, 2010

    @Mary,

    As a workaround, you could always try using my Process All Fields script to programmatically set the access property on all fields inside a given subform (same effect as setting the subform’s access attribute in XFA 2.8+).

  9. Stefan Cameron on May 16th, 2010

    @Stephanie,

    About Designer 8.2.1 crashing, there are Service Packs available that would help with those issues. The only catch is that your license agreement must allow you to install them.

  10. Sajid on May 20th, 2010

    Hi Stefan

    I have created a date field but when i open it in adobe reader it gives me this error

    Adobe The Extended Language Support Package is required to display this page properly. Under the current configuration, this resource is not available

    Sajid

  11. Stefan Cameron on May 31st, 2010

    @Sajid,

    It sounds like the date time field’s locale is set to a language that Acrobat/Reader doesn’t know/recognize. You could try changing the field’s locale (using the “Object palette > Field tab > Locale property” or installing a version of Acrobat/Reader that supports the field’s locale.