WebHelp Responsive Customization Methods

Insert Custom XHTML Fragments in Predefined Placeholders

The WebHelp Responsive template contains a series of component placeholders. Some of these placeholders are left empty in the default output configurations, but you can use them to display custom content. This method is recommended if you want to use an existing skin and simply make some minor changes or additions in certain locations within the final output.

Each such placeholder has an associated parameter in the transformation scenario Parameters tab. These predefined empty placeholder parameters are illustrated and described below:

Predefined Placeholders Diagram

Each of these parameters can hold either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment:

1- webhelp.fragment.head

In the generated output it displays a given XHTML fragment as a page header. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

2- webhelp.fragment.before.body

In the generated output it displays a given XHTML fragment before the page body. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

3- webhelp.fragment.before.logo_and_title

In the generated output it displays a given XHTML fragment before the logo and title. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

4- webhelp.fragment.after.logo_and_title

In the generated output it displays a given XHTML fragment after the logo and title. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

5- webhelp.fragment.before.top_menu

In the generated output it displays a given XHTML fragment before the top menu. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

6- webhelp.fragment.after.top_menu

In the generated output it displays a given XHTML fragment after the top menu. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

7- webhelp.fragment.before.main.page.search

In the generated output it displays a given XHTML fragment before the search field. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

8- webhelp.fragment.welcome

In the generated output it displays a given XHTML fragment as a welcome message (or title). The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

9- webhelp.fragment.after.main.page.search

In the generated output it displays a given XHTML fragment after the search field. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

10- webhelp.fragment.before.toc_or_tiles

In the generated output it displays a given XHTML fragment before the table of contents or tiles in the main page. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

11- webhelp.fragment.after.toc_or_tiles

In the generated output it displays a given XHTML fragment after the table of contents or tiles in the main page. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

12- webhelp.fragment.footer

In the generated output it displays a given XHTML fragment as the page footer. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

13- webhelp.fragment.after.body

In the generated output it displays a given XHTML fragment after the page body. The value of the parameter can be either an XHTML fragment or a path to a file that contains a well-formed XHTML fragment.

To insert a message above the search field component in the main page of the output, follow this procedure:

1. Edit the WebHelp Responsive transformation scenario.
2. Go to Parameters tab and find the parameter associated with the place holder that you want to use. In this case, it is called webhelp.fragment.welcome.
3. Edit the parameter. Depending on the size of the content you want to add, you can insert one of the following:
   • A small well-formed XHTML fragment, such as: <i>Welcome to our user guide</i>.
   • A path to a file that contains well-formed XHTML content.

Customize WebHelp Output with a Custom CSS

This method is recommended if you just want to adapt an existing skin (that is very close to what you need) and only need to change the styling of the final output. For example, this might be the case if you simply want to change a color, or adjust some of the margins or paddings of certain components.

To set a custom CSS to a transformation scenario:

1. Edit the WebHelp Responsive transformation scenario.
2. Open the Parameters tab.
3. For a DITA transformation, set the args.css parameter to the path of your custom CSS file. Also, set the args.copycss parameter to yes to automatically copy your custom CSS in the output folder when the transformation scenario is processed. Also, if your customization CSS requires additional resources, you can copy them to the generated output by specifying the webhelp.custom.resources parameter.

If you are using DITA, you could also override the default XSLT templates that are used for WebHelp transformations by using some extension points. For information about this method, see Overriding the XSLT Processing Step of a DITA WebHelp Transformation.

Create or Customize a WebHelp Responsive Skin

This method is recommended if you want a design that is not similar to any of the predefined skins, or if you want to make a lot of changes to one of the existing skins. This method is also useful if you want to distribute additional resources (such as fonts and images) together with a custom CSS.

To create a new WebHelp Responsive skin, follow this procedure:

1. Locate the following folder in your DITA-OT directory (DITA_OT_DIR):

   DITA_OT_DIR/plugins/com.oxygenxml.webhelp/templates/dita/bootstrap/variants/

2. Here you can see some subdirectories corresponding to different variants for the same template. For instance, the default directories are tiles and tree.
3. In each of these variants, you will find a directory for each of the skins (for example, the default skins and their corresponding directories are: flowers, green, light, mechano, orange, etc.)
4. Duplicate one of the skin folders and rename it to whatever you want your new skin to be identified as.
5. Edit the skin.css file and customize it the way you want. If your customization of the CSS file requires additional resources (such as images, fonts, or other CSS files), they need to be placed in the resources folder at the same level with the skin.css file.

   Result: Your new skin should now be included in the list of skins in the Templates tab of the transformation scenario.

Create a New WebHelp Responsive Template

This method can be used when you need to make significant structural changes to the WebHelp output. For example, if you want to move some components to other positions, or if you want to use a different responsive front-end framework than the default Bootstrap framework (for instance, if you want to switch to ZURB Foundation).

To create a new WebHelp Responsive template, follow these steps:

1. Locate the following folder in your DITA-OT directory (DITA_OT_DIR):

   DITA_OT_DIR/plugins/com.oxygenxml.webhelp/templates/dita/

2. Duplicate the bootstrap folder and rename it to whatever you want your new template to be identified as (for example, myTemplate).
3. Customize the structure of the new template according to your needs. For example, if you only want to keep one of the template variants, open the myTemplate/variants folder and delete all of its subdirectories, except for that one (for instance, the tiles directory). Keep in mind that the structure of the template directory is important. The names of folders at certain levels correspond to the names of templates and skins, while components and resources are defined and referenced in certain files or folders at specific locations within the directory structure. For more information, see WebHelp Responsive Template Directory Structure.
4. You can also customize the structure of the skins within the template variants. For example, if you only want to keep one of the skins in the tiles variant, open the myTemplate/variants/tiles folder and delete all of its subdirectory skins, except for that one (for instance, the light directory).
5. Edit the skin.css file that is located in the skin directory (for example, myTemplate/variants/tiles/light) and customize it the way you want. If your customization of the CSS file requires additional resources (such as images, fonts, or other CSS files), they need to be placed in the resources folder at the same level with the skin.css file.

   Result: Your new templates and skins should now be included in the Templates tab of the transformation scenario.