How to adapt the WebHelp template

One publishing format that DoX CMS supports is WebHelp. They are HTML publications which are set inside a template that shows the table of contents together with one topic at a time. The template was originally made primarily for our internal use. As such, you must change many details with style sheets when you publish other documents in this format. I will show how to do this in this piece. I will also add this information in our user manual later.

We have also outlined a more comprehensive solution for how users can edit their WebHelp templates. This solution will let you select the components that your WebHelp publications will include. For example, you ought to be able to use custom headers and footers like you already can with PDF publications. In this piece, I will only focus on the currently available methods that involve style sheets, though.

Style sheets are based on CSS. This piece is helpful mostly to those who have access to someone who can write style sheets. We can also write the required style sheets for our customers when they adopt the system or as a separately billed service.

Default template

The image above shows what the default template for WebHelp publications looks like. This image comes from the user manual for DoX CMS. It shows all the components that can be changed with the methods that I discuss below. This components consist of

1. default identifiers,
2. the table of contents,
3. the content field,
4. the find field,
5. forward and back buttons, and
6. a default style.

WebHelp publications include a default style sheet that they use in addition to the style sheets from the style that you selected. You cannot change this style sheet directly. You can, however, change which values apply through other style sheets. Sometimes, such changes must involve the ‘!important’ qualifier as the examples below show. You should make a separate style sheet for the changes related to WebHelp. You can then use it together with other style sheets as a new style in DoX CMS. Each style can include more than one style sheet.

Inspect feature

You can review the different parts of WebHelp publications and the previews for other publications with the Inspect command on your browser. When you click on a part of the view with the righthand mouse button and select this command, the browser shows the different parts of the view in its sidebar. When you select one of these parts, the browser also shows all the rules related to it in all active style sheets.

This feature lets you see the identifiers for the different parts of the view and the rules that apply to them at the time. You can also make temporary changes to their style with the browser. You must still add all these changes separately to add them to new publications.

Default identifiers

Because WebHelp publications were originally added for DoX CMS‘s user manual, the default template mentions DoX Systems. You can remove them and replace them with more appropriate pieces of text.

There are two positions for default identifiers: at the bottom of the table of contents and in the upper right corner. The bottom of the table of contents says ‘www.dox.fi | © DoX systems’. The upper right corner says ‘DoX Content Management System | DOX USER MANUAL’. You cannot change these pieces of texts direcrly but you can hide them and replace them with content that you add in a nearby position.

How the default identifiers were replaced in the pictures across this piece is shown below:

• You hide the default identifier in the table of contents when you do not show the p element in the .tocFooter section. When you then add a ::before pseudoelement to the .tocFooter section, it has the same position. You can change the content of this pseudoelement in a style sheet. Language identifiers also let you use different values for different languages in the same way as the title of note elements.
• You can remove the default identifier in the upper right corner when you do not show the .documentHeaderTitle section. There is an empty section with the identifier .documentHeaderLogoWrapper next to it. You can put it in the same position as the default identifier and add content to it with a ::before pseudoelement.

.tocFooter p {
    display: none;
}

.documentHeaderTitle {
    display: none !important;
}

.tocFooter::before {
    content: "© Aperture Inc 2022";
    position: relative;
    left: 50%;
    color: white;
}

.documentHeaderLogoWrapper::before {
    content: "Aperture Inc | Glimpse the Future";
    padding-left: 80%;
    white-space: nowrap;
    color: white;
    font-size: 1.5em;
}

.documentHeaderLogoWrapper {
    display: flex;
    flex-grow: 1;
    align-self: flex-end;
}

Table of Contents

You can move the table of contents on the other side of the view or even on the top or at the bottom of it. You can also freely change the details of its style such is its color. The majority of such changes involve the same rules as changes to the table of contents in all publications. I discuss those unique to WebHelp publications below.

Layout for the table of contents

How the table of contents was changed in the pictures across this piece is shown below:

