Chapter 4 Application Building Blocks

Lotus Notes and Domino 6 Programming Bible
by Brian Benz, Rocky Oliver and Richard Schwartz

Wiley Publishing, Inc.. (c) 2003. Copying Prohibited.
Reprinted for Satyendra K. Jha, IBM

satyejha@in.ibm.com
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 in

electronic,paper or other forms without written permission is prohibited.
i
Table of Contents
Chapter 4: Application Building Blocks........................................................................................1
Introducing Design Elements.................................................................................................1
User Interface Elements........................................................................................................1
Forms...............................................................................................................................2
Forms and documents.....................................................................................................3
Forms in Notes versus forms in browsers........................................................................5
Subforms..........................................................................................................................6
Pages...............................................................................................................................6
Special pages...................................................................................................................7
Views and folders.............................................................................................................7
Navigation Elements..............................................................................................................7
Framesets........................................................................................................................7
Outlines............................................................................................................................8
Navigators........................................................................................................................8
Shared Code Elements..........................................................................................................8
Agents..............................................................................................................................8
Script libraries..................................................................................................................8
Shared fields....................................................................................................................9
Shared actions.................................................................................................................9
Shared Resource Elements...................................................................................................9
Stylesheets.....................................................................................................................10
Shared Applets...............................................................................................................11
Images...........................................................................................................................11
Files................................................................................................................................11
Data Connection Resources..........................................................................................12
Summary..............................................................................................................................12
Chapter 4: Application Building Blocks
By Rocky Oliver
Domino databases are comprised of data, and many design elements enable you to build
applications that work with that data. Over the years, more of these design elements, such as
Web−enabled databases, data integration, and so on, have been added to the database structure to
support the ever−changing demands of the market. This chapter introduces you to these application
building 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 to
present data to a user in the Notes client, on the Web, or both. You can use design elements to
manipulate data; you can also use them to navigate through your application so users can find the
functionality or data they need. This chapter breaks down these fundamental building blocks into
four 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 they
can 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 with
the 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 design
elements are considered User Interface elements:
• Forms
• Subforms
• Pages
• Views and Folders
Reprinted for ibmsatyejha@in.ibm.com, IBM John Wiley & Sons (US), Wiley Publishing, Inc. (c) 2003, Copying Prohibited
Lotus Notes and Domino 6 Programming Bible 2
Forms
A form is a design element that acts as a lens for viewing or modifying information in a document. A
form is a collection of other elements used for showing or modifying data. These other elements can
be 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 field is 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 a
keyword field that enables the user to choose a name from their Personal Address book or
the 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 (see
Figure 4−1), and returns the hexadecimal value of the chosen color.
Figure 4−1: The Color field enables you to provide a color picker for your users. The color
picker shows the Web palette to the user, or enables the user to choose the RGB color
values.
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 by
the 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.
• Names: This field displays a concatenated name as an abbreviated name. It can also be a
keyword field that enables the user to choose a name from their Personal Address book or
the 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 is
obscured by asterisks (*).
• Rich text, rich text lite: A rich text field is a container within the form element. A rich−text
item 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 what
the 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 time
zones.
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 button is
a little gray box that can have a text label, an action button is part of the form design and appears at
the top of the form, and an action hotspot enables the user to specify that text or a graphic acts as a
button when the user clicks it.
You can add many other items to a form, some of which are covered later in this chapter. Refer to
Chapter 5 for more detail.
Forms and documents

