HTML Page Layout Files

The HTML page layout files define the default layout of the generated pages in the output for the built-in template. There are four types of pages (main, search, topic, index) and each type of page is a simple HTML file. Each page type has various components that appear by default and each component has a corresponding element and when that element is included in the HTML file, the corresponding components will appear in the output.

Warning: It is no longer recommended for you to customize these files because if you upgrade to a newer version of Oxygen, those files may no longer produce the desired results and if new components have been added, you won't have access to them. Instead, use any of the other methods described in Publishing Template Package Contents for WebHelp Responsive Customizations.

If you do choose to customize these HTML files, each type of page is defined inside an <html-page-layout-files> element in the descriptor file.

<publishing-template>
      ...
      <webhelp>
      ...
      <!-- HTML page layout files -->
      <html-page-layout-files>
        <page-layout-file page="main" file="page-templates/wt_index.html"/>
        <page-layout-file page="search" file="page-templates/wt_search.html"/>
        <page-layout-file page="topic" file="page-templates/wt_topic.html"/>
        <page-layout-file page="index-terms" file="page-templates/wt_terms.html"/>
      </html-page-layout-files>

If you do use the html-page-layout-files element, you must specify all four types of pages (main, search, topic, index). When not specified, the files from the DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/page-templates folder will be used to define the layout of each type of page.

HTML Page Components

Each type of page contains various components that control the layout of that page. The rendering of each component depends on the context where it is placed and its content depends on the transformed DITA map.

Some of the components can be used in all four types of pages, while some are only available for certain pages. For instance, the Publication Title component can be used in all pages, but the Navigation Breadcrumb component can only be used in the Topic Page.

To include a component in the output of a particular type of page, you have to reference a specific element in that particular HTML file. All the elements associated with a component should belong to the http://www.oxygenxml.com/webhelp/components namespace.

Every component can contain custom content or reference another component. To specify where the component content will be located in the output, you can use the <whc:component_content> element as a descendant of the component element. It can specify the location as before, after, or it can wrap the component content. The following snippet contains an example of each:

<whc:webhelp_search_input class="navbar-form wh_main_page_search"
    role="form" >
    <div class="custom-content-before">Enter search terms here:</div> 
    <div class="custom-wrapper">
        <whc:component_content/>
    </div>
    <div class="custom-content-after">Results will be displayed in a new window.</div>
</whc:webhelp_search_input>

Main Page

The Main Page is the home page generated in the WebHelp Responsive output. The name of the HTML file that defines this page is wt_index.html and it is located in the following directory: DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/page-templates.

The main function of the home page is to display top-level information and provide links that help you easily navigate to any of the top-level topics of the publication. These links can be rendered in either a Tiles or Tree style of layout. The HTML page produced for the home page also consists of various other components, such as a logo, title, menu, search field, or index link.

Figure 1. Example of Main Page Components for a Tiles Style of Layout

Figure 2. Example of Main Page Components for a Tree Style of Layout

The following components can be referenced in the Main Page (wt_index.html) file:

Publication Title (webhelp_publication_title)

This component generates the publication title in the output. To generate this component, the <whc:webhelp_publication_title> element must be specified in the HTML file as in the following example:

<whc:webhelp_publication_title 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_publication_title.

Publication Logo (webhelp_logo)

This component generates a logo image in the output. To generate this component, the <whc:webhelp_logo> element must be specified in the HTML file as in the following example:

<whc:webhelp_logo 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In addition, you must also specify the path of the logo image in the webhelp.logo.image transformation parameter (in the Parameters tab in the transformation scenario). You can set the webhelp.logo.image.target.url parameter to generate a link to a URL when you click the logo image.

In the output, you will find an element with the class: wh_logo.

Search Input (webhelp_search_input)

This component is used to generate the input widget associated with search function in the output. To generate this component, the <whc:webhelp_search_input> element must be specified in the HTML file as in the following example:

<whc:webhelp_search_input 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_search_input.

Print Link (webhelp_print_link)

