IBM®
Skip to main content
    Country/region select      Terms of use
 
 
   
     Home      Products      Services & solutions      Support & downloads      My account     

developerWorks  >  Lotus  >  Forums & community  >  Best Practice Makes Perfect

Best Practice Makes Perfect

A collaboration with Domino developers about how to do it and how to get it right in Domino

There seems to be a widespread misconception among novice developers that a document retains some magical connection to the form that was used to create it, so that when they -- let us say -- add a computed field to the form, they expect the computed value to start showing up in views without their doing anything more. I responded to some such person in the 6&7 forum this morning, and I also wrote a bug report for the help folks, suggesting the addition of the following text to the Designing a Form help document:

NOTE: Making a change to a form (adding a field, for instance) does not have any effect on documents previously created with that form. The new field will not be added to existing documents and will not appear in views. Only when you edit and save a document, will the value of the new field be added to it; or, you can write an agent to set the new field in existing documents.

Likewise, when you remove a field from a form, this does not remove the data from your application. Even when you edit a document, if it already contains a value for which there is no longer a field, that value will not be touched.

Sometimes people become confused about this because they add a field that is computed or has a default value, and then they open a document, and the value is already there. This occurs because, when you open a document that doesn't already contain a value for a field, Notes calculates the computed field formula or field default value and displays that value. However, the value is not stored in the document, so it doesn't appear in views, unless you edit and save the document. A view only cares about the data actually stored in the note; it does not check the form to see what fields are "supposed" to be there.

To see the true contents of a document, use the document properties dialog from a view. This will show you what's actually stored in the document note at that time. You can see whether a field value is already stored and what its value is.

I tried to clarify it in my comments on the education materials also (not done reviewing those, must resume!). Any other ideas for getting the word out? Would I be going to extremes if I put in a message the first time you saved a form where there are already existing documents using that form, saying the above briefly with a "don't tell me again" checkbox?

Andre Guirard | 23 July 2007 12:36:47 PM ET | Café Porch, Plymouth, MN, USA | Comments (16)


 Comments

1) how about making it work as expected (rather than designed)?
Charles E. Robinson | 7/23/2007 2:46:30 PM

This has always driven me nuts. The break between documents and data notes is an arcane technical point that many people don't get until using Notes for quite a while. Even when you do, all that gives you is the knowledge of how to make it do what you thought it should do in the first place. [An agent isn't necessary, by the way. You can also use a view action with @Command[ToolsRefreshAllDocuments]).]

The message you suggest would be a good start, but it could be much better. How about giving the option to refresh all the documents in the database so the field is populated (for computed fields), or ask if the user wants to add it with a default value (editable fields). That would be truly useful and make Notes work as most people would expect. :-)

2) Not always a bad thing...
Dave Armstrong | 7/23/2007 4:43:09 PM

When I train new developers, I always start with exactly this point. A form != A document. I start with the idea that a Notes database contains collections of field/value pairs -- Documents, which are created, viewed, and edited via a Form.

But I don't find this to be a bad thing, or unintuitive at all. At least not from a technical view. I can see why end users get confused, but ever since n-tier became a buzzword, separating data from UI has been a good practice. I just roll with it and take advatage of it where I can.

3) Warning message a good idea...
Kevin Pettitt | 7/23/2007 9:21:58 PM

typing 1 handed but wanted to at least say yes a form save message (or on opening) warning of this issue (w/ don't show again checkbox) is a great idea.

4) Update documentation: yes, display a message: no
Fabian Robok | 7/24/2007 8:14:24 AM

One word: Templates. When designing a template, the extra nag message would be just that: a nag. And I would not want to rely on either the file extension ntf or the master template name property to toggle this behaviour.

The option to update all existing docs created with the current form sounds like a sweet one, but after all it's not really necessary. First, it really IS easy to do that yourself (even without the comfort offered by third party tools). Second, it would make sense only, if it could deal with field deletions as well. And then, what about changing the field data types, removing options from list fields, making existing fields comuted, ...