In the previous sections, you may have noticed a distinction between the use of the word document
and the use of the word form — this distinction is intended. Although a user may view a form and a
document as the same thing, under the hood they are quite different.
A document is 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 are
collections of one or more individual bits of information. Items can be of various data types, such as
text, 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 design
documents (yes, even design elements are documents).
Note When reading about Notes/Domino, especially the API, you may hear of documents referred
to as notes. A note and a document are basically the same, except that most of the time
someone using the word note is referring to a design element structure.
A form is a lens, or template, for viewing, creating, or modifying information on a document. Forms
do not store data. Forms, and the fields contained on them, are simply used to view documents and
items 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 a
document does not have to have any form associated with it — you can create documents
programmatically all day long without having any form associated with them. Or a document can
have more than one form associated with it — maybe a supervisor views a document with a
different form, which gives her more options or displays more information to her, than a normal user
sees using his related form viewing the same document.
The separation of application and data is an important concept to grasp, not only for Notes/Domino
development, but also for development in general. One of the most powerful features of
Notes/Domino is that while there is a logical separation of application functionality and data, there is
a physical connection in that it is all stored in one physical file. This makes Notes/Domino objects
easily maintainable and portable.
A profile document is a special breed of document that doesn't behave like a normal document. A
profile document is a special document that is normally used to cache semistatic data in a
database. Profile documents have some peculiar properties that set them apart from a regular
document:
• 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 in
that the last one saved wins.
Profile documents are extremely useful for storing information that needs to be readily available but
doesn'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 unique−keyed profile
documents. A general profile document has a name that identifies it — this name is the name of the
form you use to present it to a user for modification. Only one profile document in a database can
use a name. You can, however, add an optional unique key to a profile, and then you can have
multiple profiles based on the same (form) name. But even then only one profile can exist for each
name/key combination. The ability to store a profile with a unique key can be useful to store profiles
for 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, for
example, that you centralized all your keywords and configuration documents in a central control
database. Normally, you must perform a lookup to the other database to get the needed
information. Performing the lookup can be expensive, time−wise, because you are going from one
database to another. Instead, you could push this information into one or more profile documents in
the database at the time that the keyword or configuration information is saved, and then you would
have that information available to you locally. Many LotusScript, Java, and Formula methods are
available for getting to profile information to make your code even more streamlined. For more
information 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, but
some of it is designed for one specific client. Figure 4−2 shows the various events and areas
available in an example form.
Figure 4−2: Many events and areas are available for both Web functionality and Notes functionality
in a form design element.
The items with little diamonds by them are Formula−based areas. You can use most of these in the
Notes or browser client, except for the WebQueryOpen and WebQuerySave events. You can use
these two areas to list formula code, usually in the form of @Command([ToolsRunAgent]), which is
executed right before a document is loaded into the browser or right before a document is saved to
the server from a browser. These areas with names that start with HTML — HTML Head Content
and HTML Body Attributes — are used to compute HTML, using the Formula language, which you
can 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 of
these JavaScript events — onHelp, onLoad, onUnload, and onSubmit — in both the Notes client
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 Web
browser.
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 in
Notes/Domino 6 makes this even easier — the ability to have Web−specific and Notes−specific
code in the same area. Figures 4−3 and 4−4 show how this is achieved, and what it looks like.
Figure 4−3: 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 two−colored. This means that there is code for both
the browser and Notes clients in this event. Figure 4−3 shows the @function code that fires when
the form loads into the Notes client.
Figure 4−4: The onLoad event of this form also has a JavaScript alert function that fires when the
form loads into a Web browser.
Figure 4−4 shows that, in the same event, there is also a JavaScript alert that fires when the same
form is loaded into a Web browser. Now you can have the same form used for both Web browser
and Notes clients much more easily than in past releases.
Subforms
Subforms are parts of a form that you can insert into a form. A subform enables you to have the
same part of a form available to multiple forms, thereby allowing you to create it once and use it in
multiple 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 becomes
worse 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 not
related to documents. Because pages are not related to documents, pages are not allowed to have
fields on them. Pages are mainly used to create navigation elements for your databases, as well as
for embedded view display. Pages are especially useful as Pass−Thru HTML documents for Web
applications. You can only edit pages through the Domino Designer, so pages are design elements,
not end−user elements. If your users need to modify them, you should use a document.
Tip Navigators became a deprecated element with Release 5, which means that you shouldn't use
them 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 pages refers to using a page as a library of code. In Release 5, pages were useful
for storing JavaScript libraries, which are normally text files with a .js extension used to store
JavaScript code. But Notes/Domino 6 now has JavaScript libraries available as a separate design
element. 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.
Cross−Reference You can learn more about XSL stylesheets and using pages as XSL
stylesheets in Chapter 53.
Views and folders

