Domino View & Form builder inputs - Portlet Factory v6.1.2

Portlet Factory, Version 6.1.2

Domino View & Form builder inputs

This topic describes the inputs for the Domino View & Form builder.

General inputs
View Display and Layout
Document and Form Support
View Document
Edit Document
Create Document
Delete Document
Label Translation Settings
Connection Override
Advanced Inputs

General inputs

Table 1. General inputs
Input Name Description
Name Name for this builder call. The WebSphere Portlet Factory Designer displays this name in the builder call list.
Properties File Select the name of the property file that contains basic Domino® connection information.
This file is located normally in the project WEB-INF/config/domino_config directory. For example: default_domino_server.properties
Note: You can override settings established in this file by using the Connection Override inputs in this builder.
Get databases and views Click this button to access the Domino server and return an alphabetically sorted list of available databases on the server.
Database name Open this list and select the Domino database containing the views and information to display in your portlet or widget. This list contains the relative file names of the available databases. For example: catalog.nsf or help\readme.nsf
The views associated with the selected database are displayed in the View Name input.
Enable Schema Caching Enable the caching of the schema for the specified Domino view. The builder regeneration phase uses a cached version of the view document and form schema. If a different database or view or form is selected, a new version of the schema is cached.
Enabling this option provides the following benefits:

Enhanced performance during editing models containing this builder.
Enhanced security because a cached schema avoids exposing model generation time credentials once an initial regeneration is performed. To leverage this security, specify separate runtime credentials (see the Runtime Credentials input).

Note: If the schema for the data changes on the Domino server, disable this input, regenerate the model, and enable this input again.
Runtime Credentials Select Domino security credentials for use during execution. These credentials are used when the portlet or widget containing the Domino view is run. You can select:

Use regen credentials specified above

At runtime, use the same credentials specified for regeneration.

Prompt user for credentials

Allow user to specify a user name and password for use at runtime. Credentials are taken from a IBM® WebSphere Portal Credential Vault slot called DominoUserCredentials. A link is added to the page for editing user-specific credentials.

Use LTPA Token

Use WebSphere Domino LTPA-based SSO (servers must be configured appropriately). A link is added to the page for editing user-specific credentials.

View Display and Layout

Table 2. View Display and Layout inputs
Input Name Description
View Name Open this list and select the Domino view to display in your portlet or widget. This input is available if the Enable View Support input is checked.
Note: Hidden views are not included in the list of available views. To access a hidden view, enter the name of the view.
Rows to Include Specify which rows in the view are included on the page. You can select:

Document rows only
All rows
Category rows only

View Page HTML Page that is used to display the IBM Lotus® Domino view. The default page is: ../factory/pages/domino_portlet.html.
To customize the look and layout of this Domino application, create new HTML and CSS files. If you maintain the named elements in the original page, you can create a custom page with any desired look and layout.
In addition, you can add span elements named viewname, hostname, and databasename to display any of those values on the page.
HTML Template File Select an HTML Page Automation template file that is used to generate pages in the application.
Note: If an HTML Template files is in use, a number of inputs that have to do with HTML class name generation are not displayed.
Style sheet URL (Optional) Enter the name of a CSS file used to control the look of the view. The default CSS file is ../factory/html_templates/gridtable.css.
Paged data display Enable to allow paging through the view data. If this input is enabled, paging buttons are added below table.
Rows per page Available when paging is enabled. Enter the number of rows to display.
Initial category Specify a single category for the initial view to display.
Note: You can also use the category variable to set this input.
Show category selector Enable to include a Category drop-down list and allow user to pick a category from those shown in the view.
Show search button Enable to include a Search input in the user interface (UI). This allows a user to perform a full-text search within the view.

Document and Form Support

Table 3. Document and Form Support inputs
Input Name Description
Document support This input determines the pages and methods created for working with document. You can choose:

None

To disable Domino document support options.

Open Domino window

To launch documents in a new browser window going directly to Domino server. (Document view and edit operations are not supported.)

Create pages from Domino form

