Imported Page Builder

Imported Page Builder

In this topic ...

Quick Tips
Specifying Inputs
Modifying Imported JavaScript
Inserting an Imported Page
Importing HTTPS Pages

Related Topics ...

Overview: Creating Pages
HTML Guidelines

The Imported Page builder adds an existing HTML or JSP page to the current model. By using Imported Page builders, we can develop your HTML or JSP code in your favorite editor and then import the results into the Designer. Once you import a page into the Designer, we can use builders to modify those pages.

Quick Tips

Override the JavaScript for browser events using a HTML Event Action Builder -- To modify or remove the JavaScript for the browser events (onClick, onMouseOver, etc.), use a HTML Event Action builder to replace the value of these event attributes with a new JavaScript string. For more information, see Modifying Imported JavaScript.
To keep HTML pages and images for each project in a self-contained file system, you should select "Create Absolute URLs" and "Import when Builder Call is Saved (design time only)." -- When the page is imported, the builder modifies the code so that the URLs become absolute. Since the builder directly modifies the HTML for the URLs, the page only needs to be imported at design time.

After a page is imported, we can activate any of its HTML elements by using one of the "Action Control" builders in the Designer -- When using control builders, match the "name" tag attribute from the original HTML file. The "name" attribute must be used for all activated elements. Use the Designer Page Location attribute to associate a control with a page element.

Store the HTML pages and images at or below the <servable_content_root> directory level -- If the files are stored elsewhere and you select Convert to absolute URLs, the absolute URLs are not guaranteed to work. To import an HTML file in another directory or in a mapped or mounted drive use the "file:///" form of the URL. For example, to import a file on a mapped drive, T:, the URL would be:
file:///T:/html_files/MyFile.html
To maximize performance, it is usually best to import an HTML page at design-time rather than at model generation time -- Importing pages at design-time may speed up model generation.

Specifying Inputs

The Imported Page builder takes the following inputs:

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Page to Import (URL) Enter the URL or the file name of the HTML file you want to import.

If you enter a relative path or URL, the builder assumes it is stored in the <servable_content_root> directory. The file's HTML code is converted to XML as part of the import process.

If you are importing a remote page, try following the specified URL with a "/", if the page is not imported correctly. For example, if you specify, http://www.company.com and the page is not imported, change this value to, http://www.company.com/.

Edit Page button (Appears only for local, file-based imports) Click the Edit Page button to read the file and place its contents into an edit field. Click the Cancel Editing button to discard your edits, or click the Save Page button to save your changes.
Post Form Enable this check box to force a POST of the form (rather than a GET). Post is recommended for most situations, especially when working with IBM portlets.
Import Rule Select one of the following:

Import when builder call is saved (design time only) - Enable this setting for pages that you anticipate will not change often. This option provides better performance since the page is not imported every time the model is generated.
Import on each generation of this model - Enable this setting if the page changes frequently. There is a performance hit associated with importing pages every time the model is regenerated.

URL Handling
URL Modification Use this input to determine how URLs on the imported page will he handled. We can choose:

Do not modify URLs - To keep imported URLs unchanged
Create Relative URLs - To modify imported URLs to a relative context
Create Absolute URLs -To modify imported URLs to an absolute context. Enable this setting if the imported page contains relative URLs. When the page is inserted in another page these URLs will remain functional.
Note that If the Factory is running as a non-default application on the server and the imported page is stored locally, this option must be selected.

Use JSP Code Enable this box to construct URLs at runtime using JSP code. This avoids hard coding URLs on the page and allows for dynamic URL generation.
Add Base tag Enable this setting to allow the browser to resolve relative URLs within the imported page. For more information, see the section Importing a Local Page. The builder assumes the directory containing the online help file is the base directory.
There might be cases when you would want to use a <base /> tag instead of converting to absolute URLs. Be careful if your page is embedded in some other page or Web site that also defines a <base /> tag, your URLs might not be correct.
Encoding
Encoding To use encoding other than what the running application server is using (typically US-ASCII or ISO-8859-1), enter the alternative encoding. This feature supports any encoding supported by the java.util.Locale object. The encoding shipped with the Java Virtual Machine is listed in the java.lang package in the Factory API.
Output Encoding This setting governs the Java character encoding scheme used for outbound HTTP.
To use encoding other than what the running application server is using (typically US-ASCII or ISO-8859-1), enter the alternative encoding. This feature supports any encoding supported by the java.util.Locale object. The encoding shipped with the Java Virtual Machine is listed in the java.lang package in the Factory API.
HTTP Basic Authentication
User Name Enter the user name required to view the imported page.
Password Enter the password required to view the imported page.
Advanced
Fully Parse Page Normally, the factory runtime parses only nodes with a name attribute and certain special nodes, such as form, body, and head. Other nodes are left unparsed. The advantage of partial parsing is that it is more efficient, both in time and memory, and it makes the parser somewhat more tolerant of poorly-formed HTML. Many odd constructions of HTML that are tolerated by browsers but are not, in fact, legal HTML, can be overlooked by the more tolerant parser.
Check this option to have the page fully parsed. This is especially useful to use advanced PageLocations on the page or when using XPath references in your PageLocations.
Relative URL Context Select one of the following if the imported page contains relative URLs:

