Home Page Layout

Your Heretto Portal navigation and home page layout are based on the information provided in a sitemap. A sitemap is a specialized DITA map that enables you to create a structure for your content in Heretto CCMS that Heretto Portal understands and represents in the form of a documentation portal.

Search Boxes Overview

You can enable two search boxes in your Heretto Portal: one in the header and one in the hero section.

Header Search Box

You can modify the styling by editing the .ezd-portal_app-bar_search-wrapper CSS class.

Alternatively, you can override styling and settings by editing the config.json file. To learn more about editing Heretto Portal settings, refer to Customize the Heretto Portal Settings.

There is a collapsed state for the appBar search: .ezd-portal_app-bar_search-collapse for CSS and appBarSearchCollapse for config.json. It is used to determine whether or not the search icon has been clicked (desktop) or tapped (mobile) to expose the search bar. You can modify the icon with a CSS class .ezd-portal_app-bar_search-icon or with appBarSearchIcon in config.json.

The display and positioning properties for the collapsed state can be overridden to always show on desktop.

example of modified search bar — Figure 1. Example of Modified Search Bar

Hero Search Box

The search input in header is typically displayed on tablets and higher-resolution screens. You can hide or modify it by editing the .ezd-portal_hero_search-wrapper CSS class or the heroSearchWrapper object in config.json.

hero section introduced at help.heretto.com — Figure 2. Hero Section at help.heretto.com

Hero Banner

The entire page layout has a global CSS class for the page type being displayed. These classes are applied to the root element of the HTML for globally applied CSS that you may want to specify for certain types of pages.

index-root

Typically referred to as the “root page”, “root path”, “home”, or “index” page, etc.

.section-index

The first layer of the top-level site sections and potentially a version. For example:

/product/2022-r1
/customers
/content-strategies.

.search-index

The search page accessible under /search.

.content-index

Any other page or URL slug path.

By default, the hero section is shown on all pages. Below, you can see the default settings of the hero section applied in the config.json file.

"hero": {
        "position": "relative",
        "height": "auto",
        "backgroundPosition": "center",
        "backgroundSize": "cover",
        "marginBottom": "0",
        "opacity": 1,
        "alignItems": "center",
        "alignContent": "center",
        "& i18n-message": {
            "flex": 1
        },
        "&.index-root, &.section-index, &.content-index, &.search-index, &.error-index": {
            "backgroundImage": "url(https://assets.portal.heretto.com/themes/whitelabel/Geometric-Background.webp)",
        },
    },
    "heroSearchWrapper": {
        "height": "2.25rem",
        "width": "30rem",
        "margin": "0 auto",
        [MAX_S]: {
            "display": "none"
        }
},

However, you can easily override it, for example, to remove the background image throughout different pages or introduce a different image URL:

"hero": {
        "height": "350px",
        "&.index-root, &.section-index, &.content-index, &.search-index, &.error-index": { "backgroundImage": "none",
        },
   },

These settings should be always added to the theme JSON object:

{
	"theme": {
		"hero": {
        		"height": "350px",
        		"&.index-root, &.section-index, &.content-index, &.search-index, &.error-index": {
				"backgroundImage": "none",
			},
		}
	}
}

Add Section Tiles

Most important parts of your documentation can be represented with tiles on the Heretto Portal home page.

Tiles can be linked to sections of different complexity. To learn how to manage different types of sections, see Basic Site Section.

A tile is a clickable box that consists of a title, short description, and icon. On larger screens, tiles are displayed in three columns. On mobile devices, tiles are displayed either in two or in one column depending on the resolution

tiles that you can see at help.heretto.com — Figure 3. Tiles Example

The minimum required to render a tile is a navigational title added within a site section.

Open the sitemap connected to your portal.
Right-click the sitemap element and append it with the sitesection element.

Figure 4. Appending Operation
Right-click the sitesection element and append it with the topicmeta element.
Right-click the topicmeta element and append it with the navtitle element.
Right-click the topicmeta element and append it with the shortdesc element.
Right-click the topicmeta element and append it with the data element.

Your tile structure has been successfully introduced. Now, edit the contents of the displayed elements.

Edit the navtitle element to display the name that you want.
1. Hover over the navtitle element and click the gear icon. On the right, the attributes pane appears.
2. In the top-right corner of the attributes pane, click the pencil icon to edit the contents of the navtitle element.
3. Edit the contents of the navtitle tag.
  <navtitle>My First Section</navtitle>
