12.3 Working with HTML Templates

You can use your own HTML to create a template for a portal page and to define the format, style, and colors to be used in portlet and item regions. Create templates for pages with HTML page skins. Create templates for regions with HTML content layouts.

This section provides information on working with HTML templates in Oracle Portal. It includes the following subsections:

12.3.1 Using HTML to Define a Page Border

Using a simple wizard, you can either enter or paste a copy of your own developed HTML to define the layout, look, and feel of a portal page. You can enrich the HTML by including substitution tags to stand in for standard elements that are available through the Oracle Portal user interface. You can also add any other Web standard mark up, such as JavaScript, to increase the dynamic capability of the template. HTML page skins, as these types of templates are known, affect the appearance of the area surrounding page content.

Note:

When a page uses an HTML page skin template, the page background color is taken from the template and any background color specified in a defined style is ignored.

An exception to this is when the page skin uses a class generated by an Oracle Portal style. For example, you can place an Oracle Portal style element class in the <body> HTML tag: <BODY style="margin:0px" class="Bodyid2siteid0">. Should you change the style declaratively, through the Oracle Portal user interface, the change is reflected as well in the template that references the style class.

This enables you to change the Background Color of all pages that use the page skin through the declarative style. (For more information on Oracle Portal style element classes, see Chapter 11, "Using Portal Style Element Classes in HTML Templates and CSSs".)

This section provides information about working with HTML to create page skins. It includes the following subsections:

12.3.1.1 Creating an HTML Page Skin

Oracle Portal provides a simple wizard for creating an HTML template for a page. Enter HTML and any other tags that are valid within HTML, such as JavaScript, Oracle tags, HTML substitution tags, and the like.

For information on HTML page skin substitution tags, see Appendix E, "Substitution Tags for HTML and Unstructured UI Templates".

To create an HTML page skin template:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select a page group to own the HTML page skin.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page. If you plan to use the template across page groups, select the Shared Objects page group. However, you can always move an HTML template to the Shared Objects page group if you decide that you want to use it across different page groups later.

  4. In the Layout & Appearance section, click the Create link next to the HTML Templates heading.

  5. On the resulting page, select HTML Page Skin from the Template Type drop-down list.

  6. In the Template Name field, enter a name for the HTML page skin.

    The Template Name must be unique within its page group. Use up to 50 characters. Multibyte characters are allowed. Use any character except the following:

    , & # % \ / : * ? < > | "

    Template Name is not case-sensitive. The portal stores it in uppercase.

    Note:

    For additional information on the rules governing object naming in Oracle Portal, see Appendix D, "Object Naming Rules in Oracle Portal".

  7. In the Template Definition field, enter HTML to define the template's appearance.

    Use a combination of HTML, JavaScript, Oracle tags, and any other type of mark-up available for use in Web pages. To render Oracle Portal user interface elements within the template, use HTML page skin substitution tags. To view a list of available tags, click the link tags as substitution variables on the Create HTML Template page. For more information, see Appendix E, "Substitution Tags for HTML and Unstructured UI Templates".

    Note:

    If you want to include calls to APIs within Oracle tags, they must be granted to public. For example, you cannot use wwctx_api to obtain session context information (such as current user) within HTML templates. Instead use the appropriate substitution tags.

  8. Click Create.

    The HTML page skin is created. A link to it appears at the top of the page. Click this link to make additional changes. For information on how to make changes to the template after you leave this screen, see Section 12.3.1.3, "Editing an HTML Page Skin".

  9. Click OK.

12.3.1.2 Applying an HTML Page Skin

You can apply an HTML page skin to a navigation page, a standard page, custom pages that are based on the standard page type, a Portal Template for pages, or a Portal Template for items. Use HTML page skins to wrap an HTML table around page content and provide your own mark-up around the border of the page.

To apply an HTML page skin:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select the page group that owns the page to which to apply the template.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page.

  4. In the Layout & Appearance section, under the Pages heading, click the link to the page to which to apply the template.

    This opens the page in Edit mode.

  5. Click the Page: Properties link in the toolbar at the top of the page.

  6. On the resulting page, click the Template tab to bring it forward.

  7. Select the Use HTML Page Skin radio button.

  8. Select a template from the Use HTML Page Skin drop-down list.

    When a page group and the Shared Objects page group both have a template of the same name, the page group name is added to the template name in pick lists. For example: <template_name> (page_group_name). This assists in distinguishing between templates on pick lists.

  9. Click OK to save your changes and exit page properties.

    The page renders with the HTML page skin.

    Click Apply, rather than OK, if you want to save your changes but remain on the Template tab. Click the Preview button on the Template tab to preview how the selected HTML page skin will display.

12.3.1.3 Editing an HTML Page Skin

As you fine-tune your HTML page skin template, Oracle Portal provides a quick, convenient way to access template content for editing.

