9780764526114 chapter 4 application building blocks

8/14/2019 9780764526114 Chapter 4 Application Building Blocks

1/14

Lotus Notes and Domino 6 Programming Bibleby Brian Benz, Rocky Oliver and Richard SchwartzWiley Publishing, Inc.. (c) 2003. Copying Prohibited.

Reprinted for Satyendra K. Jha, [email protected]

Reprinted with permission as a subscription benefit of Books24x7,http://www.books24x7.com/

All rights reserved. Reproduction and/or distribution in whole or in part inelectronic,paper or other forms without written permission is prohibited.
http://www.books24x7.com/http://www.books24x7.com/


2/14

Table of ContentsChapter 4: Application Building Blocks........................................................................................1

Introducing Design Elements.................................................................................................1User Interface Elements........................................................................................................1

Forms...............................................................................................................................2Forms and documents.....................................................................................................3Forms in Notes versus forms in browsers........................................................................5Subforms..........................................................................................................................6Pages...............................................................................................................................6Special pages...................................................................................................................7Views and folders.............................................................................................................7

Navigation Elements..............................................................................................................7Framesets........................................................................................................................7Outlines............................................................................................................................8Navigators........................................................................................................................8

Shared Code Elements..........................................................................................................8Agents................................................... ...........................................................................8Script libraries..................................................................................................................8Shared fields....................................................................................................................9Shared actions.................................................................................................................9

Shared Resource Elements...................................................................................................9Stylesheets................................................... ..................................................................10Shared Applets...............................................................................................................11Images...........................................................................................................................11Files................................................................................................................................11Data Connection Resources..........................................................................................12

Summary..............................................................................................................................12

i


3/14

Chapter 4: Application Building BlocksBy Rocky Oliver

Domino databases are comprised of data, and many design elements enable you to buildapplications that work with that data. Over the years, more of these design elements, such asWebenabled databases, data integration, and so on, have been added to the database structure to

support the everchanging demands of the market. This chapter introduces you to these applicationbuilding blocks, providing a brief introduction to each element.

Introducing Design Elements

Design elements are what you use to construct applications. You can use design elements topresent data to a user in the Notes client, on the Web, or both. You can use design elements tomanipulate data; you can also use them to navigate through your application so users can find thefunctionality or data they need. This chapter breaks down these fundamental building blocks intofour major areas:

User interface elements

Navigation elements

Code elements

Resource elements

This chapter should give you an idea of what these elements are, how they are used, and how theycan help you build great applications. Other chapters later in the book describe how you get the

most out of these elements.

User Interface Elements

User Interface elements are data entry and display elements that you use to provide your users withthe ability to manipulate the data in your application. You can use these elements for other reasons,but their primary use is to enable your users to view or manipulate your data. The following designelements are considered User Interface elements:

Forms

Subforms

Pages

Views and Folders

Reprinted for [email protected], IBM John Wiley & Sons (US), Wiley Publishing, Inc. (c) 2003, Copying Prohibited


4/14

Forms

A formis a design element that acts as a lens for viewing or modifying information in a document. Aform is a collection of other elements used for showing or modifying data. These other elements canbe a variety of things, such as fields, buttons, embedded views, subforms, embedded objects,hotspots, and so on. A form in the Notes/Domino world is similar to a form used in the paper world a structured interface, comprised of many smaller elements organized in a consistent fashion,used to prompt users to input data in a structured format. The next two sections review some of the

most common elements used in a form.

Fields

A fieldis a design element used to present or modify a particular piece of data from a document.Fields can collect a wide array of data types, including the following:

Authors/Readers: This field determines who can edit or read a document. It can also be akeyword field that enables the user to choose a name from their Personal Address book orthe Domino Directory.

CheckBox/Radio Button: This keyword field enables the user to choose one item (radio

button), or one or more items from a list (check box).

Color: A Color field displays a color picker dialog box when the user selects the field (seeFigure 41), and returns the hexadecimal value of the chosen color.

Figure 41: The Color field enables you to provide a color picker for your users. The colorpicker shows the Web palette to the user, or enables the user to choose the RGB colorvalues.New Feature The Color field type is new in Notes/Domino 6.

ComboBox: This keyword list field shows a single value at a time, or shows the whole list

if you click the Helper button.

Date/Time: This field displays a perpetual calendar picker and returns the date chosen bythe user.

Dialog List: This keyword list field displays the choices in a dialog box.