• I changed the icon for the table of contents in two ways. Only one of them shows in the pictures, though. I used the selector ‘.tocTitleWrapper h1 > span:before’ to do this. The content uses a value in the Font Awesome icon font. The current template uses the free 4.3 version and its icons but we will update the the icon font to a newer version. The other option is to have no visible content and to change its background image to the icon of your choice.
• I changed the backgrounds of the table of contents and its to an image and an accompanying color. The table of contens proper is inside the .documentTOCWrapper section and its title is in the .tocTitleWrapper section.
• I did not change anything besides the value for the default identifier in the footer for the table of contents. However, you can use the .tocFooter section to do so.
• I changed the button that shows and hides the table of contents to a different Font Awesome icon. You control this button with the ‘.documentHeaderTrigger::before’ selector and the content rule.

.tocTitleWrapper h1 > span:before {
    content: "\f1ea" !important;
    color: transparent;
    background-image: url(/Content/Images/camera-aperture-icon.png); 
    background-size: auto 100%;
    background-repeat: no-repeat;
    background-position: top left;
}

.documentTOCWrapper {
    background-image: url("https://static.vecteezy.com/system/resources/previews/002/024/449/original/abstract-black-and-gray-vertical-stripes-geometric-pattern-background-vector.jpg");
}

.tocTitleWrapper {
    background-color: black !important; 
}

.tocFooter {}

.documentHeaderTrigger::before {
    content: "\f0c9" !important;
}

The position of the table of contents

You can also put the table of contents in a different position. In addition to the rules that I show here you should put the button that shows and hides the table of contents in a new position and possibly change how sections’ rounded corners work. You can also hide the button that shows and hides the table of contents.

Righthand side

I moved the table of contents to the righthand side in the above image with these changes in the style sheet:

• The selector ‘.documentTOCWrapper, .documentTOCWrapper.open’ targets the table of contents both when it shows and when it is hidden. Because our WebHelp publications use a flexbox layout, you can move the table of contents on the other side of the view when you use the order command on it with a higher value than for the .documentBodyWrapper section.
• The border-radius command with a value of 0 in the .documentBodyWrapper section removes rounded borders between content and the table of contents. You can keep them with the correct rules but this is the simplest way to not break the view when you move the table of contents to the other side.

.documentTOCWrapper, .documentTOCWrapper.open {
    order: 2;
}

.documentBodyWrapper {
    order: 1;
    border-radius: 0 !important;
}

Vertical position

I moved the table of contents to a vertical relative position in the above image with these changes in the style sheet:

• You can change the flexbox to use a vertical direction when you use the value ‘column’ with the flex-direction rule on the .documentWrapper section.
• You should make the table of contents as wide as the rest of the view. You can use the ‘.documentTOCWrapper, .documentTOCWrapper.open, .tocWrapper’ selector for this. You must use the ‘!important’ qualifier with this command because hiding the table of contents is related to its width value.
• To hide content vertically, you must use the height value of the table of contents instead of its width. The .documentTocWrapper.open section’s height is the default. The .documentTOCWrapper section’s height is used when the table of contents is hidden.
• Otherwise, this involves the same rules as when you move the content to the righthand side. The table of contents moves to the top of the view by default. If you make the value for the order rule higher for the table of contents than for the content, the table of contents shows at the bottom of the page. I made this value to a comment with the identifiers ‘/*’ and ‘*/’ around it because it is optional to move the table of contents to the bottom of the page.

.documentWrapper {
    flex-direction: column;
}

.documentTOCWrapper, .documentTOCWrapper.open, .tocWrapper {
    width: 100% !important;
}

.documentTOCWrapper.open {
    height: 60%;
}

.documentTOCWrapper {
    height: 2%;
}

.documentBodyWrapper {
    order: 1;
    border-radius: 0 !important;
}

.documentTOCWrapper, .documentTOCWrapper.open {
    /*order: 2;*/
}

Content field

The layout and style of the content proper are details that you can control with a style sheet. Such details include their background and the width of the content.

How the style of the content field was changed in the pictures across this piece is shown below:

• Sections other than the table of contents are part of the .documentBodyWrapper section. I changed its color below.
• The contents are inside the .topicWrapper section. In this case, I made its color ligher relative to the dark background. I also added horizontal padding as part of this change. If you must change the width of this section, you mist use max-width rule and the ‘!important’ qualifier. I made this value to a comment with the identifiers ‘/*’ and ‘*/’ around it because the pictures here do not involve this change. The user manual for DoX CMS uses a wider content field at this time, though.

