Stefan Cameron on Forms
Building intelligent forms using Adobe LiveCycle Designer

Presence vs Relevance

Designer 7.1 introduced the ability to specify whether a button was visible only on the (computer) screen, only on paper (print) or both (visible all the time). This feature, supported in conjunction with Acrobat 7.0.5, was then extended to all XFA objects (text fields, check boxes, lists, etc.) in Designer/Acrobat 8.0.

Unfortunately, how the two concepts interact is something that isn’t easy to grasp at first and so I thought I would delve into the details and attempt to clarify things.

Note that in this article when I write about Acrobat I include Reader as well.

Before Relevance

Prior to the concept of relevance, an object was either visible, invisible or hidden, as specified by the presence attribute and it didn’t matter whether the form as being rendered on a computer screen or printed on a piece of paper — it could either be seen or not.

One of the problems with this approach to presence surfaced when you wanted to design a form that had a submit button for the electronic “fill & submit” workflow but you also wanted to support the manual “fill, print & mail” workflow. When the user printed the form, they would get this submit button on the print-out which was completely useless and looked out-of-place.

In Designer/Acrobat 7.0 or earlier, if you wanted to prevent the button from printing, you had to resort to scripting the button’s PrePrint and PostPrint events in order to hide the button while the form was being printed:

PrePrint

this.presence = "invisible"; // or "hidden";

PostPrint

this.presence = "visible";

Relevance in Designer 7.1 / Acrobat 7.0.5 – 7.0.9

The advent of Designer 7.1 and Acrobat 7.0.5 introduced support for ”relevance” on button objects only. Relevance lets us further define the circumstances where an object is visible.

There are currently two supported “views” to which objects may be relevant: Screen View and Print View. They are both straight-forward: The Screen View represents the form as it is seen on a computer screen (in Acrobat or a browser) and the Print View represents the form as it is seen on paper (after being printed).

The following table illustrates the view(s) in which a form object is visible given values assigned to an object’s presence and relevant properties. For instance, if an object is defined as follows in XFA

<field presence="invisible" relevant="+print">...</field>

it would be included (“in”) only in the Print View.

Relevant Presence Screen View Print View
+print visible in in
-print visible in out
+print invisible out in (visible)
-print invisible out out
+print hidden out out
-print hidden out out

Note that if the relevant property isn’t specified, the presence property controls the object’s inclusion in both views at the same time (as was the case before the introduction of the “relevant” property).

More importantly, notice how setting the presence property to “invisible” and the relevant property to “+print” actually causes the object to be visible in the Print View (rather than invisible). This wasn’t the original intent and was corrected in Acrobat 8.0+.

Relevance in Designer/Acrobat 8.0+

The 8.0 versions not only added support for presense and relevance on all objects (text fields, list boxes, circles, squares, text, subforms, radio button lists, etc.) but they also corrected the results of some presence and relevant property combinations such that the two are now disjoint: The relevant property determines the view (Screen and/or Print) to which an object belongs and the presence property then controls the object’s visibility within that view.

The result is as follows (note the differences highlighted in blue between both tables):

Relevant Presence Screen View Print View
+print visible out in
-print visible in out
+print invisible out in (invisible)
-print invisible in (invisible) out
+print hidden out in (hidden)
-print hidden in (hidden) out

As in previous versions, the omission of the relevant property gives control to the presence property in both views.

Setting Presence and Relevance in Designer 8.0+

Designer exposes presence and relevance via its presence property in the Object palette. It combines the two into the following settings:

Designer XFA Relevant XFA Presence
Visible <not specified> visible
Visible (Screen Only) -print visible
Visible (Print Only) +print visible
Invisible <not specified> invisible
Hidden <not specified> hidden

Differing Behaviors Across Acrobat Versions

Remember that the results of the relevant and presence property combinations are specific to the version of Acrobat being used to view/print the form.

For example, if you designed a form with a button that had

presence="invisible", relevant="+print"

it would be excluded from the Screen View but visible in the Print View in Acrobat 7.0.5 – 7.0.9. However, if you were to open the same PDF form in Acrobat 8.0+, the button would be invisible in the Print View.