Formula: This field enables the user to enter and validate a formula.

ListBox: This keyword list field shows the list of values directly on the form.

Lotus Notes and Domino 6 Programming Bible 2



5/14

Names: This field displays a concatenated name as an abbreviated name. It can also be akeyword field that enables the user to choose a name from their Personal Address book orthe Domino Directory.

Number: This field enables the user to enter a number, formatted as desired (fixed,currency, and so on).

Password: This field enables a user to enter text into a password field, and the text isobscured by asterisks (*).

Rich text, rich text lite: A rich text field is a container within the form element. A richtextitem can contain almost anything, including text, pictures, attachments, embedded objects,and so on. Rich text lite fields are similar to rich text fields, but the developer can limit whatthe field can contain.New Feature Rich text lite fields are new in Notes/Domino 6.

Text: This field enables the user to enter text.

Time Zone: This field enables the user to choose a time zone from a list of the world's timezones.New Feature Time Zone fields are new in Notes/Domino 6.

Buttons, action buttons, action hotspots

A button, action button, or action hotspot enables a user to execute a predefined action. A buttonisa little gray box that can have a text label, an action buttonis part of the form design and appears at

the top of the form, and an action hotspotenables the user to specify that text or a graphic acts as abutton when the user clicks it.

You can add many other items to a form, some of which are covered later in this chapter. Refer toChapter 5 for more detail.

Forms and documents

In the previous sections, you may have noticed a distinction between the use of the word documentand the use of the word form this distinction is intended. Although a user may view a form and adocument as the same thing, under the hood they are quite different.

A documentis where the information of the database is stored. If you are familiar with relational

databases, a document is analogous to a record. A document is a collection of items, which arecollections of one or more individual bits of information. Items can be of various data types, such astext, rich text, number, or date/time. Documents can be main documents, response documents(documents that are children of a main document or another response document), or designdocuments (yes, even design elements are documents).


http://www.books24x7.com//viewer.asp?bkid=6059&destid=163#163http://www.books24x7.com//viewer.asp?bkid=6059&destid=163#163


6/14

Note When reading about Notes/Domino, especially the API, you may hear of documents referredto as notes. A note and a document are basically the same, except that most of the timesomeone using the word noteis referring to a design element structure.

A formis a lens, or template, for viewing, creating, or modifying information on a document. Formsdo not store data. Forms, and the fields contained on them, are simply used to view documents anditems contained in them. A form is for viewing a document, and a field is for viewing an item.

A form must always have a related document associated with it when it is opened in the UI. But adocument does not have to have any form associated with it you can create documentsprogrammatically all day long without having any form associated with them. Or a document canhave more than one form associated with it maybe a supervisor views a document with adifferent form, which gives her more options or displays more information to her, than a normal usersees using his related form viewing the same document.

The separation of application and data is an important concept to grasp, not only for Notes/Dominodevelopment, but also for development in general. One of the most powerful features ofNotes/Domino is that while there is a logical separation of application functionality and data, there isa physical connection in that it is all stored in one physical file. This makes Notes/Domino objectseasily maintainable and portable.

A profile document is a special breed of document that doesn't behave like a normal document. Aprofile documentis a special document that is normally used to cache semistatic data in adatabase. Profile documents have some peculiar properties that set them apart from a regulardocument:

Profile documents can't be listed in a view or folder.

Profile documents aren't normally part of a NotesDocumentCollection.

Profile documents don't show up in the database document count.

Profile documents don't respect replication/save conflicts; they act like a design element inthat the last one saved wins.

Profile documents are extremely useful for storing information that needs to be readily available butdoesn't change often. Some uses of profile documents include specific user profile information,keywords that don't change much (for example, state abbreviations), or application functionality information that needs to be globally available.

Two types of profile documents exist: general profile documents and uniquekeyed profiledocuments. A general profile document has a name that identifies it this name is the name of theform you use to present it to a user for modification. Only one profile document in a database canuse a name. You can, however, add an optional unique key to a profile, and then you can havemultiple profiles based on the same (form) name. But even then only one profile can exist for eachname/key combination. The ability to store a profile with a unique key can be useful to store profilesfor particular application functions, or by user name.