To edit an HTML page skin template:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select the page group that owns the HTML page skin to be edited.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page.

  4. In the Layout & Appearance section, under the HTML Templates heading, click the link to the page skin to be edited.

    This opens the template wizard with the selected template's content displayed.

  5. Edit the template.

  6. Click OK to save your changes and exit the wizard.

    Click Apply to save your changes and remain in the wizard. Click the Preview button to preview how the template will display.

12.3.1.4 Detaching an HTML Page Skin from a Page

Detaching an HTML page skin from a page results in the removal of the objects, formatting, and layout that were provided by the page skin template. Once the skin is detached, page content renders according to the page's default settings.

To detach an HTML page skin from a page:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select the page group that owns the page from which to detach the template.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page.

  4. In the Layout & Appearance section, under the Pages heading, click the link to the page from which to detach the template.

    This opens the page in Edit mode.

  5. Click the Page: Properties link in the toolbar at the top of the page.

  6. Click the Template tab to bring it forward.

  7. Select the Do not use a template radio button.

  8. Click OK to save your change and return to the page.

    All formatting and content provided by the template is removed. The page renders with its default display settings.

12.3.2 Using HTML to Define the Layout and Appearance of Region Content

Use HTML content layout templates to control the way items, portlet borders, and their associated attributes display within a particular region. This section describes how to create, apply, and detach from an HTML content layout. It includes the following subsections:

12.3.2.1 Creating an HTML Content Layout

Use HTML content layout templates to define the structure, colors, and fonts of region content. Apply HTML content layout templates to portlet and item regions. Oracle Portal provides a simple wizard for creating HTML content layout templates, which you can use to enter a combination of HTML, Oracle tags, HTML content layout substitution tags, and any other tags and scripting that is valid in HTML.

Note:

HTML content layouts apply only to content item types, not to navigation item types. For example, the HTML content layout selected for a region will be applied to text items in the region, but not to list of objects items.

To create an HTML content layout template:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select a page group to own the HTML content layout template.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page. To enable sharing the template across page groups, select the Shared Objects page group. However, you can always move an HTML template to the Shared Objects page group if you decide that you want to use it across different page groups later.

  4. In the Layout & Appearance section, click the Create button next to the HTML Templates heading.

  5. On the resulting page, select HTML Content Layout from the Template Type drop-down list.

  6. In the Template Name field, enter a name for the HTML content layout.

    The Template Name must be unique within its page group. Use up to 50 characters. Multibyte characters are allowed. Use any character except the following:

    , & # % \ / : * ? < > | "

    Although Template Name is not case-sensitive, the portal stores it in uppercase.

    Note:

    For additional information on the rules governing object naming in Oracle Portal, see Appendix D, "Object Naming Rules in Oracle Portal".

  7. In the Template Definition field, enter HTML to define the template's appearance.

    Use a combination of HTML, Oracle tags, HTML content layout substitution tags, and any other tags and scripting that is valid in HTML. To view a list of available HTML content layout substitution tags, click the link tags as substitution variables on the Create HTML Template page. For more information, see Appendix E, "Substitution Tags for HTML and Unstructured UI Templates".

    Note:

    If you want to include calls to APIs within Oracle tags, they must be granted to public. For example, you cannot use wwctx_api to obtain session context information (such as current user) within HTML templates. Instead use the appropriate substitution tags.

  8. Click Create.

    The HTML content layout is created. A link to it appears at the top of the page. Click this link to make additional changes. For information on how to make changes to the template after you leave this screen, see Section 12.3.2.3, "Editing an HTML Content Layout".

  9. Click OK to exit the wizard once you edit the template; or click Cancel to exit the wizard without editing the template.

12.3.2.2 Applying an HTML Content Layout

You can apply an HTML content layout to any editable item or portlet region. Before you can apply a content layout, the region type must be defined. You cannot apply an HTML content layout to an undefined region.

On pages that are based on a template, some regions are not editable. However, if the template includes a tab, users with enough privilege to edit a page can add another tab with an editable region. In such a case, the user could apply an HTML content layout template to the editable region on the new tab.

To apply an HTML content layout template:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select the page group that owns the page to which to apply the HTML content layout template.

  4. Under Pages in the Layout & Appearance section, click the link to the page to which to apply the template.

    This opens the page in Edit mode.

  5. Click the Edit Region icon on the region where you will apply the template (Figure 12-8).

    Figure 12-8 The Edit Region Icon

    Edit Region icon
  6. On the resulting page, click the Attributes tab to bring it forward.

  7. Select Use HTML Content Layout.

    The option to use a content layout is selectable on the Attributes tab only when at least one content layout is defined in the page group or the Shared Objects page group.

  8. Select a content layout from the HTML Content Layout drop-down list.

    When a page group and the Shared Objects page group both have a template of the same name, the page group name is added to the template name in pick lists. For example: <template_name> (page_group_name). This assists in distinguishing between templates on pick lists.

  9. Click OK.

    Region content is formatted as specified in the content layout template.