Posted by Stefan Cameron on September 27th, 2007
Filed under Acrobat,Designer,XFA
Both comments and pings are currently closed.

18 Responses to “Presence vs Relevance”

  1. Jane on September 30th, 2007

    Stefan,

    I have a problem that is related to this topic. I have a date field in an instantiated subform that has a script on the exit event that makes one of three sets of hidden buttons visible, depending on the date entered. Clicking on one of the buttons makes a third (text) field visible and adds “1″ to one of two numeric fields (for counting purposes). On that click event, it also changes the date field to access: “protected” and hides the buttons. Basically, after all these events, I don’t want any more changes.

    The problem is with the protection of the date field. Although it does prevent any changes to the date, if the mouse clicks in the caption part of the date field (not the calendar field), it triggers the exit event and the buttons appear. The bigger problem is that if one of those buttons is clicked, it adds 1 to the numeric field and then the count is off. The script works perfectly as long as there is no clicking on the date field after all this above events happen. I thought that “protected” meant that no events would be triggered. Is there anyway around this?

    Thank you!

  2. Stefan Cameron on October 11th, 2007

    Jane,

    I would suggest you set the access property of your date/time field to “readOnly” instead of “protected”. This will make the field non-interactive and it will no longer respond to any mouse or keyboard events.

  3. Kyle on March 28th, 2008

    I am a beginner and do not know xml very well. I am creating a form where I want a border sunken box around the text field but when the form is printed I want the border to dissappear only showing the text that was entered into that field. Can this be done, and if so can you give me very simple steps on how to accomplish this. I am using LiveCycle Designer that is included with Adobe Acrobat 8.

  4. Stefan Cameron on April 4th, 2008

    Kyle,

    I’m assuming that you mean your text field has a sunken border only around its content area (i.e. only around the value), not its nominal extent (i.e. its caption and value). To do this, you simply need to use the PrePrint and PostPrint to hide and show, respectively, the content area border of the field.

    Select the text field and use the “Window > Script Editor” command to show the Script Editor palette. Choose the PrePrint event and hide the content area border (you may also have to set the language to JavaScript since I’m showing JavaScript in this example):

    this.ui.oneOfChild.border.presence = "hidden";

    Next, choose the PostPrint event and make the border visible again:

    this.ui.oneOfChild.border.presence = "visible";

    That’s it!

  5. Tom Chung on April 17th, 2008

    I have a problem on trying to decrypt a owner password protected Adobe Form. The form is desiged on Adobe LiveCycle Designer 8.1.1 and is owner password protected. I have tried to use 2 Java open source software (iText and PDFBox) to decrypt without success. Any suggestions? In both open source software, I can detect the adobe document is encryted with their APIs.

  6. Stefan Cameron on April 19th, 2008

    Tom Chung,

    I’m afraid I can’t help you decrypt a password-protected PDF. It’s not something you should be trying to do…

  7. Rahul on June 5th, 2008

    Hi Stefan,

    I am getting this weird problem in LiveCycle (not that it operates smoothly on other occasions). I have a few text fields on the form which are hidden (there to hold user entered options across various sessions). There is a button whose click event updates the values of these fields. The problem is, even though in the click event, it shows the values (rawValue) of the text fields as being updated, these are not updated on the form itself. If I use app.alert() in click event to see values, these are shown as updated values but the values in the fields don’t change (I have checked this by making the fields visible so that I can spot the change). These remain null forever.

    If you can help, I will greatly appreciate that. I have checked Adobe Forums to see if there is a related post but found none. The nearest I can find is yours and I am encouraged to see that you actually reply to the posts; on many sites, replies are found rarely (if ever).

    Thank you in advance.

    Rahul.

  8. Stefan Cameron on June 8th, 2008

    Rahul,

    What’s the script you’re using in the button’s Click event to update the values of the hidden text fields? If your script is written in JavaScript, have you looked at the JavaScript Console in Acrobat to see if there are any errors?

  9. Nicole on November 20th, 2008

    Stefan,

    I’m working a form where I have a drop-down list at the top of the form where the users select their name and other fields are automatically filled in. This part works just fine. However, I am trying to make the drop-down list box disappear after the selection has been made and the user has selected “yes” from the confirmation box. The confirmation box works, too. However, the if statement that I put in after the confirmation box script only works in part. It is supposed to make the entire drop-down list box disappear if the user chooses “yes” that they have made the correct choice in names. The problem is this: the content area appears to disappear, but the caption stays behind. No matter what I try, it will not disappear with the content area. This code has worked on another form, but will not work on this one.

    topmostSubform.Page1.officerSetupBox::exit – (JavaScript, client)
    //Message box asking for confirmation that the intended choice was selected. 1=icon listed on message box, 2=yes and no button displayed.
    //Answer selected put into variable called confirm
    var confirm = xfa.host.messageBox(“Is this the officer you wish to select?”, “Confirmation”, 1, 2)
    //If the answer is yes make box disappear; 4=yes;
    if (confirm==4)
    {officerSetupBox.presence=”invisible”;}

    What am I missing here and why would this work in one form but not another? I’ve come across that several times.

    Any help would be appreciated. I’m not finding any help in any of the resources I have looked at.

    Nicole

  10. Nicole on November 20th, 2008

    Stefan,

    Please disregard my last post. I changed the form to dynamic rather than static and that took care of the problem.

    Nicole

  11. David Joycw on July 8th, 2009

    Hi Stefan,

    Maybe you can help me with a query I have around making fragments hidden. I have a form that includes a fragment. I can make the presence of this fragment hidden by specifying the following JavaScript within my form:
    xfa.form.MyForm.MyForm.MyFragment.presence=”hidden”
    However, my requirements are for the JavaScript to reside within the fragment. However, when I embed corresponding JavaScript in my fragment the fragment always displays when the form is rendered. Would you have an example of how to achieve this?

    Thanks.

  12. Stefan Cameron on July 15th, 2009

    David Joycw,

    If you put

    xfa.form.MyForm.MyForm.MyFragment.presence=”hidden”

    in your fragment and it gets inserted into a document which has a root subform named “form1″ instead of “MyForm”, your script will fail because “MyForm” won’t exist, which could explain why the fragment won’t hide itself.

    You didn’t explain under what circumstances the fragment would hide itself but let’s say it was during the form’s initialization sequence if a particular field value was not 1. This is what you could put in the fragment’s Initialize event (Initialize event of the subform that is defined as a fragment):

    // JavaScript:
    if (theField.rawValue != 1)
        this.presence = "hidden";
  13. Alvin on December 30th, 2009

    Hi Stefan,

    I had a try on using relevant as opposed to hiding/showing at pre-print and post-print events. However, it appears that fields that was set with relevant=”-print” were “invisible” on print. Is there a way that we could make the fields “hidden” on print rather than having them “invisible” using the relevant property?

  14. Stefan Cameron on January 6th, 2010

    Alvin,

    I don’t believe you can achieve this only with the relevant attribute. You’ll need to set the presence to “hidden” on the PrePrint event.

  15. Arwin on January 11th, 2010

    Dear Stefan,

    I want to display a post print message, explaining what a user should do after printing the form.

    How and where within the XML Source should this be done?

    Thanks for your help, I appreciate the effort.

  16. Stefan Cameron on January 13th, 2010

    Arwin,

    You would do this using the Script Editor by adding an xfa.host.messageBox(“<message>”) statement in the object’s (most likely the print button) PostPrint event. The PostPrint event is fired on all objects (that support it) after printing.

  17. Chris on August 5th, 2010

    Hi Stefan, Reading the XFA Spec, there’s a section “Concealing Containers Depending on View” which talks about defining your own views under the element of the configuration . Can you tell me if these have currently been implemented. I’ve tried to follow the spec but have so far not had any luck.

    Thanks

  18. Stefan Cameron on August 13th, 2010

    @Chris,

    Based on my understanding of the spec, I don’t think anything other than “print” can be used in this case. I can see how having custom relevant values could be useful but I don’t think it’s supported by Acrobat/Reader as the XFA agent.