.documentBodyWrapper {
    background-color: #666 !important;
}

.topicWrapper {
    background-color: rgba(255,255,255,0.35);
    padding: 0% 2%;
    height: 100%;
    /*max-width: 50% !important*/
}

Find field

You can also change the details of the find field for content searches.

How the style of the find field was changed in the pictures across this piece is shown below:

• The background of the find field is lighter because of the darker background of the .documentHeaderSearchForm section.
• You can change the style of the whole find field with rules added to the .documentHeaderSearchWrapper section. You can, for example, move this section or add text to it with pseudoelements.
• The ‘.documentHeaderSearchForm::before’ selector lets you change the magnifying glass to a different icon or to remove it. This involves the same methods as changing icons elsewhere or hiding sections.
• The input field for the find feature uses the #search section.

.documentHeaderSearchForm {
    background-color: rgba(255,255,255,0.35) !important;
}

.documentHeaderSearchWrapper {}

.documentHeaderSearchForm::before {}

#search {}

Forward and back buttons

The WebHelp template in DoX CMS has forward and back buttons that let you change the topic that shows directly rather than through the use of the table of contents. By default, these buttons are below the content. However, you can move them and change their style.

How the default style for content was changed in the pictures across this piece is shown below:

• In this case, I moved the forward and back buttons with a change to the relative position of the .padinationWrapper section. Because the section is not below other content, I removed its background color. You can also use other methods such as a flexbox that includes the sections around them together with the order command discussed above.
• I separated the buttons on either side of content with a .pagination section that is wider than the .paginationWrapper section around it. If you make the .paginationWrapper section wider with relative units such as percents, it will turn the whole view too wide.
• You can change the style of the text for the forward and back buttons with the selector ‘.pagination a’. I changed the color of this text to white.
• The sections .paginationPrev and .paginationNext let you target the individual buttons. I separated the two into blocks with a width value that fits their new positions. I also used the float rule to position the two blocks at each end of the section around them.
• Voit muuttaa siirtymäpainikkeiden ikoneita kohdentajalla ‘.paginationPrev a:before, .paginationNext a:after’. Tässä tapauksessa tein niiden pallosta mustan. Voit vaihtaa niiden nuoli-ikonit voi samalla tavoin kuin muut WebHelp-pohjan ikonit.

.paginationWrapper {
    background-color: transparent !important;
    position: relative;
    top: -70%;
    left: -35%;
}

.pagination {
    width: 170% !important;
}

.pagination a {
    color: white !important;
}

.paginationPrev, .paginationNext {
    display: inline-block !important;
    width: 13% !important;
}

.paginationPrev {
    float: left !important;
}

.paginationNext {
    float: right !important;
}

.paginationPrev a:before, .paginationNext a:after {
    background-color: black !important;
}

Default style

The most relevant details in the default style for the contents of the WebHelptemplate are related to titles. You can control them as usual and use the ‘!important’ qualifier where you must. The example that I used below removes the orange background from the titles of first level topics. If you see other details related to layout or style that relate to .static.css or doc.css according to the control panel, they involve the WebHelptemplate’s default style.

Alta löytyvät tämän artikkelin kuvissa käytetyt keinot hallinnoida oletustyyliä:

• The titles for first level topics (h1) have an orange background with rounded corners by default. You can hide this background when you you make it transparent.
• Some titles use orange text by default. The examples below show one way to change their color. This is all part of how you normally use style sheets in DoX CMS. Details such as the background color also make it a good idea to change the color of titles in WebHelp publications.
• You can also change the style of the scrollbars. Both W3C and the Mozilla developer resources contain instructions for this. My implementation below shows how you can hide them. This involves the risk that users will not see some content, though, because they will not know that they should scroll down. A better implementation would involve thinner and perhaps partly transparent scrollbars.

h1 {
	background-color: transparent !important;
}

.titleWrapper * {
	color: white;
}

*::-webkit-scrollbar {
	display: none;
}