What I would like to see in designer help is a more strict distinction between form and document (with some emphasis on the term note as the common) and between field and item. But I probably wouldn't want to be the one to rework all of the Designer help on my own ... ;-)

5) Hrm...
Nathan T. Freeman | 7/24/2007 8:23:08 AM

@1 - Charles, when you add a column to a table in Access or SQLServer, does it populate an initial value for all the existing rows? What about if you put that column on a form in Access or in some VB.Net environment?

Learning that forms != documents is the first step in someone becoming a real developer on the platform. I would encourage you to keep the two separate in as many places as possible.

God, I can just see what would happen if you were to auto-populate the field. Some fool would add field to a form on a db with 100,000 docs, and populate it with the results of some @DbLookup. Which would lock their machine for 4 hours, then create a replication ripple effect on 200 servers for a week, then require massive view rebuilds on every one of those 200 servers.

And you know who'd get blamed? Notes.

6) Design vs Data
Sean S Burgess | 7/24/2007 8:25:44 AM

I had the relationship between forms and documents explained to me early in my Notes career in this way:

Notes Databases keep design (forms) separate from data (documents). Forms are used to view the data in documents in a structured manner. Only data that is in fields that exist on both the form and the document will show up when viewing a document using a specific form.

What really blows n00bies' minds is when you try to explain to them that documents can have fields that don't exist on any form in the database and never have.

7) no, but I wish they did
Charles E. Robinson | 7/24/2007 1:04:29 PM

One of Andre's stated goals is to increase developer slack. By asking "do you want to update documents using this form" it lets me focus on creating the solution rather than doing administrivia.

Yes, I can work around the issue easily. So can you and everyone else reading this blog. I just think a relatively simple change could make it easier for new developers and existing ones alike. I've been wrong before so I'm likely wrong this time, too.

8) I’m with NTF on this one
Doug Finner | 7/24/2007 2:38:10 PM

Back in, oh my god, like '78 I was working with a system that allowed you to create report forms from 'the big pile of all possible fields' - kinda like forms vs documents. This isn't new and I sure as all get out don't want Note taking it upon itself to update my data all by itself. I currently work in a regulated environment and that falls into the bucket called 'bad stuff'...I don't even want Notes to THINK about updating my data - EVER...sure as shootin' some non-FDA programmer's not gonna understand that we need things like audit trails and content approval processes and is just going to say 'sure, update all my docs'. Like I said, bad.

I like the way I can display any bucket of data in any layout/form - that is wicked cool and I'll take total ownership of getting the data fixed the way I like.

9) Help update - sure. Designer change - no thanks.
Mike VandeVelde | 7/24/2007 4:38:56 PM

Any extra help you can give to people in the documentation is great. (while you're in there, how about adding mention of the &ParentUNID parameter for the ?SaveDocument URL command?)

Any extra 'features' you can add to Designer had better be useful, and none of the message boxes through to automatic updating mentioned so far sound useful to me. Well I suppose you could call them useful for certain people, but to anyone who knows better it would just be annoying, even if you could turn it off. And once certain people had seen it, it would be annoying to them as well. I'd call it bloat!

The separation between data documents and design documents should be a fundamental piece of knowledge required to start developing Notes applications (again, making this clearer in the documentation is a good idea). Data documents exist regardless, they don't even need a form, a form is just a tool used to view/edit documents. That's basic, I vote no for having the IDE do anything extra to drill it into my head.

10) For the record Charles...
Nathan T. Freeman | 7/24/2007 5:11:05 PM

I see that I came across a bit acerbic on my response. Didn't mean to single you out there. I had a toothache & dentist appointment this morning, so I was WAY out of sorts. :-)