Profile documents are useful for storing cached information, because they can be accessed quickly,especially if the information you're retrieving is normally stored in another database. Suppose, forexample, that you centralized all your keywords and configuration documents in a central controldatabase. Normally, you must perform a lookup to the other database to get the neededinformation. Performing the lookup can be expensive, timewise, because you are going from onedatabase to another. Instead, you could push this information into one or more profile documents inthe database at the time that the keyword or configuration information is saved, and then you wouldhave that information available to you locally. Many LotusScript, Java, and Formula methods are




7/14

available for getting to profile information to make your code even more streamlined. For moreinformation on profile documents, refer to the Domino 6 Designer help.

Forms in Notes versus forms in browsers

A form is like two design elements in one a form design element that is useful in a Notes client,and a form design element that is useful in a Web browser. Some of the functionality overlaps, butsome of it is designed for one specific client. Figure 42 shows the various events and areas

available in an example form.

Figure 42: Many events and areas are available for both Web functionality and Notes functionalityin a form design element.The items with little diamonds by them are Formulabased areas. You can use most of these in theNotes or browser client, except for the WebQueryOpen and WebQuerySave events. You can usethese two areas to list formula code, usually in the form of @Command([ToolsRunAgent]), which isexecuted right before a document is loaded into the browser or right before a document is saved tothe server from a browser. These areas with names that start with HTML HTML Head Contentand HTML Body Attributes are used to compute HTML, using the Formula language, which youcan use for the HTML head and body areas of a Web document.

The little circles indicate JavaScript events that are a part of the form object. You can use four ofthese JavaScript events onHelp, onLoad, onUnload, and onSubmit in both the Notes client




8/14

and the Web browser. The little curled document icons indicate events that fire in the Notes client.These events can contain LotusScript, Formula, or JavaScript. These events do not fire in a Webbrowser.

Many design elements used on a form are useful in both client types. If you design your forms right,you can use the same form for both the Web browser and the Notes client. A new feature inNotes/Domino 6 makes this even easier the ability to have Webspecific and Notesspecificcode in the same area. Figures 43 and 44 show how this is achieved, and what it looks like.

Figure 43: The onLoad event of this form has an @function that fires when the client loads.The little circle indicator to the left of onLoad is twocolored. This means that there is code for boththe browser and Notes clients in this event. Figure 43 shows the @function code that fires whenthe form loads into the Notes client.

Figure 44: The onLoad event of this form also has a JavaScript alert function that fires when theform loads into a Web browser.Figure 44 shows that, in the same event, there is also a JavaScript alert that fires when the sameform is loaded into a Web browser. Now you can have the same form used for both Web browserand Notes clients much more easily than in past releases.

Subforms

Subformsare parts of a form that you can insert into a form. A subform enables you to have thesame part of a form available to multiple forms, thereby allowing you to create it once and use it inmultiple places. You can even dynamically load subforms into a form based on an @function.

Tip Don't overuse subforms. Using shared resources, especially subforms, has a speed cost.Subforms are heavy and take a bit of effort to load. They are useful, but the speed hit becomesworse with each additional subform you use in the same form.

Pages

Pages are similar to forms, with a couple of exceptions. The main difference is that pages are notrelated to documents. Because pages are not related to documents, pages are not allowed to havefields on them. Pages are mainly used to create navigation elements for your databases, as well asfor embedded view display. Pages are especially useful as PassThru HTML documents for Webapplications. You can only edit pages through the Domino Designer, so pages are design elements,not enduser elements. If your users need to modify them, you should use a document.




9/14

Tip Navigators became a deprecated element with Release 5, which means that you shouldn't usethem any more because they're no longer being updated. For future applications use pages:They provide the same functionality as navigators, and much more.

Special pages

The term special pagesrefers to using a page as a library of code. In Release 5, pages were usefulfor storing JavaScript libraries, which are normally text files with a .js extension used to storeJavaScript code. But Notes/Domino 6 now has JavaScript libraries available as a separate designelement. Pages are, however, still useful for storing one type of code library XSL stylesheets,which are text files ending in .xsl that contain XSL stylesheet code.

CrossReference You can learn more about XSL stylesheets and using pages as XSLstylesheets in Chapter 53.

Views and folders

Views and folders are design elements used to organize documents. Think of them as a table ofcontents (view) or bookmarks you use in a book (folder). In a table of contents, you expect to seethe pages of the book listed in order. A view is like a table of contents on steroids the developercan specify any order for displaying the documents, the view can be filtered to show a subset ofdocuments, documents can be opened from a view, and in Notes/Domino 6 you can edit adocument as it's listed in a view.

