VideosCreating a Publishing Template to Customize WebHelp and PDF Output using CSS

Overview

Duration: 14:19
This demonstration offers an overview of the Oxygen publishing templates feature and shows you how to create a new template starting from an existing one, and how to customize various aspects of WebHelp and PDF output using CSS styling.

Transcript

00:00:06In this video demonstration I will introduce you to the concept of the Oxygen publishing template.
00:00:12A feature designed to provide the ability to define all aspects of the layout and style
00:00:16of WebHelp Responsive and PDF output for DITA documentation.
00:00:19It is especially helpful for those who are familiar with CSS and HTML5 since each
00:00:25type of transformation includes CSS&HTML5 processing stages.
00:00:30More specifically, in this video I will show you how to use a built-in template as a starting
00:00:35point and then make some CSS-based changes to customize the WebHelp & PDF output.
00:00:43The possible benefits for using a publishing template package include:
00:00:48- You can use any of the existing built-in templates as a starting point for your customizations
00:00:52- The customized template packages are easy to share with others
00:00:56- Custom template packages remain intact even when you upgrade Oxygen to a new version
00:01:02- A publishing template can be easily integrated with a continuous integration publishing system
00:01:09- The same publishing template package can contain both WebHelp & PDF customizations
00:01:15so you can easily bundle and share both customizations as a single template.
00:01:20Each publishing template is a package that contains a descriptor file and various resources.
00:01:26The descriptor file controls the template package by defining the references to the
00:01:30other resources in the package.
00:01:33First, I'll introduce you to the built-in templates.
00:01:37I have a small DITA project about space exploration that I'll use for this video ...
00:01:45I'll edit a WebHelp Responsive transformation scenario.
00:01:52..and you can see all the built-in templates
00:01:55in this first Templates tab.
00:01:58Notice there are some tags at the top of the pane to help you filter the templates and
00:02:02narrow your search.
00:02:04Now, to show you how to use one of the built-in templates as a starting point to create your
00:02:09own custom template, I'll select a very plain, simple template and I'll apply the transformation
00:02:15to show you what the WebHelp output looks like from my starting point.
00:02:25Ultimately, I want my output to look something like this.
00:02:32So, to begin my customization, I'll once again edit the transformation scenario, select that
00:02:38same built-in template and I'll click the "Save template as" button.
00:02:43This opens a template configuration dialog box.
00:02:47I'll enter a suitable name and description for the template ... and I'll select the
00:02:53location where I want to save the exported package and choose a file name.
00:03:07The saved template is packaged into a zip archive,
00:03:16and since I want to modify some of its files
00:03:19, I first need to unzip it ...
00:03:22I'll delete the zip file.
00:03:26and I'll add the newly created folder to my project
00:03:29t so I can access the files directly in Oxygen.
00:03:34Remember I told you that each publishing template package contains a descriptor file.
00:03:39It has an "opt" file extension.
00:03:42So, I'll open the descriptor file in Oxygen and I'll make some structural changes according
00:03:47to what I want for my custom template.
00:03:51For example, I'll modify the tags that will be displayed in the transformation dialog box.
00:03:57You can have as many tags as you want - but for simplicity, I'll just include two
00:04:03I'll keep "tiles" and I want the 2nd one to be "blue" instead of "gray", and I'll
00:04:08delete the other one.
00:04:09Next, I want to change the preview image that will be displayed in the transformation dialog box.
00:04:16I've also prepared some other image resources that I'll use later for my customization,
00:04:22so I'll create a folder inside my project and copy all of those image files there.
00:04:39Then I'll go back to the descriptor file and change the "preview-image" element to point
00:04:43to the correct image.
00:04:47I no longer need the existing default preview image, so I'll delete it.
00:04:52Back in the descriptor file, notice there's also an online-preview-url element.
00:04:59You could use this optional element to point to a URL of a published sample of your template,
00:05:05but I won't do that for this video so I'll just delete it.
00:05:09Now I'll do some cosmetic customizations to the main page.
00:05:12First, I'll add a logo.
00:05:16I already added the logo image to my project so now I just need to change the reference
00:05:21in the descriptor file to point to it.
00:05:23The logo element goes in the 'resources' section.
00:05:27Now I want to transform it to see how it looks, but first I need to add my new template package
00:05:34to the gallery so that I can choose it from the transformation dialog box.
00:05:38To do so, I simply click "Configure Publishing Templates Gallery", then I add the folder
00:05:44that contains my custom templates ,
00:05:53...and after I click "OK" I now see that my newly
00:05:56created template is the first one displayed in the gallery.
00:05:59So, I'll select it and apply the transformation.
00:06:06The logo looks fine, but now I want to customize the font & color scheme for the title, and
00:06:12I'll use CSS styling to do this.
00:06:15So, back in Oxygen, I'll create a custom CSS that will act as a custom styling layer added
00:06:22on top of the default base CSS from the template I started with.
00:06:32Back in the descriptor file, I'll add a reference to the newly created CSS file after the reference
00:06:39to the base CSS.
00:06:41I should note that most of the elements in the descriptor file are optional, but one
00:06:46requirement is that at least one CSS file must be referenced.
00:06:50In my case, I'll use multiple CSS files.
00:06:54Then I'll switch back to the output and use my browser's Inspect tool to identify the
00:06:59element I want to customize so that I can adjust the CSS rules that are being applied.
00:07:04In this case, it's the 'wh_publication_title' class.
00:07:10Back in my custom CSS, I'll add a rule to adjust the color of the title, then I'll import
00:07:15a custom Google font and set it as the font for my title and increase the font size.
00:07:22Now I'll transform it again to see how it looks.
00:07:28Looks good so far...
00:07:31so now I want to change the styling for other components.
00:07:35So back to the CSS file...
00:07:37I'll add some more rules.
00:07:42Once again, I'll transform it to see the result.
00:07:46So far so good, but I see one final customization that I want for my main page.
00:07:52I want to add a background image that will surround the Search field.
00:07:58I'll add the styling rules in the custom CSS and I referenced an image that I added
00:08:04to the project earlier, so now I need to declare that image in the 'resources' section
00:08:10back in the descriptor file so that the transformation process will copy it to the output folder
00:08:15and use it in the final output.
00:08:22I'll run the transformation scenario again... and now I'm happy with my main page, so now
00:08:30I'll focus on the topic pages.
00:08:33This is what one of the topics looks like currently... and I want to adjust the styling
00:08:39for titles,, color and border for tables,,, and the padding for the related links section.
00:08:50Once again, I normally would use my browser's Inspect tool to identify the elements, but
00:08:55for this video, I already did that behind the scenes, so I'll add my rules to the custom CSS.
00:09:02And I'll transform it again to see how these modifications look...
00:09:09and it looks good so
00:09:10I've achieved everthing I wanted for my WebHelp output.
00:09:14Remember that one of the benefits of using Oxygen publishing templates is that the same
00:09:19template package can contain both WebHelp & PDF customizations.
00:09:23So, now I'll show you how I can use the same template for PDF output and it will reuse
00:09:29the same custom CSS styling while adding some additional styling specifically for printed media.
00:09:37First, back to the descriptor file... to use this template for PDF output, I need to
00:09:43add a new pdf section... notice that I've used a different tag and different preview
00:09:49image for my PDF version and the first 2 referenced CSS files are the same as the WebHelp version,
00:09:56but I've added an additional custom CSS file where I'll add rules for printed media.
00:10:02That CSS file doesn't exist yet, but if I hold down the control key on my keyboard and
00:10:08left click that reference, Oxygen offers an option to quickly create that file.
00:10:20Now I'll run a PDF transformation and check the output.
00:10:24I edit the scenario called DITA Map to PDF based on HTML5 & CSS...
00:10:31and since I added a PDF section in the descriptor file, you see that my custom template is there in the
00:10:38gallery for this PDF transformation scenario... so I choose my template and apply the transformation,
00:10:48and I can see how my customization looks in the PDF output before adding additional styling.
00:10:53Before I continue with my customization, here's a tip for helping you to identify the elements
00:10:59you want to customize that are specific for printed media.
00:11:02This PDF transformation creates a merged mapping file in HTML5 format and adds it to the output folder.
00:11:10So, if you go the Project view, find and expand the 'out' folder, and right-click the merged
00:11:16html file, you can select 'open with' and then 'system application', and that merged
00:11:22mapping file is opened in your default browser.
00:11:26You can then use the browser's Inspect tool to identify the elements from this HTML file.
00:11:32I mention this because headers, footers, and other CSS paged media constructs are not shown
00:11:38when you inspect the output directly.
00:11:42Back to my customization, now I'll add some rules to my custom CSS that are specifically
00:11:49for my PDF output.
00:11:51First, I want to add a background image and adjust the font size in the front page.
00:11:56Next, I'll add rules to modify the page headers and add the rocket logo in the top corner
00:12:02of the pages... and I want to hide the logo from the first page of each part of the publication...
00:12:10- and I'll add rules to adjust the font size and color for text in certain headers.
00:12:16I'll re-run the transformation to see how it looks.
00:12:22I see that the front page has changed ...
00:12:29...the logo image is there...
00:12:32and the headers look better.
00:12:35But, I think the chapter titles could be improved.
00:12:40So, I'll add rules to increase the size of the chapter numbers, move the titles below
00:12:45them, and adjust the styling of the fonts...
00:12:49I'll transform it again...
00:12:53and now I've achieved everything I wanted for my PDF output as well.
00:12:58so my custom template can now be used anytime I want to generate WebHelp or PDF output.
00:13:06The last thing I want to show you is a very simple way to share custom templates with
00:13:10other members of your team.
00:13:13I'll go to Options, Preferences, and the DITA Publishing page, I'll switch the storage option
00:13:20I'll switch the storage option at the bottom
00:13:22to "project options",
00:13:24Click OK ... and now all I have to do is share my
00:13:29project (the xpr file) with the rest of my team.
00:13:31For example, in my case, I would just commit the change to the xpr file and the custom template folder in our repository
00:13:39and once my colleagues pull the changes, they would have access to my custom template.
00:13:46In this video, I've shown how to create a custom template that can be used for both
00:13:51WebHelp and PDF output and I've shown just handful of basic CSS customizations that styled
00:13:58the output, but the possibilities are virtually limitless.
00:14:01For more information, see
00:14:04our documentation for customizing the WebHelp or PDF output.
00:14:09This concludes the demonstration, as always, thanks for watching.

Use Oxygen Feedback to ask us anything about this video.

Products

Features

Shop

Resources

Support

Company

© 2002-2024 SyncRO Soft SRL. All rights reserved.

This website was created & generated with <oXygen/>®XML Editor