This component is used to generate a print icon that opens the print dialog box for your particular browser. To generate this component, the <whc:webhelp_print_link> element must be specified in the HTML file as in the following example:

<whc:webhelp_print_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_print_link.

Main Menu (webhelp_top_menu)

This component generates a menu with all the documentation topics. To generate this component, the <whc:webhelp_top_menu> element must be specified in the HTML file as in the following example:

<whc:webhelp_top_menu 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_top_menu.

You can control the maximum level of topics that will be included in the menu using the webhelp.top.menu.depth transformation parameter (in the Parameters tab of the transformation scenario).

For information about customizing the menu, see How to Customize the Menu.

Main Page Topic Tiles (webhelp_tiles)

This component generates the tiles section in the main page. This section will contain a tile for each root topic of the published documentation. Each topic tile has three sections that correspond to the topic title, short description, and image. To generate this component, the <whc:webhelp_tiles> element must be specified in the HTML file as in the following example:

<whc:webhelp_tiles 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_tiles.

If you want to control the HTML structure that is generated for a WebHelp tile you can also specify the template for a tile by using the <whc:webhelp_tile> component, as in the following example:

<whc:webhelp_tile class="col-md-4">                    
  <!-- Place holder for tile's image -->
  <whc:webhelp_tile_image/>                        
                    
  <div class="wh_tile_text">
    <!-- Place holder for tile's title -->
     <whc:webhelp_tile_title/>
                       
     <!-- Place holder for tile's shordesc -->
     <whc:webhelp_tile_shortdesc/>
  </div>
</whc:webhelp_tile>

For information about customizing the tiles, see How to Configure the Tiles on the WebHelp Responsive Main Page.

Main Page Table of Contents (webhelp_main_page_toc)

This component generates a simplified Table of Contents. It is simplified because it contains only two levels from the documentation hierarchy. To generate this component, the <whc:webhelp_main_page_toc> element must be specified in the HTML file as in the following example:

<whc:webhelp_main_page_toc 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_main_page_toc.

Index Terms Link (webhelp_indexterms_link)

This component can be used to generate a link to the index terms page (indexterms.html). If the published documentation does not contain any index terms, then the link will not be generated. To generate this component, the <whc:webhelp_indexterms_link> element must be specified in the HTML file as in the following example:

<whc:webhelp_indexterms_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_indexterms_link. This component will contain a link to the indexterms.html page.

Link to Skins Resources (webhelp_skin_resources)

This component can be used to add a link to resources for the current WebHelp skin (such as the CSS file). To generate this component, the <whc:webhelp_skin_resources> element must be specified in the HTML file as in the following example:

<whc:webhelp_skin_resources/>

In the output, you will find a link to the skin resources.

Topic Page

The Topic Page is the page generated for each DITA topic in the WebHelp Responsive output. The name of the HTML file that defines this page is wt_topic.html and it is located in the following directory: DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/page-templates.

The HTML pages produced for each topic consist of the topic content along with various other additional components, such as a title, menu, navigation breadcrumb, print icon, or side table of contents.

Figure 3. Example of Topic Page Components

The following components can be referenced in the Topic Page (wt_topic.html) file:

Publication Title (webhelp_publication_title)

This component generates the publication title in the output. To generate this component, the <whc:webhelp_publication_title> element must be specified in the HTML file as in the following example:

<whc:webhelp_publication_title 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_publication_title.

Publication Logo (webhelp_logo)

This component generates a logo image in the output. To generate this component, the <whc:webhelp_logo> element must be specified in the HTML file as in the following example:

<whc:webhelp_logo 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_logo.

Theme Menu (webhelp_theme_link)

This component is used to generate a drop-down menu for selecting the theme. To generate this component, the <whc:webhelp_theme_link> element must be specified in the HTML file as in the following example:

<whc:webhelp_theme_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_theme_link.

Search Input (webhelp_search_input)

<whc:webhelp_search_input 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_search_input.

Topic Breadcrumb (webhelp_breadcrumb)