12.3.2.3 Editing an HTML Content Layout

As you fine-tune your HTML content layout template, Oracle Portal provides a quick, convenient way to access template content for editing.

To edit an HTML content layout template:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select the page group that owns the HTML content layout.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page.

  4. In the Layout & Appearance section, under the HTML Templates heading, click the link to the template to be edited.

  5. Edit the template.

  6. Click Apply to save your changes without exiting, or click OK to save your changes and exit the wizard.

12.3.2.4 Detaching an HTML Content Layout Template from a Region

Detaching an HTML content layout from a region results in the removal of the objects, formatting, colors, fonts, and layout that were provided by the content layout template. Items or portlets continue to display in the affected region along with any default attributes selected for the region's attribute settings.

To detach an HTML content layout template from a region:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select the page group that owns the page from which to detach the template.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page.

  4. In the Layout & Appearance section, under the Pages heading, click the link to the page from which to detach the template.

    This opens the page in Edit mode.

  5. Click the Edit Region icon over the region that uses the HTML content layout template to be detached (Figure 12-9).

    Figure 12-9 The Edit Region Icon

    Edit Region icon
  6. On the resulting page, click the Attributes tab to bring it forward.

  7. Change the selection from Use HTML Content Layout to Select Attributes.

  8. Click OK.

12.3.3 Using HTML to Create Templates for Database Portlets

The HTML templates you create for database portlets are also known as Unstructured User Interface templates, or UI templates. UI templates control the look and feel of the Web page on which an Oracle Portal database portlet is rendered when the portlet displays in full-page mode. Database portlets are those portlets built under the ownership of Portal Database Providers (as opposed to Web providers).

Unstructured User Interface templates are based on HTML code that you supply. You can enter the code directly into the template wizard, or create it using a third-party tool, then cut and paste that HTML into the wizard. Additionally, you can enter substitutions tags to stand in for such information as the current user's name, the Oracle Portal images directory, the portal schema owner, and the like.

You can also use <oracle></oracle> tags to include SQL statements or PL/SQL blocks in your UI template. Additionally, you can include HEAD elements, such as custom JavaScript, cascading style sheet references, and META tags.

By applying a UI template to a database portlet, you can automatically specify a portlet title, a title background, links to home and help pages, and background colors and images. UI templates are good for standardizing groups of database portlets in a provider. For example, you can design a UI template for a provider that includes the company logo in the heading, the company name in the title, and an industry-related background image. By seeing that every database portlet in the provider uses the same UI template, you can ensure that such portlets display in a standard, controlled way to all users.

This section describes how to work with UI templates. It includes the following subsections:

12.3.3.1 Creating an Unstructured User Interface Template

To create an unstructured UI template:

  1. Log in to Oracle Portal.

  2. Click the Navigator link at the top of the page.

  3. Click the Providers tab to bring it forward.

  4. Click the Locally Built Providers link.

  5. Click the Shared Components link.

  6. Click the User Interface Templates link.

  7. Next to Create New, click the User Interface Template link.

  8. Click the Unstructured UI Template link.

  9. In the Template Name field, enter a name for the template.

    The name must be unique within the objects in the Shared Components provider. Use up to 50 bytes. This equals 60 ASCII bytes, but fewer multibyte characters. Use any character except the following:

    , & # % \ / : * ? < > | "

  10. In the Template Definition field, enter the HTML or other Web-standard code for your template.

    Click the tags as substitution variables link for a list of substitution tags available for use in your template. See Appendix E, "Substitution Tags for HTML and Unstructured UI Templates" for a list and description of these database portlet substitution tags.

    You can use <oracle></oracle> tags in your HTML to include SQL statements or PL/SQL blocks in your template.

    Note:

    If you want to include calls to APIs within Oracle tags, they must be granted to public. For example, you cannot use wwctx_api to obtain session context information (such as current user) within HTML templates. Instead use the appropriate substitution tags.

  11. Click Preview to see how the template definition displays.

  12. Click Create when you are finished to save your changes and exit the wizard.

12.3.3.2 Applying an Unstructured User Interface Template

Data components always display within the context of a UI template when viewed in full-page mode. They use either a default template provided by the portal or a template you select. You cannot detach a UI template from a data component, but you can select a template other than the default. Additionally, should you want a data component to display on a blank page when displayed in full-page mode, you can create a simple template that does not include any colors, objects, or formatting, then select that in lieu of a populated UI template.

You can apply a UI template when you create a data component or when you edit one. This section describes how to apply a UI template when you edit a data component.

