This guest blog post was written by Chris Bradley. Chris has been writing and designing technical documentation solutions for over 15 years.

For many years I wanted a simple way to provide users a button in my HTML topics that would open each topic in a perfectly formatted PDF that the user could then download.

MadCap Flare does not have this feature out-of-the-box, and commercially available solutions were not cheap and required the implementation of server-side or cloud-based software.  Any solution that was not cost-effective or complicated to install and manage would not be considered.

I recently completed a Word-to-Flare conversion project for a set of aircraft inspection manuals. Each aircraft has many different parts and systems that have to be inspected at regular intervals. Each inspection requirement would be placed into its own topic.  One requirement of the project was to have each of these inspection requirements generated into their own file that could be sent to maintenance vendors.  This was easy to do by using the PDF target advanced feature “Generate multiple documents for native PDF output” which generates a PDF file for each chapter break designated in the TOC.

This gave me an idea for my HTML to PDF solution.  Rather than server-side code that would generate a PDF file on demand, an easier solution would be to generate all the topics to individual PDF files in advance and then add a button on each topic that launched the PDF file.  However, I have many projects with hundreds of topics.  It would be very cumbersome to manually create links to each of the PDFs for each topic.   I created this JavaScript solution to automatically create the links for me.

Below you will find the requirements and JavaScript code to implement this solution into your own Flare projects.  I’m providing these procedures with one caveat: Madcap Flare is incredibly flexible to fit many publication methods. This solution may not currently work within your publication process.  However, we can always improve on this method by working together. You can reach me to send me feedback on LinkedIn.

How the Solution Works

A PDF Target is used to create individual PDF files for each topic in the Project. Those files are then stored on the web server in a specific directory.

When a user clicks the new “View PDF” button on their HTML topic, a JavaScript onclick event reads the URL of their current page:

URL = https://www.yoursite.com/html/topic.htm

Next, the script uses a substring method to remove the URL portion and only leave the topic name:

URL = topic.htm

Then, a regular expression is used to strip off the file extension:

URL = topic

Finally, the script returns the topic name back to the onclick event where it is appended to a new directory with a pdf extension:

URL = https://www.yoursite.com/pdfs/topic.pdf

Since the script uses the user’s current location to determine what PDF file will need to be retrieved, the links don’t have to be determined in advance. They are automatically generated by client-side execution of the script.

What You Need to Get Started

  1. You will need a directory on the web server that will store the generated PDF files.
  2. Once the directory is determined, you will need to add the JavaScript and button html supplied below. You will need to add your unique pdf directory to the code.
  3. You will need to create a new TOC in your existing Flare project that lists all the topics in your project (more on that later).
  4. You will need a new PDF target with the “Generate multiple documents for native PDF output” option enabled on the Advanced tab.
  5. Optionally, you may want to consider creating a new page layout for the individual files. I found this useful to include the name of the project as a variable in the PDF header in case a customer sent me a random one page file in the future and I could not easily identify the manual it was created from.
  6. The file names for the PDF will be created based on their file name in Flare and placed into a flat directory. Therefore, each topic file name must be unique across your project. Also, the script does not support file names with spaces as it does not currently URL encode them. I may add that in the next version based on feedback I receive.

Adding the JavaScript Script and Button

Open your Template Page in the Flare text editor and insert the following code where you want the button to appear.  This is probably above the body proxy or breadcrumbs proxy.

<script>
function getPDF() {
var url = encodeURI(window.location.href);
url = url.substring(url.lastIndexOf('/')+1);
const regex = /(.*)\.[^.]+$/;
url = url.match(regex);
var pdf = url[1] + '.pdf';
return(pdf);
}

</script>
<button type="button"  onclick="window.open('https://[DirectoryPathToPDFFolder]/' + getPDF(), '_blank')">View PDF </button>

Within the onclick method, replace the [DirectoryPathToPDFFolder] placeholder with the URL to the directory where your PDF files will be located.

Save and close the Template Page.

Configuring the New TOC

  1. Create a new Table of Contents and remove the default placeholder books.
  2. Open the File List panel by selecting View > File List from the ribbon. This displays all the topics in your entire project in alphabetical order. It's a great way to identify if you have two topics with the same name.
  3. Use the File List filter to only display the  .htm and .html files.
  4. Select all the files on the list (Ctrl + A or Shift + click) and drag them to the new TOC. You may have to float the File List window to easily drag the files to your TOC.
  5. Once the list of topics is pasted to the TOC, select them all (Shift + click) and open the TOC Properties window (right click > Properties).
  6. Click the Printed Output tab and set the Break Type to Chapter Break.
  7. Optionally, if you created a special page layout for these topics, select it here.
  8. Click OK and save the TOC.

Configuring the New PDF Target

  1. Create a new PDF Target and open it.
  2. On the General tab, select the new TOC you created.
  3. On the Advanced tab, select the Generate multiple documents for native PDF output option.
  4. Save the target, and then Build it.
  5. Open the output folder and verify a PDF topic exists for each topic in the Flare Project.

Publishing

  1. Build your HTML and PDF targets.
  2. Copy your output to their publication directories on your web server.
  3. Launch the HTML files and test the new View PDF button.  If nothing happens when you click your button, verify the URL you updated in the onclick event is correct.

Styling Your Button

The default style for a button is not very modern or pleasing looking.  You can modify the CSS to make it look great.  Also, you can add an image icon to your button by referencing it in the button itself. For example:

<button type="button" onclick="window.open('https://[DirectoryPathToPDFFolder]/' + getPDF(), '_blank')">ViewPDF <img src="../[PathToImage]" style="width: 16px;height: 16px;vertical-align: text-top;" /></button>

Summary

This should be enough information to implement this solution in your Flare projects.  The ongoing maintenance of this feature is quite small.  Just remember to add any new topics to the project to your new TOC and give it a chapter break.  Also, you can create a batch target with publication destinations that will build and publish both of your targets in one easy step.