Use Factory's <servable_content_root> - The Factory assumes the relative URLs within the imported page are stored in the Factory's <servable_content_root> directory. This is the default and it means that absolute URLs are generated to be relative to the factory's servable content area, which generally means adding the current app context name to the generated URL. For example: /images/foo.gif is changed to http://some.com/MyApp/images/foo.gif.
Use <servable_content_root> of web server's default application - The Factory assumes the relative URLs within the imported page are stored in the <servable_content_root> directory of the web server's default application. In the rare case that you want /images/foo.gif to refer to the server's servable content root ( no added app context, select "Use <servable_content_root> of the web server's default application". The use case for this non-default behavior is a shared images directory used by more than one application.

Overwriting
Rename Existing This input is useful in cases where you want to change the behavior of code that was placed in the WebApp by a high-level builder or by an Imported Model.
For example, you might want to do this if you have a Domino View & Form builder in your model, and you want to use a different class for one of the LJO's that Builder adds to the WebApp. The Domino View and Form Builder does not provide an "LJO Class Name" input. But, we can place a new LJO Builder in the model and give it the same name as that assigned by the Domino View and From Builder, thus replacing the existing LJO and specifying new class.

Enable - When checked, this input will cause the Builder to replace an existing WebApp object with a new object. The Builder will locate the existing WebApp object (variable, LJO, etc.), rename it, and then create a replacement object.

Note that This input is available on the following low-level Builders that create WebApp objects: Action List, Imported Page, Linked Java Object, Linked Model, Method, Method Call, Page, Variable and Schema.

Modify Imported JavaScript

When you import a page, you usually want to work with the HTML. However, many of the pages you import will also contain JavaScript that is imported along with the HTML. There is a handy way to rid yourself of unwanted JavaScript that comes with the HTML on an imported page.
For example, if an Input tag has associated with it an onChange=some JavaScript, you will be unable to add a HTML Event Action builder to this control. The solution is to create a property setter and set the "onChange= "(Make an empty assignment)." Next create the HTML Event Action builder.
What happens here is that the original value for onChange is replaced by the property setter, and the HTML Event Action builder can now create a fresh onChange event overriding the original JavaScript.

Inserting an Imported Page

If you plan to insert into another page the page you are importing, we need to take measures to ensure that links on the imported page remain intact once the page is inserted into another page. Since header information is lost when one page is inserted into another, links usually break on imported pages.
The Imported Page builder solves this problem by automatically converting all relative URLs to absolute URLs. For imported pages that you expect to insert into other pages, just enable the Make URLs Absolute option. When this check box is enabled, page URLs remain functional even when the imported page is inserted in another page.

Importing HTTPS Pages

If you import pages that use the HTTPS protocol, you will see an error message in your IDE's console window similar to the following:
Error importing HTML:File not found:https://www.company.com
Eclipse does not have support for SSL by default, so an error message appears when Designer tries to import a page that uses HTTPS. This error does not affect the actual running of the model (assuming that the application server that is hosting the Factory is configured to support the outbound Secure Sockets Layer (SSL)); however, you will lose the design-time check of the URL. The error message displayed above masks an incorrect URL that might have been caused by the following: a typo, HTML parsing error, certificate problems. We can either ignore the design-time error, or we can configure your IDE to use Java^TM Secure Sockets Extension (JSSE) so that it will support SSL, as described in the steps below:

Download JSSE from http://java.sun.com/products/jsse/index.html and follow the instructions for installing it.
Note that JSSE is included by default in JDK 1.4.0.

Add the following line in WEB-INF/config/bowstreet.config file:
vmparam -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol

Restart your IDE.

You should now be able to import HTTPS pages without errors.