To apply a UI template:

  1. Log in to Oracle Portal.

  2. Click the Navigator link at the top of the page.

  3. Click the Providers tab to bring it forward.

  4. Click the Locally Built Providers link.

  5. Under the Name column, click the link to a database provider that contains the data component to which to apply a template.

  6. On the resulting page, click the Edit link next to the data component (portlet) to which to apply a template.

  7. Click the final tab in the series, Data Component and Personalization Form Text (Figure 12-10).

    Figure 12-10 Data Component and Personalization Form Text Tab Icon

    Data Component and Personalization Text tab icon
  8. From the Template drop-down list, select the UI template to apply to the data component.

  9. Click OK to save your change and go to the Develop Data Component screen.

    You can perform additional management tasks on the data component on this screen.

  10. Click Close to return to the Portal Navigator.

12.3.3.3 Editing an Unstructured User Interface Template

To edit an unstructured UI template:

  1. Log in to Oracle Portal.

  2. Click the Navigator link at the top of the page.

  3. Click the Providers tab to bring it forward.

  4. Click the Locally Built Providers link.

  5. Click the Shared Components link.

  6. Click the User Interface Templates link.

  7. Click the Edit link next to the UI template to be edited.

  8. Make your changes to the template.

    If you change the name of the UI template, keep in mind that the name must be unique among the object names within the Shared Components provider. Use up to 50 bytes. This equals 60 ASCII bytes, but fewer multibyte characters. Use any character except the following:

    , & # % \ / : * ? < > | "

  9. Click OK to save your changes.

12.3.3.4 Deleting an Unstructured User Interface Template

When you delete an unstructured UI template, the default template is automatically applied to any components that used the deleted template. The default unstructured UI template is the one at the top of the pick list of unstructured UI templates.

To delete an unstructured UI template:

  1. Log in to Oracle Portal.

  2. Click the Navigator link at the top of the page.

  3. Click the Providers tab to bring it forward.

  4. Click the Locally Built Providers link.

  5. Click the Shared Components link.

  6. Click the User Interface Templates link.

  7. Click the Delete link next to the UI template to be deleted.

  8. On the resulting page, click Yes to confirm the deletion.

12.3.4 Copying HTML Templates

A quick way to create a new HTML template is to copy an existing one. The procedures for copying HTML templates differs between unstructured user interface templates and the other types of HTML templates. This section describes both procedures. It includes the following subsections:

12.3.4.1 Copying an HTML Page Skin or Content Layout Template

To copy an HTML page skin or content layout template:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. From the Page Groups portlet Work In drop-down list, select the page group that owns the HTML template to be copied.

    By default, the Page Groups portlet is located on the Build tab of the Portal Builder page.

  4. In the Layout & Appearance section, click the Browse link next to HTML Templates.

  5. On the resulting Portal Navigator page, click the Copy link next to the HTML template to be copied.

  6. In the New Template Name field, provide a new name for the template.

    The New Template Name must be unique within its page group. Use up to 50 characters. Multibyte characters are allowed. Use any character except the following:

    , & # % \ / : * ? < > | "

    Although Template Name is not case-sensitive, the portal stores it in uppercase.

    Note:

    For additional information on the rules governing object naming in Oracle Portal, see Appendix D, "Object Naming Rules in Oracle Portal".

  7. Click OK to save your change and exit the Copy Template page.

12.3.4.2 Copying an Unstructured User Interface Template

To copy an unstructured UI template:

  1. Log in to Oracle Portal.

  2. Click the Navigator link at the top of the page.

  3. Click the Providers tab to bring it forward.

  4. Click the Locally Built Providers link.

  5. Click the Shared Components link.

  6. Click the User Interface Templates link.

  7. Click the Copy link next to the UI template to be copied.

  8. Edit the value in the New Template Name field.

  9. Click OK to save your change.

12.3.5 Sharing an HTML Template Across Page Groups

Move an HTML Template to the Shared Objects page group to make it available for use in all portal page groups.

Note:

Objects can be moved to the Shared Objects page group—whose default language is English—from a non-English page group only if the object already has an English translation. This applies to all promotable objects:

  • Item types

  • Page types

  • Attributes

  • Categories

  • Perspectives

  • Styles

  • HTML templates

To move an HTML template to the Shared Objects page group:

  1. Log in to Oracle Portal.

  2. Click the Build tab to bring it forward.

  3. Click the Navigator link at the top of the page.

    This opens the Portal Navigator.

  4. In the Portal Navigator, click the Page Groups tab to bring it forward.

  5. Click the page group link for the page group that contains the style to be moved.

  6. On the resulting page, click the HTML Templates node.

    Only the HTML templates you are authorized to see and the actions you are authorized to perform are displayed.

  7. Click the Moved to Shared link next to the HTML template to be moved to the Shared Objects page group.

  8. In the confirmation page, click Yes to move the HTML template.