Views also extend the table of contents metaphor by introducing the concept of categorization. Youcan cause documents to be grouped by like values, creating categories for each value. Acategorized view is like an index to a book you want to know all the documents that pertain toTriumph Motorcycles, so you go to the index and look up the word Triumph, where it lists fourdocuments. The same concept applies to a categorized view, except that you look for the categoryTriumph Motorcycles, and you can expand the category to see all the documents that had that valuein the specified field in the view.

Folders are similar to views in that they are designed the same, work the same, can do the samethings, and so on. The major difference is that folders, unlike views, do not automatically displaydocuments based on selected criteria (known as a selection formula). Instead, folders contain a tagthat tells them what folder(s) to show up in. Users normally add documents to folders, butoccasionally developers place documents into folders by programmatic means.

Navigation Elements

A Domino developer uses three main elements to provide application navigation to her users:framesets, outlines, and navigators.

Framesets

Framesets were introduced in Release 5 and are similar to the framesets used in browserbasedapplications. Framesetsenable the developer to quickly create a framed user interface withoutknowing complex code. The frameset appears in the Designer as an element instead of code, whichmakes it much easier to adjust as needed. Framesets work as well in a Web browser as they do ina Notes client. The contents of frames in a frameset can be pages, views/folders, forms, Notes links(such as document links, view links), or an external Web page URL. The contents can also bedynamically determined by formula at runtime. You can also control the appearance of the bordersof a frameset during design time.


http://www.books24x7.com//viewer.asp?bkid=6059&destid=2041#2041


10/14


11/14

New Feature Java libraries and JavaScript libraries are new to Notes/Domino 6.

Script libraries store subroutines and functions and make them available to other design elementsthroughout your database. These script libraries are referenced in other design elements by using aUse statement in the (Options) area of the code. If, for example, you have a script library called

UtilityLibrary, you could make it available to a form by using the following statement:

Use "UtilityLibrary"

All the code in the library is immediately available to the elements of the form for use.

The great thing about script libraries is that they make your code much easier to maintain. Supposethat you have a function that you use in 14 different places in your application. You place thatfunction in each area by copying and pasting it. A week after deploying the application, you find abug in the function. Now you have to go to all 14 areas and correct the code opening yourself upto making a typographical error in one or more places, causing even more headaches. Contrast thiswith placing the function in a Script Library. You reference the script library in the 14 places whereyou need it. When that bug is found, you simply correct it in the script library, and it's automaticallycorrected everywhere it is used.

Shared fields

Shared fieldsenable you to design a field in one place and use it in many places. While this maysound like a good thing, shared fields can be troublesome. Any time you use a shared resource,such as a shared field, shared action, script library, and so on, you trade a bit of code reusabilityand maintenance for a speed hit. It's a "pay me now or pay me later" proposition. In some sharedelements, the tradeoff is worth it: Script libraries, for example, are extremely useful. The tradeoff ofthe speed hit for the reuse provided by shared fields is debatable. Exceptions to this rule exist, butit's generally recommended that you not use shared fields.

Shared actions

Shared actionsare similar to other shared elements in that they enable you to create a single actionthat can be used in multiple forms, views, or folders. Shared actions have the same drawbacks asshared fields, but not to the extent of shared fields. Shared actions can be useful in designingapplications, especially in those applications that have complex actions. It's much more efficient,however, to place the code you would have had in the shared action into an agent, and then call theagent with a simple @Command([ToolsRunMacro]). You get the benefit of centralized, shared code(the agent) without the extra weight and speed degradation of a shared action.

Shared Resource Elements

Like shared code elements, shared resource elements are designed to be stored in one place and

be available for use in multiple places. The major difference between a shared code element and ashared resource element, however, is that shared code elements are programmatic Notes/Dominoelements, and shared resource elements are externally created objects that are made available toother elements. These elements are typically files of some type, such as graphics, Java classes,and so on. While these elements also have the usefulness versus speed dilemma of shared codeelements, the price you pay in speed is worth the advantages you get by using shared resourceelements. Some of these benefits include the following:

Portability: These elements must be on the file system if they aren't shared resources. Byplacing them in the database, they replicate just like other design elements.




12/14

Ease of access: These elements are referenced simply by name because they areavailable as a part of the same object store.

You should use these shared resources whenever you need this type of item in your databasedesign.

You can reference and use any of these resources in the same way. Simply choose Create Resource Insert Resource, and then choose the type of resource you want to insert. The InsertResource dialog box appears, as shown in Figure 45.