This component generates a breadcrumb that displays the path of the current topic. To generate this component, the <whc:webhelp_breadcrumb> element must be specified in the HTML file as in the following example:

<whc:webhelp_breadcrumb 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_breadcrumb. This component will contain a list with items that correspond to the topics in the path. The first item in the list has a link to the main page with the home class. The last item in the list corresponds to the current topic and has the active class set.

Maximize to full width/Restore to normal width Link (webhelp_full_width_link)

This component is used to maximizes or restores the topic content to use the entire page space. To generate this component, the <whc:webhelp_full_width_link> element must be specified in the HTML file as in the following example:

<whc:webhelp_full_width_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: webhelp_full_width_link.

Navigation Links (webhelp_navigation_links)

This component generates navigation links to the next and previous topics. To generate this component, the <whc:webhelp_navigation_links> element must be specified in the HTML file as in the following example:

<whc:webhelp_navigation_links 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_navigation_links. This component will contain the links to the next and previous topics.

Print Link (webhelp_print_link)

<whc:webhelp_print_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_print_link.

Topic Content (webhelp_topic_content)

This component generates the content of a topic and it represent the content of the HTML files as they are produced by the DITA-OT processor. To generate this component, the <whc:webhelp_topic_content> element must be specified in the HTML file as in the following example:

<whc:webhelp_topic_content 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_topic_content.

Publication TOC (webhelp_publication_toc)

This component generates a mini table of contents for the current topic (on the left side). It will contain links to the children of the current topic, its siblings, and all of its ancestors. To generate this component, the <whc:webhelp_publication_toc> element must be specified in the HTML file as in the following example:

<whc:webhelp_publication_toc 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_publication_toc. This component will contain links to the topics referenced in the DITA map. It also includes an expand/collapse button (either to collapse or the to expand).

Topic TOC (webhelp_topic_toc)

This component generates a topic table of contents for the current topic (on the right side) with a heading named On this page. It contains links to each section within the current topic and the section corresponding to the current scroll position is highlighted. The topic must contain at least two <section> elements and each <section> must have an @id attribute. To generate this component, the <whc:webhelp_topic_toc> element must be specified in the HTML file as in the following example:

<whc:webhelp_topic_toc 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_topic_toc. This component will contain links to the sections within the current topic. It also includes an expand/collapse button (either to collapse or the to expand).

Expand/Collapse Sections (webhelp_expand_collapse_sections)

This component is used to generate an icon that expands or collapses sections listed in the side table of contents within a topic. To generate this component, the <whc:webhelp_expand_collapse_sections> element must be specified in the HTML file as in the following example:

<whc:webhelp_expand_collapse_sections 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: webhelp_expand_collapse_sections.

Topic Feedback (webhelp_feedback)

This component generates a placeholder for where the comments section will be presented. To generate this component, the <whc:webhelp_feedback> element must be specified in the HTML file as in the following example:

<whc:webhelp_feedback 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

Main Menu (webhelp_top_menu)

This component generates a menu with all the documentation topics. To generate this component, the <whc:webhelp_top_menu> element must be specified in the HTML file as in the following example:

<whc:webhelp_top_menu 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_top_menu.

You can control the maximum level of topics that will be included in the menu using the webhelp.top.menu.depth transformation parameter (in the Parameters tab of the transformation scenario).

For information about customizing the menu, see How to Customize the Menu.

Index Terms Link (webhelp_indexterms_link)

<whc:webhelp_indexterms_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_indexterms_link. This component will contain a link to the indexterms.html page.

Child Links (webhelp_child_links)

For all topics with subtopics (child topics), this component generates a list of links to each child topic. To generate this component, the <whc:webhelp_child_links> element must be specified in the HTML file as in the following example:

<whc:webhelp_child_links 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

Related Links (webhelp_related_links)

For all topics that contain related links, this component generates a list of related links that will appear in the output. To generate this component, the <whc:webhelp_related_links> element must be specified in the HTML file as in the following example:

<whc:webhelp_related_links 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

Link to Skins Resources (webhelp_skin_resources)