Anyway, wasn't trying to be mean. It's not that your proposal was bad. I just fear the consequences. I fear the consequences of anything that makes Domino development somehow more "accessible" because I think the problem with Domino in its early days was that too many BAD apps were built, deployed and used for years.

But that's just me.

11) Updating Docs
Kerr | 7/25/2007 7:01:33 AM

OK, who's going around updating forms in production? Hands up.

Go to Worst Practices. Do not pass Go. Do not Collect $200.

Otherwise, what's the point in automatically updating docs? Your going to have to write something to update prod. Of course a nice utility for building data refactoring scripts would be cool. Especially something that could be triggered by a design update.

12) I do it all the time
Nathan T. Freeman | 7/25/2007 10:11:02 AM

There are very good reasons for doing this. In fact, it's a GREAT troubleshooting method in places where you have templates applied. Make a change directly to the form to debug your problem, then apply the fix to the template and let it cascade down.

Updating in production is done all the time. It's called "using the application." The fact that a user updates data and I update code is irrelevant. In fact, I'm quite confident that in most cases, I can more reliably modify code than they can data.

And fortunately, I know the difference between when I'm doing something complicated and when I'm doing something risky. Not every code change carries risk, and adding a field to a form is a GREAT example of something that's low-risk in Notes.

13) I don’t
Dave | 7/25/2007 12:26:50 PM

Nathan,

YOU may know what is low risk, and OK to do in production. But the management I've worked for has rarely been able to make that distinction. So while you and I may know that updating production is risk-free, in a highly formalized IT shop, it gets the management all a-twitter, and just wait for that one time you make a mistake, and they come railing at you for Worst practices, or just the old stadby of "Notes sucks."

So for political and even marketing reasons, if not technical, I follow the larger IT Best Practice of never updating production. And even in the Notes world, this does reduce production problems.

14) OK
Nathan T. Freeman | 7/25/2007 2:33:16 PM

Why is it everytime lately I try to get people away from their existing biases, they take it as an attack? *sigh*

15) no worries
Charles Robinson | 7/25/2007 3:36:07 PM

Nathan - Thanks for the apology. My skin is thickening. :-) I hear you on the possible impact, and I agree that it could lead to laziness and undesired impact. It was an off the cuff suggestion that I made because Andre was halfway down that path already by acknowledging that there are some common actions many people may want to take when adding new fields to a form. Since he broached the subject I just wanted to toss out the idea of taking it all the way to its logical conclusion rather than stopping 80% of the way. It may not make sense to do it, and it may not even be possible.

16) Not an attack...
Dave | 7/25/2007 6:08:05 PM

I hope that wasn't directed at my response to you. I wasn't attacking in the slightest. Just pointing out a different perspective. I agree with you in principle, but have reasons to act differently in practice.

No attacks. Just replies. Don't sweat it. :)

17) Like the idea of a prompt with a disable checkbox, but...
Erik Brooks | 7/27/2007 8:59:35 AM

@1 - What you describe would make Notes "work as most people expect," but only some of the time. Under other cirumstances (adding a field to a computed subform), etc. Designer would have a field day just trying to determine what docs were potentially affected. It's not a complete solution, and would just add another layer to the problem.

Not to mention the cases where a document changes Forms... yikes!

What might be good, Andre, is to also add some examples in the Designer Help showing how to write an agent to populate the new field on existing docs after creating the one on the form.

Oh, and about modifying forms in production: it really is the best way to debug a form. After all, once you've found the problem you can simply refresh the design of the database to revert back to a pre-modified version right? ;-)

18) Mods in production vs mods in templates
Fabian Robok | 7/29/2007 10:31:24 AM

To me, this discussion shows merely one thing: In Domino development we usually don't have dedicated staging systems. If we did, there would be no argument about where to test certain changes.

 Add a Comment
Subject:
   
Name:
Comment:  (No HTML - Links will be converted if prefixed http://)
 
Remember Me?     Cancel

Search this blog 

Disclaimer 

    About IBM Privacy Contact