To enable the automatic creation of document-related pages and methods. The builder creates a schema-typed variable for documents, based on the Domino form. In addition, pages and methods for edit, view, create, and delete document operations are also created by the builder

Document link column This input is available when Open Domino window is selected in the Document support input. Specify the column name used as a link to launch the selected document using Domino. The Domino document opens in a separate browser window.
Form name This input is available when Create pages from Domino form is selected in the Document support input. Select a Domino form to use as the basis for your pages. The forms displayed in the list are available on the Domino server.
Navigation control type This input is available when Create pages from Domino form is selected in the Document support input. Choose the type of control to use to launch the Domino view. You can choose:

Link
Button

Note: The Save Changes button is not controlled by this setting.
Document page type This input determines how view, edit and create pages are created. You can choose:

Create fields based on form

To automatically generate or replicate the fields and UI that exist in the Domino form. (Supported field types include: String, Date/Time, and Number.)

Use fields from imported HTML

To use only fields that exist on a custom HTML page that you created.

Enable Input Validation Enable to activate schema-based validation on the input page.

View Document

Table 4. View Document inputs
Input Name Description
Enable document View Enable to create a page for viewing a document. This set of inputs controls pages used for viewing documents.
Document view page Select a page in the model to use for viewing the document.
HTML Template File Select an HTML page automation template file that will be used to generate the Document View page.
If an HTML template file is in use, a number of inputs that have to do with HTML class name generation are not displayed.
Document view link Select a column in the view to use as the link.
Retrieve Rich Text Items as HTML When getDocumentData is invoked on the DominoHelper class, it uses HTTP requests to the Domino server to get HTML for any rich text items in the document. When these fields are displayed in a page, the appearance matches the HTML rich text appearance from the Domino server.
This feature is suitable for display only, not for updating.
Because this functionality uses HTTP access to the Domino server, it requires HTTP to be enabled on the Domino server. If Lightweight Third Party Authentication (LTPA) is being used, the LTPA cookie is passed to the HTTP call. Otherwise, the user ID and password specified in the builder are sent using HTTP Basic Authentication.

Edit Document

Table 5. Edit Document inputs
Input Name Description
Enable document edit Enable to create a page for editing a document. This set of inputs controls pages used for editing documents.
Document edit page Select a page in the model to use for editing the document. A default edit page named domino_document.html is provided.
HTML Template File Select an HTML page automation template file that is used to generate the Document Edit page.
If an HTML template file is in use, a number of inputs that have to do with HTML class name generation are not displayed.
Add edit column to view Add a column to the view to support editing.
Edit column type Type of widget displayed in the edit column. This widget provides a link to the edit page. You can choose:

Link

To display the word Edit as a hyperlink.

Button

To display a button with the label Edit.

Image Button

To display a page image as the edit symbol.

This input is available when the Add edit column to view input is enabled.
Agent to run on save Select a Domino agent to run when the edited document is saved. Agents displayed in the list are the agents available for his view.
You must follow the rules for invocation of agents.

Create Document

Table 6. Create Document inputs
Input Name Description
Enable document create Enable to generate a page for creating a document. This set of inputs controls pages used for creating documents. A link is added that provides access to the create page.
Document create page Select a page in the model to use for creating the document.
HTML Template File Select an HTML page automation template file that is used to generate the document create page.
If an HTML template file is in use, some inputs that related to HTML class name generation are not displayed.
Agent to run on create Select a Domino agent to run when a created document is saved. The agents displayed in the list are the agents available for his view.
You must follow the rules for invocation of agents.

Delete Document

Table 7. Delete Document inputs
Input Name Description
Enable document delete Enable to create a link in the view that supports the deletion of a document from the Domino database.
Confirm deletion Enable to pop up a confirmation dialog when a document is about to be deleted from the Domino database.
Add Delete Column Enable to add a column to the view to support deletion of a document.
Delete column type Type of widget displayed in the delete column. You can choose:

Link

To display the word Delete as a hyperlink.

Button

To display a button with the label Delete.

