Edit online

How to Configure the Tiles on the WebHelp Responsive Main Page

The tiles version of the main page of the WebHelp Responsive output displays a tile for each topic found on the first level of the DITA map. However, you might want to customize the way they look or even to hide some of them.

Depending on your particular setup, you can choose to customize the tiles either by setting metadata information in the DITA map or by customizing the CSS that is associated with the DITA map.

How to Hide Some of the Tiles

If your documentation is very large or there is a large number of topics on the first level, you might want to hide some of the tiles. Also, this might be useful if you only want to display the topics in the first page that are most relevant to your intended audience.

There are two methods for doing this. One of them involves editing the DITA map and marking the topics that do not need to be displayed as tiles, and another one that uses a small CSS customization level to hide some tiles identified by the ID of the topic.

Editing the DITA Map
To edit the metadata in the DITA map to control which topics on the first level of the DITA map will not be displayed as a tile, follow these steps:
  1. Open the DITA map in the Text editing mode of Oxygen XML Author Eclipse plugin.
  2. Add the following metadata information in the <topicref> element (or any of its specializations) for each first-level topic that you do not want to be displayed as a tile:
    <topicmeta>
      <data name="wh-tile">
        <data name="hide" value="yes"/>        
      </data>
    </topicmeta>
Customizing the CSS
To customize the CSS to control which topics on the first level of the DITA map will not be displayed as a tile, follow these steps:
  1. Make sure you set an ID on the topic you want to hide.
  2. Create a new CSS file that contains a rule that hides the tile generated for the topic (identified in the following example by the topic ID growing-flowers). The CSS file should have content that is similar to this:
    .wh_tile [data-id='growing-flowers'] {
      display:none;
    }
  3. Reference the CSS file in a WebHelp Responsive transformation using an Oxygen Publishing Template or the args.css parameter.

How to Add an Image to the Tiles

There are two methods that you can use to add an image to a tile. One of them involves editing the DITA map, and the other uses a CSS customization.

Editing the DITA Map
To edit the metadata in the DITA map to set an image to be displayed in a tile, follow these steps:
  1. Open the DITA map in the Text editing mode of Oxygen XML Author Eclipse plugin.
  2. Add the following metadata information in the <topicref> element (or any of its specializations) for each first-level topic that will have an image displayed in the corresponding tile:
    <topicmeta>
      <data name="wh-tile">
        <data name="image" href="img/tile-image.png" format="png">
         <data name="attr-width" value="64"/>
         <data name="attr-height" value="64"/>
        </data>
      </data>  
    </topicmeta>
    Note: The @attr-width and @attr-height attributes can be used to control the size of the image, but they are optional.
Customizing the CSS
To customize the CSS to set an image to be displayed in a tile, follow these steps:
  1. Make sure you set an ID on the topic that you want the tile to include an image.
  2. Create a new CSS file that contains a rule that associates an image with a specific tile. The CSS file should have content that is similar to this:
    .wh_tile[data-id='growing-flowers']> div {
        background-image:url('resources/flower.png');
    }
  3. Reference the CSS file in a WebHelp Responsive transformation using an Oxygen Publishing Template or the args.css parameter.