Domino Gives Birth to Surrogate Fields
Remember the Domino Checkbox Bug? Sorry, I should of course say "browser limitation". Well, it's four years since I wrote that article and have just found out that things have changed. It's time for an update on the problem.
Briefly, the problem is that, when you submit a web form with a button that uses JavaScript (rather than @Functions) you can't deselect previously checked checkboxes. Thinking about this from Domino's point of view this is understandable. How does it now whether the checkbox field was on the form? Without the luxury of the context-sensitive @Function button it has no way of knowing. Not that I'm making excuses for them or anything.
Apparently this was addressed in releases 6.x. Certainly I've had trouble recreating the issue in a simple form I just put together. As far as I can tell JavaScript calls to .submit() now work with forms that include checkboxes. Although I'm sure I've seen the problem as recently as a month or so ago.
Anyway, getting to the point, there's been a change in releases 7.x and 6.5.5 onwards that introduces the %%Surrogate_Field. Consider the HTML below:
<input name="%%Surrogate_Private" type="hidden" value="1"> <input type="checkbox" name="Private" value="1" checked>Yes <input type="hidden" name="Private" value="">
This is from a form with a single-option checkbox field on it called "Private". The hidden empty field below it, also called Private, is my hack field, as documented in my original article. The field above it called %%Surrogate_Private has been inserted by the Domino server. Presumably this is to fix the bug. But I thought it was already fixed? If so, why this new addition and what the hell does it do in the backend?
Having searched the web I can find no official documentation of this change and only one mention of it in the forums. Does anybody know more about it? I'm confused.
Skip to the 
You can subscribe to an individual
Having thought about this, here's what I've worked out:
The surrogate field represents the state of the checkbox (also used for dropdowns/selects etc) field at the point it was served to the browser. So, in the example in the post, it has a value of one, as this is the default value for the field. Now, if we uncheck the field and post back, the browser doesn't POST the field name/value pair back, which is why Domino has problems in the first place. However, the surrogate field IS passed back. So, if the surrogate field has a value of 1 and no normal field is posted the server knows it sent the normal field (by presence of surrogate) and knows to modify the backend field.
Make sense?
Hang on. I take that back. It was coincidence that the surrogate field had the same value as its "parent" field. The value of the surrogate field has nothing to do with anything and is always "1", no matter what the value of the actual field. So, I guess, the value for the surrogate could well be "foo". All that matters is that it was there in the first place, which tells Domino its parent was too. If not parent field is posted back we know it's had all values unticked.
you talking to yourself Jake? :P
Nobody else will today Jono.
Also, I did another validation of the way this works. Using Firebug I renamed the surrogate field to %%Surrogate_Foo, unchecked all options of a previously checked checkbox and submitted the form. It broke. So the surrogate field is working and does its job well.
Good. Now grab that sixpack go to gazebo and wait for World Cup to begin. ;-)
Taking a step back here - I don't understand why people find it necessary to do a JavaScript submit in Domino? If you're can be certain that JavaScript is available (which it must for your submit call to work), then why not just call the onClick event of a button (in a hidden div) with an @Command([FileSave]) behind it?
I didn't think this was IBM's problem to fix personally, and I'm quite surprised they have considering a solution was already available.
@ Dorian
Or why not just use an input type=submit and skip JS form submission all together? That is what I usually do for web apps weher the assurance of js support is not 100%. It means hand coded html but makes more sense to me. Less clutter and random Domino helpfulness.
Domino sort of forces JS on you when you let it render Action buttons to HTML equivalents. I have a suspicion as to why but its not proven yet.
@Dorian and @Jerry
Time to take another step back...
AFAIK, the "submit" method utilized is irrelevant. The problem comes from POSTing HTML combined with the useful Domino behavior of not sending every field is sent to a browser. Given that some fields may not be sent to the user to edit, Domino does not clear out "non-submitted" fields. Example:
- document contains a computed Readers field. That field is not sent to the browser as an input field. Consequently, upon submit, the browser does not POST that field. Clearing that readers field simply because it wasn't POSTed by the browser would be wrong.
Well, what happens with an completely cleared out checkbox field? Nothing is posted/submitted. Again, Domino doesn't clear it out (or didn't prior to the fix highlighted by Jake).
Thanks for the news that this is taken care of in 6.5.5 & 7 Jake. I presume the same is true of radio buttons (clearing those requires JS... ;-)
@ Rod
Quite right.... but why exactly it uses JS to handle web translation of action buttons I don't know and would like to figure out the details of.
Looking at the way Struts works, I *suspect* it has to do with the way commands are recieved by the server. Two different technologies, but perhaps they both ran into the same problem. If Domino had chosen to deliver two action buttons on the same form via HTML, there would be no easy way to know which was doing the submitting. Having a _doClick function seems to allow the proper formatting of the form as you submit it from one action or another, or perhaps it bypasses a submit altogether in certain instances.
More reasons it would be really nice if Domino were open source. Guess is all we can do (apart from tediously reverse engineering, which I'll leave to Master Jake.).
@jake
here is a notes developer domain discussion:
{Link}
The original 6.x fix had the problem that it couldn't tell the difference between a field that has nothing checked and a field that was hidden from the web. (I think this showed up as hidden listbox field getting reset to its default value.)
The %%Surrogate fixes that. If I recall, the value does not matter.
I'm coming across a problem in Notes 7 using the original workaround of adding a hidden input field to form for clearing out radio button choices. If you add more than one radio button to your form the radio button field value is never saved (even when you remove the JavaScript to uncheck the values).
I've tried it out in the R5 client on a R6 server and it works OK.
Another side-effect is caused by the fact that the %%Surrogate fields have type=hidden. This seems to cause problems for CSS - It closes whatever div is currently open.
Anyone else seen this?
Thanks!! Saved me.
I find another strange behaviour. I use Lotus Domino 8.5.1
I create a form with some fields and a dialog list.
Every field is required in the form.
I try to validate fields upon submission via javascript.
With IE javascript seems not to read dialog list field (it's the same with listbox), while everything goes well with text or numeric fields.
I find that document.forms[0].dialogboxfieldname.value returns always ""
No problems at all with Firefox and GoogleChrome.
Any help?
@ Enzo - if on the web, you'll find dialog lists get converted to <select> elements containing <option> elements. You'll want to understand the DOM / Javascript object model for these elements to properly validate them.
check out http://devguru.com for Javascript documentation which should help.
Thank you Jerry ... I've solved the problem allowing keyword synonyms and formatting correctly the input choices ("value1 | value1 : ...")
... the strangeness (but probably not so strange) is that I've found that problem only with IE
Hi,
I have created a web form with some fields and submit button. I have also created a client form with the same fields to store the web documents value. But when I submit the form in the web the values are not getting submitted in the notes database. The document is been created but doesn't have values in it. I am using .submit() function of java-script to submit the values in web.
This happens only in IE. It works fine in FireFox and Google Chrome.
Thanks in advance for your help.