Input Name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Page to Import (URL)	Enter the URL or the file name of the HTML file you want to import. If you enter a relative path or URL, the builder assumes it is stored in the `<servable_content_root>` directory. The file's HTML code is converted to XML as part of the import process. If you are importing a remote page, try following the specified URL with a "/", if the page is not imported correctly. For example, if you specify, `http://www.company.com` and the page is not imported, change this value to, `http://www.company.com/`.
Edit Page button (Appears only for local, file-based imports)	Click the Edit Page button to read the file and place its contents into an edit field. Click the Cancel Editing button to discard your edits, or click the Save Page button to save your changes.
Post Form	Enable this check box to force a POST of the form (rather than a GET). Post is recommended for most situations, especially when working with IBM portlets.
Import Rule	Select one of the following: Import when builder call is saved (design time only) - Enable this setting for pages that you anticipate will not change often. This option provides better performance since the page is not imported every time the model is generated. Import on each generation of this model - Enable this setting if the page changes frequently. There is a performance hit associated with importing pages every time the model is regenerated.
URL Handling
URL Modification	Use this input to determine how URLs on the imported page will he handled. We can choose: Do not modify URLs - To keep imported URLs unchanged Create Relative URLs - To modify imported URLs to a relative context Create Absolute URLs -To modify imported URLs to an absolute context. Enable this setting if the imported page contains relative URLs. When the page is inserted in another page these URLs will remain functional. Note that If the Factory is running as a non-default application on the server and the imported page is stored locally, this option must be selected.
Use JSP Code	Enable this box to construct URLs at runtime using JSP code. This avoids hard coding URLs on the page and allows for dynamic URL generation.
Add Base tag	Enable this setting to allow the browser to resolve relative URLs within the imported page. For more information, see the section Importing a Local Page. The builder assumes the directory containing the online help file is the base directory. There might be cases when you would want to use a `<base />` tag instead of converting to absolute URLs. Be careful if your page is embedded in some other page or Web site that also defines a `<base />` tag, your URLs might not be correct.
Encoding
Encoding	To use encoding other than what the running application server is using (typically US-ASCII or ISO-8859-1), enter the alternative encoding. This feature supports any encoding supported by the `java.util.Locale` object. The encoding shipped with the Java Virtual Machine is listed in the `java.lang` package in the Factory API.
Output Encoding	This setting governs the Java character encoding scheme used for outbound HTTP. To use encoding other than what the running application server is using (typically US-ASCII or ISO-8859-1), enter the alternative encoding. This feature supports any encoding supported by the `java.util.Locale` object. The encoding shipped with the Java Virtual Machine is listed in the `java.lang` package in the Factory API.
HTTP Basic Authentication
User Name	Enter the user name required to view the imported page.
Password	Enter the password required to view the imported page.
Advanced
Fully Parse Page	Normally, the factory runtime parses only nodes with a name attribute and certain special nodes, such as form, body, and head. Other nodes are left unparsed. The advantage of partial parsing is that it is more efficient, both in time and memory, and it makes the parser somewhat more tolerant of poorly-formed HTML. Many odd constructions of HTML that are tolerated by browsers but are not, in fact, legal HTML, can be overlooked by the more tolerant parser. Check this option to have the page fully parsed. This is especially useful to use advanced PageLocations on the page or when using XPath references in your PageLocations.
Relative URL Context	Select one of the following if the imported page contains relative URLs: Use Factory's <servable_content_root> - The Factory assumes the relative URLs within the imported page are stored in the Factory's `<servable_content_root>` directory. This is the default and it means that absolute URLs are generated to be relative to the factory's servable content area, which generally means adding the current app context name to the generated URL. For example: `/images/foo.gif` is changed to `http://some.com/MyApp/images/foo.gif`. Use <servable_content_root> of web server's default application - The Factory assumes the relative URLs within the imported page are stored in the <servable_content_root> directory of the web server's default application. In the rare case that you want `/images/foo.gif` to refer to the server's servable content root ( no added app context, select "Use <servable_content_root> of the web server's default application". The use case for this non-default behavior is a shared images directory used by more than one application.
Overwriting
Rename Existing	This input is useful in cases where you want to change the behavior of code that was placed in the WebApp by a high-level builder or by an Imported Model. For example, you might want to do this if you have a Domino View & Form builder in your model, and you want to use a different class for one of the LJO's that Builder adds to the WebApp. The Domino View and Form Builder does not provide an "LJO Class Name" input. But, we can place a new LJO Builder in the model and give it the same name as that assigned by the Domino View and From Builder, thus replacing the existing LJO and specifying new class. Enable - When checked, this input will cause the Builder to replace an existing WebApp object with a new object. The Builder will locate the existing WebApp object (variable, LJO, etc.), rename it, and then create a replacement object. Note that This input is available on the following low-level Builders that create WebApp objects: Action List, Imported Page, Linked Java Object, Linked Model, Method, Method Call, Page, Variable and Schema.