WebHelp Responsive Customization Methods

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

Insert Custom HTML 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 useful 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

1- webhelp.fragment.head
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed as the header in the output.
2- webhelp.fragment.before.body
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed before the body in the output.
3- webhelp.fragment.before.logo_and_title
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed before the logo and title in the output.
4- webhelp.fragment.after.logo_and_title
Specifies an XML fragment (or a path to a file that contains well formed XML content) that will be displayed after the logo and title in the output.
5- webhelp.fragment.before.top_menu
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed before the top menu in the output.
6- webhelp.fragment.after.top_menu
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed after the top menu in the output.
7- webhelp.fragment.before.main.page.search
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed before the search field in the output.
8- webhelp.fragment.welcome
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed as a welcome message (or title) in the output.
9- webhelp.fragment.after.main.page.search
Specifies an XML fragment (or a path to a file that contains well formed XML content) that will be displayed after the search field in the output.
10- webhelp.fragment.before.toc_or_tiles
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed before the table of contents or tiles in the main page of the output.
11- webhelp.fragment.after.toc_or_tiles
Specifies an XML fragment (or a path to a file that contains well formed XML content) that will be displayed after the table of contents or tiles in the main page of the output.
12- webhelp.fragment.footer
Specify an XML fragment (or a path to a file that contains well formed XML content) that will be displayed as the footer in the output
13- webhelp.fragment.after.body
Specifies an XML fragment (or a path to a file that contains well formed XML content) that will be displayed after the body in the output.
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 useful if you want to use an existing skin and it is very close to what you need, but you want to adjust 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.

Create a New WebHelp Responsive Skin

This method is useful 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/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 project (you could use one of the Oxygen XML Editor 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:
  • This method allows you to fully customize the output.
  • This method allows you to change the structure of the generated HTML files.
  • You can create your own skins for the new template.
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/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).
  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 sample projects). Also, you can use your web browser CSS inspector tool to lookup the CSS classes you want to modify.