Working with Documents

Because Notes originated as a distributed document-management system, it is only natural that there are a lot of ways to obtain information about documents. You can obtain information about the document's creation date and last modified date, as you saw earlier in the section "Working with Date and Time @Functions." There are also @Functions that tell you the size of the document, the names of any attachments, the lengths of any attachments, and more. Some of these @Functions are available as simple actions in views. Table 12.11 lists some of the @Functions you can use to display information about documents.

Table 12.11. Document @Functions

@Function	Returns
General Document Information
@Accessed	Last date and time the document was accessed
@Attachments	The number of file attachments
@AttachmentNames	Text list of attached filenames
@AttachmentLengths	Text list of attached file sizes
@Author	Text list of document authors
@Created	Date the document was created
@DocFields	Text list of document fields
@DocLength	The size of the document in bytes
@DocumentUniqueID	The document's unique ID
@InheritedDocumentUniqueID	The unique ID of the current document's parent document
@Modified	Last modification date and time
@NoteID	"NT" plus the note ID, for example, NT000021BE
@Functions Used in Views
@AllChildren	Used in view selection formulas; returns response documents
@AllDescendants	Used in view selection formulas; returns response and response-to-response documents
@Responses	The number of responses to the current document in a view
Logical Properties of Documents ” Is Functions
@IsAvailable( fieldname )	True if the field is available
@IsDocBeingEdited	True if the document is in edit mode
@IsDocBeingLoaded	True if the document is being loaded into memory
@IsDocBeingMailed	True if the document is being mailed
@IsDocBeingRecalculated	True if the document is being refreshed
@IsDocBeingSaved	True if the document is being saved
@IsNewDoc	True if the document has just been composed and has not been saved
@IsResponseDoc	True if the document is a response document
@IsUnAvailable( fieldname )	True if the field is not available
Other Useful Document Properties ”Special Fields
$Ref	Unique ID of the parent document
$Revisions	List of dates and times the document was edited
$UpdatedBy	List of document authors and editors

You have already seen examples of many of these @Functions scattered throughout the formulas in this chapter. Many document property @Functions are useful in views. For example, if you have a database that serves as a design archive, you can use the @Functions @Attachments , @AttachmentLengths , and @AttachmentNames to display information about any file attachments. Figure 12.9 shows a view under construction that uses these @Functions.

Figure 12.9. This view uses @Functions to display information about the attachments to documents.

The paperclip icon next to the Attachment Names column is displayed only when a file attachment exists. To accomplish this, set the view column properties to display icons only, and use the following formula:

@If(@Attachments > 0; 5; 0)

The formula evaluates to the number 5 , which displays a specific view column icon. A grid of view icons is available in Domino Designer Help.

To display the names of the attachments, you can use a simple action or the @Function @AttachmentNames . If you want to stack multiple attachment filenames in a view column, set the column property Multivalue Separator to New Line, set the view property Row Height to 9 lines, and check Shrink to Fit.

To display the size of the attachment, use the @AttachmentLengths @Function. Normally, @AttachmentLengths displays the value in bytes; to display the value in kilobytes with a fixed decimal place setting of 2, use the following formula:

@If(@Attachments > 0; @Text(@AttachmentLengths / 1024; "F,2") + " K"; "")

If you have stacked the filenames using the previous technique, you should set the column property Multivalue Separator to New Line for this column as well. When you do this, the sizes of the files stack neatly next to their names (see Figure 12.9).

The @Functions related to the document ID are also useful. For example, you can update the value of a field on another document as long as you know the unique document ID. If you want to update the value of the cStatus field on a parent document from a response document, you can use a formula such as the following:

@SetDocField($Ref; "cStatus"; cRespStatus)

NOTE

Document IDs are unique across all replicas of a database.

 

The @AllChildren , @AllDescendants , and @IsResponseDoc functions are used in view selection formulas to display main documents and any responses.

TIP

It is better to use @AllChildren or @AllDescendants in a view selection formula than @IsResponseDoc . The formula @IsResponseDoc returns all response documents ”not just those related to the main documents in the view. Only those response documents that are related to a main document are displayed.

 

The Is @Functions are useful if you need to take certain actions that are dependant on the state of the document. In the edit history example in the section "Getting Session and User Information," @IsDocBeingSaved was used to make sure that the field values didn't get updated at the wrong time.

The special fields listed at the end of Table 12.11 are not editable, but they can be used in formulas. Of the three, $Ref is used the most frequently; $Ref stores the unique ID of the parent document and provides the link to the document to update the field value. This can be used in @SetDocField() to update a parent document from a response document.