Image Button

To display an X image as the delete symbol.

This input is available when the Add delete column is enabled.

Label Translation Settings

Table 8. Label Translation Settings inputs
Input Name Description
Navigation resource bundle This input supports internationalization of a portlet or a widget. Specify a Java resource bundle to use for the text of all the buttons and links. This input is also used to specify image file names for use with image buttons, if you are using them for navigation.
The resource bundle used to control the labels is located in the project work/lib/domino_builder.jar file. From this jar file, extract the file DominoPortletBuilder.properties to view examples of key values.
Place a localized version of this file in the project work/source directory to use it. Also, see the default resource bundle for an example. For example: com.bowstreet.samples.DominoPortletBuilder
Form resource bundle This input supports the internationalization of a portlet or widget. Specify a Java resource bundle to use for all labels, form fields, and view columns. Enter the fully-qualified name of the property file or Java class to serve as the form resource bundle. Alternately, click Create resource bundle to create a suitable starting resource bundle. For example, enter
com.acme.LabelResources for the property file stored as follows:
WEB-INF/work/source/com/acme/LabelResources.properties
Create resource bundle Creates a properties file that contains the label name and default value for each element used in the form. Use this generated property file as the basis for creating the final resource bundle used by this page.
Include the .properties extension in the name that you enter for the properties file.

Connection Override

Table 9. Connection Override inputs
Input Name Description
Host server Enter the host name (and port number if not port 80) of the Domino server. For example: domino_server.acme.com:8080
User name for generation Provide a Domino server user name. This name is used for all requests to the Domino server.

The generation credentials are used to access the Domino server from IBM WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be made at both design time and at regeneration time.
Password for generation Provide a Domino server password associated with the user name above. This password is used for all requests to the Domino server.
The generation credentials are used to access the Domino server from IBM WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be made at both design time and at regeneration time.

Advanced Inputs

Table 10. Advanced Inputs
Input Name Description
Create Sample HTML Creates an HTML file for viewing and editing documents. The page contains SPAN tags for each of the form fields you are using.
To create a page suitable for document editing, change SPAN tags to INPUT tags for those fields to be editable.
Model name This is the name of the model that provides a template for the functionality of this builder. This model has a number of profiled inputs which are controlled by this builder.
The default setting for this input specifies the domino_portlet model. This model contains all the builders required for the portlet to function and, as a result, this input should not be changed. However, in some cases, to leverage some additional (profiled) functionality, a custom version of this model might be required. This input allows you to specify an alternate version of the domino_portlet model.
Generate Main Enable to allow this builder to automatically generate a Main action. This action starts application operation and causes the display of the web page. Disable this input to use a custom Main action of your own creation.
Log View and Document Data Enable to output the returned document and view data to a log file. The log4j logger DebugTracing is used as the output. The info level for this logger must be at least INFO, which it is by default.
Fetch Subsets of Data If a large amount of data is to be returned, and the model uses paging to view a specific number of rows, enable this input. When enabled, this input allows more efficient paging of data from Domino APIs to the WebSphere Portlet Factory XML representation. If you plan to use the Data Page or Data View builders to display paged data, the increased efficiency is desirable. This input applies to document-only Domino data fetches using IIOP. This input has no effect when the following conditions are true:

HTTP Access is used.
The Rows to Include input is either All Rows or Category Rows Only.

Include Untitled Columns Enable to display Domino view columns that have no name or title. By default, this builder hides untitled and unnamed columns. Such columns are displayed in the portlet or widget when this input is enabled.
The absence of a column title is not a good measure of whether a column should be displayed. Typically, most categorized columns are not titled. Usually you have a mix of untitled columns that should be displayed (categories, columns with icons) and columns that should not be displayed (hidden sort columns). You can always hide unwanted columns with a Data Field Modifier builder.
Create Empty Fields Specifies how the builder handles fields with empty values when it creates and updates IBM Lotus Notes® documents.
If this input is enabled, empty fields are created in the Lotus Notes document for all fields from the document schema that do not have a value in the view_document variable. (This behavior mimics the Lotus Notes client when it creates or updates documents.) For example, if a user did not enter a value for a field in an HTML form, or if a field was hidden using a Rich Data Definition builder, an empty field is still created in the Lotus Notes document.
If this input is disabled, empty fields are removed from the Lotus Notes document.