Views and folders are design elements used to organize documents. Think of them as a table of
contents (view) or bookmarks you use in a book (folder). In a table of contents, you expect to see
the pages of the book listed in order. A view is like a table of contents on steroids — the developer
can specify any order for displaying the documents, the view can be filtered to show a subset of
documents, documents can be opened from a view, and in Notes/Domino 6 you can edit a
document as it's listed in a view.
Views also extend the table of contents metaphor by introducing the concept of categorization. You
can cause documents to be grouped by like values, creating categories for each value. A
categorized view is like an index to a book — you want to know all the documents that pertain to
Triumph Motorcycles, so you go to the index and look up the word Triumph, where it lists four
documents. The same concept applies to a categorized view, except that you look for the category
Triumph Motorcycles, and you can expand the category to see all the documents that had that value
in the specified field in the view.
Folders are similar to views in that they are designed the same, work the same, can do the same
things, and so on. The major difference is that folders, unlike views, do not automatically display
documents based on selected criteria (known as a selection formula). Instead, folders contain a tag
that tells them what folder(s) to show up in. Users normally add documents to folders, but
occasionally 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 browser−based
applications. Framesets enable the developer to quickly create a framed user interface without
knowing complex code. The frameset appears in the Designer as an element instead of code, which
makes it much easier to adjust as needed. Framesets work as well in a Web browser as they do in
a 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 be
dynamically determined by formula at runtime. You can also control the appearance of the borders
of a frameset during design time.
Outlines
Outlines enable you to automatically generate a tree−based navigation system for your Domino
database. The display of an outline object can use text, graphics, colors, or a combination. You can
set an outline used in a browser to appear as a Java applet or as HTML. Domino automatically
generates the needed HTML for an outline based on the design of the outline.
You can also set outlines to automatically generate changes if the design of the application
changes. This is especially useful on sites in which the view or document structure changes
regularly, or the design is complex and changing the navigation is otherwise a pain.
But as nice as outlines are, they also have some annoying limitations — most of which center
around how the application appears. Things such as margins, some font settings, and graphics/icon
displays are somewhat limited with an outline. The recommended rule−of−thumb is that if your site
is fairly simplistic, your graphical navigation needs are minimal, and you need to get a site up fast,
use an outline. In fact, you may want to try an outline regardless of your needs. If you can, do so —
it will save you maintenance pains later. If, however, you find outlines limiting, it's probably best to
invest the time to develop an alternative navigation feature.
Navigators
Navigators are a decremented element as of Release 5 and the introduction of pages. Navigators
were introduced in Release 4 to provide the developer a navigation creation tool for developing
Notes/Domino applications. Navigators, however, have many drawbacks, so Lotus introduced
pages in Release 5 to overcome these limitations. Lotus told the development community that
navigators would continue to work, but that development effort was no longer being applied to them
and pages should be used instead.
Shared Code Elements

