WebHelp Responsive Customization Methods

There are several methods that you can use to customize your WebHelp Responsive output. This topic provides information on each of the methods and highlights its advantages so that you can choose the best possible method based upon your needs.

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.

Advantages:
  • This method is very easy, since the fragments for the placeholders can be specified in the transformation scenario.
  • Advanced knowledge of CSS styling is not required for this method.

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

Figure: 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 inserts a given XHTML fragment in the <head> element. 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.
EXAMPLE:

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.

Advantages:
  • This method could be used as a quick and easy way to make small styling changes.
  • The custom CSS can be distributed with your project and shared with other members of your team.
  • This method can be used for advanced and precise styling.
Additional Notes:
  • The fonts, images, and other resources must be stored in a remote server location.
  • This type of customization will not appear in the Templates tab of the transformation scenario. Instead, the custom CSS needs to be set as a parameter of an existing transformation scenario.

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 XSLT Processing Step of DITA WebHelp Classic Transformations.

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.

Advantages:
  • The customized skin will be available in the Templates tab of the transformation scenario.
  • The resources are encapsulated into the skin directory and can be shared with other team members, along with a custom CSS file.
Additional Notes:
  • This method requires access to the installation folder, or the use of an external DITA-OT engine (with the WebHelp plugin installed).
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.responsive/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.

Tip: During development, you may want to regularly test your customization. To shorten the publishing time of your tests, use a small set of test files (you could use one of the Oxygen XML Editor plugin sample projects). Also, you can use your web browser CSS inspector tool to lookup the CSS classes you want to modify.

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).

Advantages:
Additional Notes:
  • This method requires access to the installation folder, or the use of an external DITA-OT engine (with the WebHelp plugin installed).
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.responsive/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.

Tip: During development you regularly need to test your customization. To shorten the publishing time of your test, use a small project (you could use one of the Oxygen XML Editor plugin sample projects). Also, you can use your web browser CSS inspector tool to lookup the CSS classes you want to modify.
For more information about WebHelp Responsive templates, see the WebHelp Responsive Template Mechanism section.