Domino user name and password credentials
The Domino Data Access builder and Domino View & Form builder provide several credential options.
Parent topic: Domino View & Form builder

Library | Support |

Input Name	Description
Name	Name for this builder call. The WebSphere Portlet Factory Designer displays this name in the builder call list.
Properties File	Select the name of the property file that contains basic Domino® connection information. This file is located normally in the project WEB-INF/config/domino_config directory. For example: default_domino_server.properties Note: You can override settings established in this file by using the Connection Override inputs in this builder.
Get databases and views	Click this button to access the Domino server and return an alphabetically sorted list of available databases on the server.
Database name	Open this list and select the Domino database containing the views and information to display in your portlet or widget. This list contains the relative file names of the available databases. For example: catalog.nsf or help\readme.nsf The views associated with the selected database are displayed in the View Name input.
Enable Schema Caching	Enable the caching of the schema for the specified Domino view. The builder regeneration phase uses a cached version of the view document and form schema. If a different database or view or form is selected, a new version of the schema is cached. Enabling this option provides the following benefits: Enhanced performance during editing models containing this builder. Enhanced security because a cached schema avoids exposing model generation time credentials once an initial regeneration is performed. To leverage this security, specify separate runtime credentials (see the Runtime Credentials input). Note: If the schema for the data changes on the Domino server, disable this input, regenerate the model, and enable this input again.
Runtime Credentials	Select Domino security credentials for use during execution. These credentials are used when the portlet or widget containing the Domino view is run. You can select: Use regen credentials specified above At runtime, use the same credentials specified for regeneration. Prompt user for credentials Allow user to specify a user name and password for use at runtime. Credentials are taken from a IBM® WebSphere Portal Credential Vault slot called DominoUserCredentials. A link is added to the page for editing user-specific credentials. Use LTPA Token Use WebSphere Domino LTPA-based SSO (servers must be configured appropriately). A link is added to the page for editing user-specific credentials.

Input Name	Description
View Name	Open this list and select the Domino view to display in your portlet or widget. This input is available if the Enable View Support input is checked. Note: Hidden views are not included in the list of available views. To access a hidden view, enter the name of the view.
Rows to Include	Specify which rows in the view are included on the page. You can select: Document rows only All rows Category rows only
View Page HTML	Page that is used to display the IBM Lotus® Domino view. The default page is: ../factory/pages/domino_portlet.html. To customize the look and layout of this Domino application, create new HTML and CSS files. If you maintain the named elements in the original page, you can create a custom page with any desired look and layout. In addition, you can add span elements named viewname, hostname, and databasename to display any of those values on the page.
HTML Template File	Select an HTML Page Automation template file that is used to generate pages in the application. Note: If an HTML Template files is in use, a number of inputs that have to do with HTML class name generation are not displayed.
Style sheet URL	(Optional) Enter the name of a CSS file used to control the look of the view. The default CSS file is ../factory/html_templates/gridtable.css.
Paged data display	Enable to allow paging through the view data. If this input is enabled, paging buttons are added below table.
Rows per page	Available when paging is enabled. Enter the number of rows to display.
Initial category	Specify a single category for the initial view to display. Note: You can also use the category variable to set this input.
Show category selector	Enable to include a Category drop-down list and allow user to pick a category from those shown in the view.
Show search button	Enable to include a Search input in the user interface (UI). This allows a user to perform a full-text search within the view.

