ShowTable of Contents
Defining the concepts of document and page in Quickr for Domino 8.5
IBM Lotus Quickr for Domino is a Web application program based on Lotus Domino. In Quickr for Domino 8.5 (hereafter called “Quickr 8.5”), “document” and “page” have been well defined; specifically, any file in Quickr 8.5, including “document” and “page” is a note in a Domino database. Each file in Quickr 8.5 contains a certain amount of fields, whose type decides that of the file.
A new field---called the single-attachment field---was introduced in Quickr 8.5 and has only one field with attachments. Files containing this kind of field are defined as “documents,” while the rest are defined as “pages”.
Relationship between forms and documents
In Quickr Domino, there is a concept of “form,” which is a template based on which the documents are created. The form defines what fields are included in the documents, such as the title field, multi-attachment fields, single-attachment field, and the text-edit-box field. The form decides the document's type.
The introduction of “document” and “page” makes Quickr 8.5 share the same definition with the Quickr Connector. The forms containing single-attachment fields are templates for “documents,” while the other forms are templates for “pages”.
The Customizing form of Quickr 8.5 in document and page
According to the definitions above, you can see that forms are not limited to the those of “Upload” and “Page” defined by the system. You can also define your own forms. For example:
1.Click the Customize button on the upper right-hand side of a place, choose the Form item, and then click New Form (see figure 1).
Figure 1. Customize form
2. Add your desired fields to the form by clicking the Add button in figure 1; the Add Field window then displays (figure 2).
Figure 2. Add Field window
3. Save the new form so that, later on, users can later create documents based on this form (see figure 3).
Figure 3. Create a document/page based on the new form
The document and page concepts in ECM of Quickr 8.5
There is an exception for the definitions of “document” and “page”. When the Enterprise Content Management (ECM) System is integrated, you can browse all the files stored in the ECM database or publish the files from a Quickr 8.5 database to the ECM database.
There are three options for publishing to ECM: “Replace with a link”, “Create a copy,” and “Move the document” (see figure 4).
As for replacing the current file as a link, though the document has been stored in the ECM, there is no single-attachment field in the Quickr 8.5 database, so in this situation the file is also seen as the “document”. Similarly, when the page is published by being replaced as a link, it is also seen as the “page”.
Figure 4. Publish to the ECM
Users can choose the particular document pointing to the ECM server when creating a link (see figure 5); thus the created ECM link is a “document” instead of a “page”.
Figure 5. Create a link
Figure 6 shows the Insert Link dialog box.
Figure 6. ECM Link
Application upgrade in document and page
During an upgrade, the program does not not change the type of data created by users in the place of the earlier product version. To avoid confusion during the upgrade from Quickr 8.2 to Quickr 8.5, the program filters all the places, as well as the files, and modifies the form information along with the type of the files, under some certain conditions.
For example, if you create a file named “A” based on the Upload form and add an attachment named A.odt to the file in Quickr 8.2, then you can see an A.odt document in Connector 8.2.
After Quickr 8.2 is upgraded to Quickr 8.5, when you browse this file A using Connector 8.5, assuming that the data model has not been changed, you can see it only as a “page” instead of a “document”. This occurs because the form of the file is now a multi-attachment form now, and “A” instead of “A.odt” will be seen in the Connector.
In other words, the user will operate the page, which is the layer of data outside the A.odt instead of the A.odt itself. A.odt cannot be edited or downloaded directly. You need to select it and see its property and the attachment list from the context menu before actually downloading this attachment.
To avoid this situation, the Quickr 8.5 upgrade program changes some properties of the files in certain conditions. For instance, in the above case if we assume that A meets the requirements (which is explained below), then the original form of the file will be newly changed to a pure, single-attachment form by Quickr 8.5. Thus it is still a “document”, not “page”.
In Connector 8.5, users still see A.odt and directly operate the attachment instead of the A file that includes this attachment. Users can also directly download and edit this file, like before.
So, what are the conditions in which the upgrade program will change some properties? When a user creates a file based on the Upload form in Quickr 8.2 and adds only one attachment to it, and there is either no word in the rich-text-editing area on the Web UI or no modification to the default file name created by the Connector in the rich text editing area, then the upgrade program turns the file into a real “document” that can be identified by Quickr 8.5, instead of a “page”.
Why is it necessary to check the rich-text-editing area? Because in the Upload file of Quickr 8.2 a user can add different styles of texts to the Web UI, whereas in Quickr 8.5 the user can no longer input any different style of text except the simple one.
In order not to lose the user's data and format, it is necessary to check the rich-text-editing area during the upgrade. If there is any content in the rich-text-editing area, it will keep its type as “page,” and different styles of text still can be shown in the text-editing-area of “page”.
Comparing the Quickr 8.2 and Quickr 8.5 UIs
Connector for Quickr 8.2
There are many differences between the data shown in the Connector and in the Quickr Web UI. In the Connector you can see only a single file or folder, whereas in the Quickr Web UI you can create different types of files, with or without single or multiple attachments.
As shown in figure 7, we create a “file1-multiple attachments” file with the multiple attachments, “Attachment 1.odt”, “Attachment 2.odt,” and “Attachment 3.odt”; we create “file2-one attachment” with only one attachment, “Attachment 4.odt”; file3 -no attachment” without any attachments; and “UploadAttachment” with attachment “Upload file.odt”.
Figure 7. Quickr 8.2 Web UI
The Connector UI and Web UI are two different client sides of Quickr for Domino. As shown in figure 8, when Connector 8.2 links to a place as shown in figure 7, the page shown in Quickr Domino Web UI with multi-attachments will turn into a folder that stores all the attachments as individual files in the Connector. In the Web UI it is a document with multi-attachments.
Figure 8. The 8.2 Connector
Connector for Quickr 8.5
After Connector is linked to the server side of Quickr 8.5, users can not only browse the individual files and folders but also view the pages in Connector. The “page”can have one attachment, multiple attachments, or no attachment at all (see figure 9). To support this function, the data model of “document”/ “page” has been introduced into the Quickr for Domino servers.
Figure 9. The 8.5 Connector
Figure 10 shows the Quickr 8.5 Web UI.
Figure 10. Quickr 8.5 Web UI
Improved user experience via document and page
The concepts of document and page offer a better user experience because:
- The data shown in the Connector is exactly the same as in the Web UI. For example, a page with multiple attachments in a Web UI is still a page in the Connector, instead of a folder. With a Lotus Quickr 8.2 for Domino server, a page in the Web UI with multiple attachments appears as a folder in the Connector.
- The Single-attachment field and the Upload File form introduced in Quickr for Domino enable the concepts of document and page to be clearly distinguished.
If the Connector wants to apply the “document” and “page”, then the “version” in the request parameter should be 8.0.6 or above. The version request format is <serviceVersion>8.0.6</serviceVersion>..
When Connectors of different versions are linked to the same Quickr 8.5 server, users may see different results. For example, in the 8.2 Connector version, the server follows the logic of Quickr 8.2 and returns the information without the support of “document” and “page”. Whereas in the 8.5 Connector, the server returns the results with support of “document” and “page”.”
In other words, if you create a page with multiple attachments on the Web UI of Quickr 8.5, you will see a folder that has many files of attachments when it is linked with Connector 8.2; however, if Connector 8.5 is linked to the page, then you can see the same page as in the Web UI library. The attachments for modifying the page will not be seen or downloaded until you browse the page by the Connector and change the type of the page.
This article has defined the concepts of document and page in Quickr for Domino 8.5 and provided a clearer classification of data models. The type of “document” or “page” is decided by the type of its form and is not changed by adding or deleting one attachment.
We also introduce the customization of “document” and “page”; what kind of files are turned into “documents” after upgrading; and the “document” / “page” data model in the condition of ECM integration. Further, a better user experience is provided by “document” and “page” for Connectors in that the action of the Connector is consistent with that of the Web UI.
About the author
Hao Xiang Yu is based at IBM's China Software Development Lab in Beijing and has worked on Lotus products for seven years. She is the core service development lead of Lotus Quickr for Domino, and is one of the key developers of the “document” and “page” service in Lotus Quickr 8.5 for Domino. You can reach her at firstname.lastname@example.org.