VideosCreating and Customizing WebHelp Responsive Publishing Templates


This demonstration offers an overview of the WebHelp Responsive publishing templates in Oxygen and shows you how to create a new template starting from an existing one, and how to customize various aspects of the output by making small changes in the template package.


00:00:06Starting with Oxygen version 20.0, publishing DITA content was greatly enhanced with the
00:00:12introduction of the concept of Oxygen Publishing Templates that define all aspects of the layout
00:00:18and style of WebHelp Responsive output.
00:00:21In this video demonstration I will introduce you to the concept of the Oxygen publishing
00:00:25templates and provide an example of how you can use one of the built-in templates as a
00:00:31starting point and then make some small changes to customize the WebHelp Responsive output.
00:00:37The possible benefits for using the publishing template package include:
00:00:42- You can use any of the existing built-in templates as a starting point for future customizations
00:00:47- The customized template packages are easy to share with others
00:00:52- Custom template packages remain intact even when you upgrade Oxygen to a new version
00:00:57- A publishing template can be easily integrated with a continuous integration publishing system
00:01:04Each WebHelp Responsive publishing template is a package that contains a descriptor file
00:01:09and various resources.
00:01:12The descriptor file controls the template package by defining the references to the
00:01:16other resources in the package.
00:01:19First, let's introduce you to the built-in templates.
00:01:23You can see them by editing a WebHelp Responsive transformation scenario and going to the Templates tab.
00:01:34There are two primary layout types, tree and tiles and a variety of color schemes.
00:01:41You can click on tags at the top of the pane to filter the templates and narrow your search.
00:01:47Next, I'll show you how to do some simple customizations starting from a built-in template.
00:01:54To demonstrate this, I'll use a simple documentation project.
00:01:59I'll apply one of the default transformation scenarios and ... it produces a nice, clean
00:02:05output, that I can use as a starting point for my customization.
00:02:10Ultimately, I want my output to look similar to this:
00:02:13I have a particular logo and graphics I want to use, a particular font, and I want to use
00:02:20a blue color scheme.
00:02:22back to the transformation dialog box, I'm going to select that same template and click
00:02:28"Save template as" ...
00:02:31I'll give it a suitable name ... and description.
00:02:36Next, I'll choose the name and location of the exported template.
00:02:50The saved template is packaged into a zip archive, but since I need to modify some of
00:02:55its files, I first need to unzip it.
00:03:04I no longer need the zip archive, so I'll delete it.
00:03:09... and then I'll add the newly created folder to my project to make it easier to access
00:03:16the files in Oxygen.
00:03:17Next, I'm going to open the template descriptor file.
00:03:25I'm going to make some changes to several cosmetic aspects of the template.
00:03:30I'll modify one of the color tags to "blue".
00:03:34Note that I can add as many tags as I want...
00:03:37they will make it easier to filter and find the template in the Transformation Scenario dialog box.
00:03:44Next, I need to change the preview image of the output, but I first need to add the graphic
00:03:49resources to my project.
00:03:51So, I'll create an image folder inside my template folder, and drag all the graphic
00:03:57files I will later use in my customization:
00:04:01logo, background, and a preview image.
00:04:06back to the descriptor file, I need to change the "preview-image" element to point to the correct image.
00:04:12This is the image that will be displayed for my template in the transformation dialog box,
00:04:18making it easier to identify.
00:04:21Note that the content completion assistant is available when editing the descriptor files.
00:04:25Also, I no longer need the other existing preview image, so I'll just delete it.
00:04:32For simplicity, I won't include a link to an online preview of the template, so I'll
00:04:38delete that element in the descriptor file.
00:04:41Next I'm going to start adding some custom features...
00:04:45Remember, the 3 things we want to accomplish is to add a logo, change the font, and change
00:04:52the color scheme.
00:04:54First, I'll add a 'logo' element in the 'resources' section and point to my logo file.
00:05:03Now let's see how it will look ... first I need to add my new template package to the gallery...
00:05:14so back in the transformation dialog box, I'll click "Configure Publishing Templates
00:05:19Gallery", then I'll add the folder that contains all my custom templates.
00:05:33After I click "OK"...
00:05:37I'll select my space-themed template and apply the transformation scenario.
00:05:44The logo looks ok, so now I'll customize the font face and color.
00:05:49To do this, I'll use a custom CSS layer that will be added on top of the base CSS from
00:05:56the template I started from.
00:05:58So, back in Oxygen, using the actions available in the Project view I create a new CSS file
00:06:04inside the publishing template folder.
00:06:17Back in the descriptor file, I'll add a reference to the newly created CSS file...
00:06:23after the reference to the base CSS.
00:06:28Back to the output created earlier...
00:06:31I need to identify the element I want to customize, so I'm using my browser's Inspect tool to look for its id.
00:06:44Now that I have the id, I can write the CSS rule that changes the styling of the publication
00:06:50title: first I'll set the color...
00:06:54then I'll import a font (...I'll use a Google Font called "Orbitron" since it's fitting
00:07:01for my space exploration project...) and I'll set it as the font for my publication title.
00:07:09I'll also set a font size.
00:07:19Now I'll transform my documentation project again to see how it now looks like ...
00:07:26Note that the publication title is now rendered with a new font and color.
00:07:32In a similar manner, I'm adding more CSS rules to change the color and font for more components.
00:07:41Once again, I'll transform the documentation to see the result.
00:07:47Looks great so far...
00:07:48Now I want to add a background image in the Search input component.
00:07:53Back in the CSS...
00:07:55I'll add a new CSS rule that sets a background image.
00:07:59Since the reference to this image was added inside the CSS file, the transformation process
00:08:04needs to know where the image is actually located, to copy it and use it in the final output.
00:08:11This is also the reason why I need to declare the image in the "resources" area of the descriptor file.
00:08:21I'll run the transformation scenario again...
00:08:25and this is how the output looks like.
00:08:27One final tweek...I want to change the color of the main page tiles ... to light blue color.
00:08:38These were just some very basic customizations, but with some creativity the possibilities
00:08:45are virtually limitless.
00:08:47Now I want to share my new template with the rest of the team...
00:08:52so I'll go back to the transformation dialog box, once again, I'll select "Configure Publishing
00:09:00Templates Gallery"
00:09:01and I'll switch the option at the bottom of this preferences page to "Project Options" ...
00:09:08This means that the association between my documentation project and the gallery of publishing
00:09:13templates is now saved at project level.
00:09:19Since my publishing template package is part of my project, when I share it with my team,
00:09:25they will have access to the template customization and the associated transformation scenario.
00:09:32This concludes the demonstration, as always, thanks for watching.