Shared code elements are elements where code is stored. Most of the elements described in the
following sections are considered shared code elements because they enable you to write code in
one place and use it in many places. These shared code elements include agents, script libraries,
and more.
Agents
Agents are one of the most powerful design elements in Notes/Domino. Agents (known as macros
in Release 3) are stand−alone chunks of code that can perform actions in one or more databases.
Agents are extremely powerful and flexible — a user can trigger an agent in the Notes client and in
Web−based applications, a developer can schedule an agent to run periodically, and an agent can
be triggered when a particular event happens, such as mail arrival. Agents can also be invoked
programmatically — agents can even call other agents. Agents also can work against subsets of
documents determined in a variety of ways. Agents respect the powerful security model of
Notes/Domino, and can be run as the user executing the agent or as the signer of the agent (the
person who last saved the agent).
Cross−Reference For more on agents, refer to Chapter 18.
Script libraries
Script libraries enable you to store code in one place and use it in many places. Three main types of
script libraries exist: LotusScript libraries, Java libraries, and JavaScript libraries.
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 elements
throughout your database. These script libraries are referenced in other design elements by using a
Use 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. Suppose
that you have a function that you use in 14 different places in your application. You place that
function in each area by copying and pasting it. A week after deploying the application, you find a
bug in the function. Now you have to go to all 14 areas and correct the code — opening yourself up
to making a typographical error in one or more places, causing even more headaches. Contrast this
with placing the function in a Script Library. You reference the script library in the 14 places where
you need it. When that bug is found, you simply correct it in the script library, and it's automatically
corrected everywhere it is used.
Shared fields
Shared fields enable you to design a field in one place and use it in many places. While this may
sound 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 reusability
and maintenance for a speed hit. It's a "pay me now or pay me later" proposition. In some shared
elements, the tradeoff is worth it: Script libraries, for example, are extremely useful. The tradeoff of
the speed hit for the reuse provided by shared fields is debatable. Exceptions to this rule exist, but
it's generally recommended that you not use shared fields.
Shared actions
Shared actions are similar to other shared elements in that they enable you to create a single action
that can be used in multiple forms, views, or folders. Shared actions have the same drawbacks as
shared fields, but not to the extent of shared fields. Shared actions can be useful in designing
applications, 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 the
agent 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 a
shared resource element, however, is that shared code elements are programmatic Notes/Domino
elements, and shared resource elements are externally created objects that are made available to
other 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 code
elements, the price you pay in speed is worth the advantages you get by using shared resource
elements. Some of these benefits include the following:
• Portability: These elements must be on the file system if they aren't shared resources. By
placing them in the database, they replicate just like other design elements.
• Ease of access: These elements are referenced simply by name because they are
available as a part of the same object store.
You should use these shared resources whenever you need this type of item in your database
design.
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 Insert
Resource dialog box appears, as shown in Figure 4−5.
Figure 4−5: The Insert Resource dialog box is a handy way to access all available shared resource
elements in the current database or other databases.
New Feature One of the most exciting new features in Notes/Domino 6 is the ability to
use resources from other databases in your current database. If you look at
the Insert Resource dialog box shown in Figure 4−5, you see the combo
box at the top that enables you to choose the current database or other
databases for selecting the desired shared resource.
Stylesheets
Stylesheets control the presentation of your documents. Usually associated with Web−based
applications, stylesheets are now used to control the appearance of documents displayed in the
Notes client as well.
To add stylesheets to your application design, you simply choose Shared Resources → Style
Sheets, click the New Style Sheet Resource button, and find your CSS file on your file system. The
file 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
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 a
class, .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 Java
resource files that you need. Figure 4−6 shows the Locate Java Applet Files dialog box.
Figure 4−6: The Locate Java Applet Files dialog box enables you to choose Java resource files to
add 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 the
Notes client and Web browser applications, in any design element that enables you to place
graphics in it.
You can add an image resource to your application by choosing Shared Resources → Images, and
then clicking the New Image Resource button. A Windows common File dialog box appears, and
you can choose the graphics file(s) you want to import into your application. You can then use the
Properties box to provide an alias for the image.
Besides using the method described at the beginning of this section (Create → Resource → Insert
Resource) to add a resource to your design element, you can also add an image resource by
choosing Create → Image Resource and selecting the desired graphic.
Files
File resources are basically a catch−all area for files you want to have as a part of your application
that don't fit into any other category. But if you place an HTML file here (a file with the extension
.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 then
clicking the New File Resource button. A Windows common File dialog box appears, and can
choose 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 data
resource, and then use that DCR object in your forms to populate one or more fields with data from
the 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 target
database, without the need to use the Domino Administrator.
Cross−Reference 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 in
Lotus Notes/Domino. These design elements were broken down into functional areas:
• User interface elements: These elements include forms, subforms, pages, views, and
folders. These elements are used to interact with the user, and allow her to work with the
data stored in the database.
• Navigation elements: These elements include framesets and outlines, which can be used
to easily provide the ability to locate information in your application, either through a Web
browser 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 in
multiple places in your application.
• Shared resource elements: There are quite a few shared resource elements, including
image resources, Cascaded Style Sheets, file resources, and so on. These elements allow
you to maintain all of the items needed for your application in one object store, which
preserves 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 elements
covered in this chapter. From here we move on to Part II, Domino Designer. The chapters there will
introduce you to the Domino Designer, and how you can use it to develop world−class Domino
applications exploiting the design elements covered here.

Chapter 4 Application Building Blocks

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Chapter 4 Application Building Blocks

Caricato da

Copyright:

Formati disponibili

Lotus Notes and Domino 6 Programming Bible

by Brian Benz, Rocky Oliver and Richard Schwartz

Reprinted for Satyendra K. Jha, IBM

Reprinted with permission as a subscription benefit of Books24x7,

All rights reserved. Reproduction and/or distribution in whole or in part in

Introducing Design Elements

• User interface elements

User Interface Elements

• Views and Folders

• Text: This field enables the user to enter text.

Buttons, action buttons, action hotspots

Forms and documents

• 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.

Forms in Notes versus forms in browsers

Views and folders

Shared Code Elements

Cross−Reference For more on agents, refer to Chapter 18.

Shared Resource Elements

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

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

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

Data Connection Resources

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

Potrebbero piacerti anche