Figure 45: The Insert Resource dialog box is a handy way to access all available shared resourceelements in the current database or other databases.

New Feature One of the most exciting new features in Notes/Domino 6 is the ability touse resources from other databases in your current database. If you look at

the Insert Resource dialog box shown in Figure 45, you see the combobox at the top that enables you to choose the current database or otherdatabases for selecting the desired shared resource.

Stylesheets

Stylesheetscontrol the presentation of your documents. Usually associated with Webbasedapplications, stylesheets are now used to control the appearance of documents displayed in theNotes client as well.

To add stylesheets to your application design, you simply choose Shared Resources StyleSheets, click the New Style Sheet Resource button, and find your CSS file on your file system. Thefile is then imported into your database design. Use the Properties box of the stylesheet to name it.You can add a stylesheet to your design element, such as a page or form, by using the method




13/14

described at the beginning of this section: Create Resource Insert Resource.

New Feature Stylesheets are a new resource element in Notes/Domino 6.

Shared Applets

Although this resource is called an applet, it really means any Java class whether it's stored in aclass, .jar, archive, or resource type file. You can add applets to your application by choosing

Shared Resources Applets, clicking the New Applet Resource button, and selecting the Javaresource files that you need. Figure 46 shows the Locate Java Applet Files dialog box.

Figure 46: The Locate Java Applet Files dialog box enables you to choose Java resource files toadd to your application.New Feature Shared applets are a new resource element in Notes/Domino 6.

Images

Image resources have been around since Release 5. Image resources enable you to store BMP,GIF, or JPG files as a part of your database design. These images are available for use in both theNotes client and Web browser applications, in any design element that enables you to placegraphics in it.

You can add an image resource to your application by choosing Shared Resources Images, andthen clicking the New Image Resource button. A Windows common File dialog box appears, andyou can choose the graphics file(s) you want to import into your application. You can then use theProperties box to provide an alias for the image.

Besides using the method described at the beginning of this section (Create Resource InsertResource) to add a resource to your design element, you can also add an image resource bychoosing Create Image Resource and selecting the desired graphic.

Files

File resources are basically a catchall area for files you want to have as a part of your applicationthat don't fit into any other category. But if you place an HTML file here (a file with the extension




14/14

.html), it's available for insertion by using the method described at the beginning of this section(Create Resource Insert Resource).

You can add a file resource to your application by choosing Shared Resources Files, and thenclicking the New File Resource button. A Windows common File dialog box appears, and canchoose the file(s) you want to import into your application.

New Feature The files resource is a new resource available in Notes/Domino 6.

Data Connection Resources

Data Connection Resources (DCRs) enable you to define a connection to an external dataresource, and then use that DCR object in your forms to populate one or more fields with data fromthe external resource.

New Feature Data Connection Resources are new in Notes/Domino 6.

DCRs are based on the same technology as Domino Enterprise Connection Services (DECS),

except that they provide the developer a way to manage the DECS connection in the targetdatabase, without the need to use the Domino Administrator.

CrossReference For more information on using DCRs, please refer to Chapters 43 and 44.

Summary

This chapter provided you with a quick review of the various application building blocks available inLotus Notes/Domino. These design elements were broken down into functional areas:

User interface elements: These elements include forms, subforms, pages, views, andfolders. These elements are used to interact with the user, and allow her to work with thedata stored in the database.

Navigation elements: These elements include framesets and outlines, which can be usedto easily provide the ability to locate information in your application, either through a Webbrowser or the Notes client.

Shared code elements: Shared resource elements include script libraries, shared fields,and shared actions. Shared code elements allow you to write your code once and use it inmultiple places in your application.

Shared resource elements: There are quite a few shared resource elements, includingimage resources, Cascaded Style Sheets, file resources, and so on. These elements allowyou to maintain all of the items needed for your application in one object store, whichpreserves the portability of your application and makes it easier to maintain.

You build applications that solve you customer's needs by using the powerful design elementscovered in this chapter. From here we move on to Part II, Domino Designer. The chapters there willintroduce you to the Domino Designer, and how you can use it to develop worldclass Dominoapplications exploiting the design elements covered here.


http://www.books24x7.com//viewer.asp?bkid=6059&destid=160#160http://www.books24x7.com//viewer.asp?bkid=6059&destid=1657#1657http://www.books24x7.com//viewer.asp?bkid=6059&destid=1614#1614