<whc:webhelp_skin_resources/>

In the output, you will find a link to the skin resources.

Search Results Page

The Search Results Page is the page generated that presents search results in the WebHelp Responsive output. The name of the HTML file that defines this page is wt_search.html and it is located in the following directory: DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/page-templates.

The HTML page that is produced consists of a search results component along with various other additional components, such as a title, menu, or index link.

Figure 4. Example of Search Results Page Components

The following components can be referenced in the Search Results Page (wt_search.html) file:

Publication Title (webhelp_publication_title)

This component generates the publication title in the output. To generate this component, the <whc:webhelp_publication_title> element must be specified in the HTML file as in the following example:

<whc:webhelp_publication_title 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_publication_title.

Publication Logo (webhelp_logo)

This component generates a logo image in the output. To generate this component, the <whc:webhelp_logo> element must be specified in the HTML file as in the following example:

<whc:webhelp_logo 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_logo.

Search Input (webhelp_search_input)

<whc:webhelp_search_input 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_search_input.

Search Results (webhelp_search_results)

This component is used to generate a placeholder to signal where the search results will be presented in the output. To generate this component, the <whc:webhelp_search_results> element must be specified in the HTML file as in the following example:

<whc:webhelp_search_results 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_search_results.

Print Link (webhelp_print_link)

<whc:webhelp_print_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_print_link.

Main Menu (webhelp_top_menu)

This component generates a menu with all the documentation topics. To generate this component, the <whc:webhelp_top_menu> element must be specified in the HTML file as in the following example:

<whc:webhelp_top_menu 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_top_menu.

You can control the maximum level of topics that will be included in the menu using the webhelp.top.menu.depth transformation parameter (in the Parameters tab of the transformation scenario).

For information about customizing the menu, see How to Customize the Menu.

Index Terms Link (webhelp_indexterms_link)

<whc:webhelp_indexterms_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_indexterms_link. This component will contain a link to the indexterms.html page.

Link to Skins Resources (webhelp_skin_resources)

<whc:webhelp_skin_resources/>

In the output, you will find a link to the skin resources.

Index Terms Page

The Index Terms Page is the page generated that presents index terms in the WebHelp Responsive output. The name of the HTML file that defines this page is wt_terms.html and it is located in the following directory: DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/page-templates.

The HTML page that is produced consists of an index terms section along with various other additional components, such as a title, menu, or search field.

An alphabet that contains the first letter of the documentation index terms is generated at the top of the index page. Each letter represents a link to a specific indices section.

Figure 5. Example of Index Terms Page Components

The following components can be referenced in the Index Terms Page (wt_terms.html) file:

Publication Title (webhelp_publication_title)

This component generates the publication title in the output. To generate this component, the <whc:webhelp_publication_title> element must be specified in the HTML file as in the following example:

<whc:webhelp_publication_title 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_publication_title.

Publication Logo (webhelp_logo)

This component generates a logo image in the output. To generate this component, the <whc:webhelp_logo> element must be specified in the HTML file as in the following example:

<whc:webhelp_logo 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_logo.

Search Input (webhelp_search_input)

<whc:webhelp_search_input 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_search_input.

Print Link (webhelp_print_link)

<whc:webhelp_print_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_print_link.

Main Menu (webhelp_top_menu)

This component generates a menu with all the documentation topics. To generate this component, the <whc:webhelp_top_menu> element must be specified in the HTML file as in the following example:

<whc:webhelp_top_menu 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_top_menu.

You can control the maximum level of topics that will be included in the menu using the webhelp.top.menu.depth transformation parameter (in the Parameters tab of the transformation scenario).

For information about customizing the menu, see How to Customize the Menu.

Index Terms Link (webhelp_indexterms_link)

<whc:webhelp_indexterms_link 
     xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>

In the output, you will find an element with the class: wh_indexterms_link. This component will contain a link to the indexterms.html page.

Link to Skins Resources (webhelp_skin_resources)

<whc:webhelp_skin_resources/>

In the output, you will find a link to the skin resources.