Input Name	Description
Document support	This input determines the pages and methods created for working with document. You can choose: None To disable Domino document support options. Open Domino window To launch documents in a new browser window going directly to Domino server. (Document view and edit operations are not supported.) Create pages from Domino form To enable the automatic creation of document-related pages and methods. The builder creates a schema-typed variable for documents, based on the Domino form. In addition, pages and methods for edit, view, create, and delete document operations are also created by the builder
Document link column	This input is available when Open Domino window is selected in the Document support input. Specify the column name used as a link to launch the selected document using Domino. The Domino document opens in a separate browser window.
Form name	This input is available when Create pages from Domino form is selected in the Document support input. Select a Domino form to use as the basis for your pages. The forms displayed in the list are available on the Domino server.
Navigation control type	This input is available when Create pages from Domino form is selected in the Document support input. Choose the type of control to use to launch the Domino view. You can choose: Link Button Note: The Save Changes button is not controlled by this setting.
Document page type	This input determines how view, edit and create pages are created. You can choose: Create fields based on form To automatically generate or replicate the fields and UI that exist in the Domino form. (Supported field types include: String, Date/Time, and Number.) Use fields from imported HTML To use only fields that exist on a custom HTML page that you created.
Enable Input Validation	Enable to activate schema-based validation on the input page.

Input Name	Description
Enable document View	Enable to create a page for viewing a document. This set of inputs controls pages used for viewing documents.
Document view page	Select a page in the model to use for viewing the document.
HTML Template File	Select an HTML page automation template file that will be used to generate the Document View page. If an HTML template file is in use, a number of inputs that have to do with HTML class name generation are not displayed.
Document view link	Select a column in the view to use as the link.
Retrieve Rich Text Items as HTML	When getDocumentData is invoked on the DominoHelper class, it uses HTTP requests to the Domino server to get HTML for any rich text items in the document. When these fields are displayed in a page, the appearance matches the HTML rich text appearance from the Domino server. This feature is suitable for display only, not for updating. Because this functionality uses HTTP access to the Domino server, it requires HTTP to be enabled on the Domino server. If Lightweight Third Party Authentication (LTPA) is being used, the LTPA cookie is passed to the HTTP call. Otherwise, the user ID and password specified in the builder are sent using HTTP Basic Authentication.

Input Name	Description
Enable document edit	Enable to create a page for editing a document. This set of inputs controls pages used for editing documents.
Document edit page	Select a page in the model to use for editing the document. A default edit page named domino_document.html is provided.
HTML Template File	Select an HTML page automation template file that is used to generate the Document Edit page. If an HTML template file is in use, a number of inputs that have to do with HTML class name generation are not displayed.
Add edit column to view	Add a column to the view to support editing.
Edit column type	Type of widget displayed in the edit column. This widget provides a link to the edit page. You can choose: Link To display the word Edit as a hyperlink. Button To display a button with the label Edit. Image Button To display a page image as the edit symbol. This input is available when the Add edit column to view input is enabled.
Agent to run on save	Select a Domino agent to run when the edited document is saved. Agents displayed in the list are the agents available for his view. You must follow the rules for invocation of agents.

Input Name	Description
Enable document create	Enable to generate a page for creating a document. This set of inputs controls pages used for creating documents. A link is added that provides access to the create page.
Document create page	Select a page in the model to use for creating the document.
HTML Template File	Select an HTML page automation template file that is used to generate the document create page. If an HTML template file is in use, some inputs that related to HTML class name generation are not displayed.
Agent to run on create	Select a Domino agent to run when a created document is saved. The agents displayed in the list are the agents available for his view. You must follow the rules for invocation of agents.

Input Name	Description
Enable document delete	Enable to create a link in the view that supports the deletion of a document from the Domino database.
Confirm deletion	Enable to pop up a confirmation dialog when a document is about to be deleted from the Domino database.
Add Delete Column	Enable to add a column to the view to support deletion of a document.
Delete column type	Type of widget displayed in the delete column. You can choose: Link To display the word Delete as a hyperlink. Button To display a button with the label Delete. Image Button To display an X image as the delete symbol. This input is available when the Add delete column is enabled.