4. Click Save.
Follow the same steps to edit the short description element.

To edit contents of the data element that represents tile's icon, do the following:

Hover over the data element and click the gear icon to open the attributes pane.
1. Fill in the name attribute with the thumbnail value.
2. Find the href attribute and click Change to select the icon that you would like to display in a tile.
Append your site section with a proper ditamap file that you would like to link to the created tile.
Figure 5. Site Section Example
An example of a basic site section. Elements marked in red are responsible for the contents displayed within a tile.

Go to the home page of your Heretto Portal and refresh it to see the newly created tile.

Add Custom Sections

You can add your own sections on the home page by using the topicgroup element.

Additional, custom sections can be used to introduce more contextual information about your Heretto Portal like:

your company description
the purpose of your Heretto Portal
icons
videos
div containers that you can use for customizing displayed modules

Tip:

By applying the outputclass attribute to DITA elements in the topics within the topicgroup, you can style them freely with the CSS code. Each outputclass value is rendered as an HTML class that can be used as a CSS selector. To learn more about Heretto Portal styling, refer to Customize Heretto Portal Styling.

Additional sections are rendered below the tiles section and above the footer of your home page.

There are no requirements related to the placement of additional sections. If they do not have to be included in the navigation, you can put them anywhere in the sitemap. However, we recommend putting them either at the beginning or at the end of your sitemap to keep its structure neat and tidy.

Open the sitemap connected to your portal.
Right-click the sitemap element and append it with the sitesection element.

Figure 6. Appending Operation
Right-click the sitesection element and append it with the topicgroup element.
Hover over the topicgroup element and click the gear icon to open the attributes tab.
1. To ensure your additional section is not displayed in the search results, set the search attribute to no.
2. To ensure your additional section is not listed in the navigation, set the toc attribute to no.
Figure 7. Properly Set Topic Group
Right-click the topicgroup element and append it with the data element.
Hover over the data element and click the gear icon to open the attributes pane.
1. Fill in the name field with the topicgroup-name value.
2. Fill in the value field with a unique meaningful value that will represent your section. This value will be later used for translation purposes. Do not use spaces or special characters.
  <data name="topicgroup-name" value="about-us"/>
  By default, the title of your section will be displayed on the home page as label.your-value. Our example will be displayed as label.about-us. To change the title of the newly created home page section, see Localize Custom Sections.
Append your topicgroup element with topics that contain contents that you would like to display on the home page.
Note:
If you want to localize your content, add a map reference instead as you can only localize maps. If you do not localize content, it is fine to add topic references instead.
The example below shows how to add an additional section with contents based on two topics: our-values.dita and see-more.dita. For your implementation, use as many topics as necessary. The example assumes that you already introduced two tiles to the sitemap: “Site Section 1” and “Site Section 2” to show you how additional sections are placed with reference to the tiles. To learn more about adding tiles, see Add Section Tiles.
```

<sitesection>
    <topicgroup search="no" toc="no">
	
        <data name="topicgroup-name" value="about-us"/>
	
        <topicref href="content/our-values.dita"/>
        <topicref href="content/see-more.dita"/>
    </topicgroup>
</sitesection>
```

Go to the home page of your Heretto Portal and refresh it to see the newly created section.

Localize Custom Sections

You can add new sections to your Heretto Portal home page. Section titles are saved as strings that need to be localized. This process also produces a valid structure even if you do not localize your content into multiple languages.

To learn more about adding new sections to the home page, refer to Add Custom Sections.

To explore general rules for strings localization in Heretto Portal, refer to Internationalized Strings Configuration Reference.

Open the sitemap connected to your portal.
Find the sitesection element related to the home page section that you want to localize.
Expand the sitesection element to see the value of the data element.
Create a localization string variable that you will use in the next steps. It follows the pattern: label.your-value. Save or remember the string.
Open the config.json file connected with your Heretto Portal.
Add your localization string for every locale that you localize your Heretto Portal to.
Remember:
Locale codes in the config.json file have to be the same as the codes that you use during the localization process in Heretto CCMS.
```
   "i18n": {
      "en-us": {
         "label.about-us":"About us"
      },
      "de-de": {
         "label.about-us":"Über uns"
      }
   }
```
To localize contents of your additional sections, follow the standard localization process. You only need localization strings for section titles.

Go to the home page of your Heretto Portal and refresh it. You should now be able to see the updated title of the section in a selected language.

Gretyl's Portal

Heretto Help