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.