Input Name	Description
Navigation resource bundle	This input supports internationalization of a portlet or a widget. Specify a Java resource bundle to use for the text of all the buttons and links. This input is also used to specify image file names for use with image buttons, if you are using them for navigation. The resource bundle used to control the labels is located in the project work/lib/domino_builder.jar file. From this jar file, extract the file DominoPortletBuilder.properties to view examples of key values. Place a localized version of this file in the project work/source directory to use it. Also, see the default resource bundle for an example. For example: com.bowstreet.samples.DominoPortletBuilder
Form resource bundle	This input supports the internationalization of a portlet or widget. Specify a Java resource bundle to use for all labels, form fields, and view columns. Enter the fully-qualified name of the property file or Java class to serve as the form resource bundle. Alternately, click Create resource bundle to create a suitable starting resource bundle. For example, enter com.acme.LabelResources for the property file stored as follows: WEB-INF/work/source/com/acme/LabelResources.properties
Create resource bundle	Creates a properties file that contains the label name and default value for each element used in the form. Use this generated property file as the basis for creating the final resource bundle used by this page. Include the .properties extension in the name that you enter for the properties file.

Input Name	Description
Host server	Enter the host name (and port number if not port 80) of the Domino server. For example: domino_server.acme.com:8080
User name for generation	Provide a Domino server user name. This name is used for all requests to the Domino server. The generation credentials are used to access the Domino server from IBM WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be made at both design time and at regeneration time.
Password for generation	Provide a Domino server password associated with the user name above. This password is used for all requests to the Domino server. The generation credentials are used to access the Domino server from IBM WebSphere Portlet Factory Designer. They are used for regenerating the model on the server, and such requests can be made at both design time and at regeneration time.

Input Name	Description
Create Sample HTML	Creates an HTML file for viewing and editing documents. The page contains SPAN tags for each of the form fields you are using. To create a page suitable for document editing, change SPAN tags to INPUT tags for those fields to be editable.
Model name	This is the name of the model that provides a template for the functionality of this builder. This model has a number of profiled inputs which are controlled by this builder. The default setting for this input specifies the domino_portlet model. This model contains all the builders required for the portlet to function and, as a result, this input should not be changed. However, in some cases, to leverage some additional (profiled) functionality, a custom version of this model might be required. This input allows you to specify an alternate version of the domino_portlet model.
Generate Main	Enable to allow this builder to automatically generate a Main action. This action starts application operation and causes the display of the web page. Disable this input to use a custom Main action of your own creation.
Log View and Document Data	Enable to output the returned document and view data to a log file. The log4j logger DebugTracing is used as the output. The info level for this logger must be at least INFO, which it is by default.
Fetch Subsets of Data	If a large amount of data is to be returned, and the model uses paging to view a specific number of rows, enable this input. When enabled, this input allows more efficient paging of data from Domino APIs to the WebSphere Portlet Factory XML representation. If you plan to use the Data Page or Data View builders to display paged data, the increased efficiency is desirable. This input applies to document-only Domino data fetches using IIOP. This input has no effect when the following conditions are true: HTTP Access is used. The Rows to Include input is either All Rows or Category Rows Only.
Include Untitled Columns	Enable to display Domino view columns that have no name or title. By default, this builder hides untitled and unnamed columns. Such columns are displayed in the portlet or widget when this input is enabled. The absence of a column title is not a good measure of whether a column should be displayed. Typically, most categorized columns are not titled. Usually you have a mix of untitled columns that should be displayed (categories, columns with icons) and columns that should not be displayed (hidden sort columns). You can always hide unwanted columns with a Data Field Modifier builder.
Create Empty Fields	Specifies how the builder handles fields with empty values when it creates and updates IBM Lotus Notes® documents. If this input is enabled, empty fields are created in the Lotus Notes document for all fields from the document schema that do not have a value in the view_document variable. (This behavior mimics the Lotus Notes client when it creates or updates documents.) For example, if a user did not enter a value for a field in an HTML form, or if a field was hidden using a Rich Data Definition builder, an empty field is still created in the Lotus Notes document. If this input is disabled, empty fields are removed from the Lotus Notes document.