Reply To: Insert an image to the PDF cover page that fills up the whole page

[Derek Read]

Here is another strategy. It is difficult to give you “the” answer as there can really be no best way to do what you want.

The following should place a background image on the title page (you might also call that the “cover”) of the PDF. This is done by modifying the XSLFO to add a new container block and adding a background-image.

You don't have to do the first step, but if the rest of this doesn't work it should help to eliminate the possibility that other changes you've made to the DITA OT are interfering — I've tested this with a default (unmodified) installation on XMetaL Author Enterprise 6.0.2.070.

1. Make sure you aren't going to lose any changes to the DITA OT that you want to keep, then do the following so we begin with a fresh copy of the DITA Open Toolkit.
 – Delete this folder%appdata%SoftQuadXMetaL Shared
 – Generate output from your DITA map. This will restore the folder structure we just deleted by deploying a copy of the DITA OT from C:Program FilesCommon FilesXMetaL Shared

You may wish to allow output to complete to make sure that it is successful and that everything is working properly as with an out of the box installation.
Of course, if you have been modifying the copy in Program Files then your modifications will be redeployed. So, if you really need to start with an unmodified copy of the DITA OT you will need to reinstall and then redeploy.

2. Locate a supported image type on your system (JPG, PNG, GIF, TIFF, SVG or PDF). For information on supported image types see http://www.renderx.com/reference.html#SupportedGraphicFormats

3. Place a copy of that image in this folder:
%appdata%SoftQuadXMetaL SharedDITA_OTdemoxmfoCustomizationcommonartwork

Note: RenderX supports the embedding of vector-type images (SVG and PDF). So, to keep your PDF file sizes small you may consider using PDF, and the image you have posted lends itself well to that as it can be constructed as a few shapes with appropriate fill colours. However, the DITA OT only copies JPG, GIF, PNG to the temp folder that is ultimately used by RenderX XEP to generate the PDF and so if you use PDF you may need to manually move it there. Alternatively, you may use an absolute path. You might try JPG to start with though, to make sure everything else is working, then look into PDF later (keeping the possible points of failure to a minimum is usually a good idea).

4. Open the following file in your favourite text or XSLT editor:
%appdata%SoftQuadXMetaL SharedDITA_OTdemoxmfoCustomizationfoxslxm_titlepage.xsl

Note: This is the deployed copy of the DITA OT. Once you get this working, and if you need to reuse this solution on multiple machines for all users at your location, you may wish to modify the “installed” copy of the DITA OT and then have users deploy it. If this is just for you then you can weigh the benefits to either method. See: http://forums.xmetal.com/index.php/topic,1008.0.html

5. Locate the first object in xm_titlepage.xsl. It should be and inside (after) the opening tag add the following:

[code] absolute-position=”absolute”
top=”-30mm”
left=”-30mm”
right=”-40mm”
bottom=”-40mm”
background-image=”CustomizationOpenTopiccommonartworkcover_page_background.jpg “
background-repeat=”no-repeat”>[/code]

The negative values for top and left “undo” margins set elsewhere so that they are effectively set to zero. For right and bottom the numbers can be larger than actually necessary. For some reason, setting them to -30mm was not quite big enough, but I don't want to bother tracking that down. Since the image is going to “bleed” off the edge anyway these can be bigger than necessary I think.

Here's another example using a PDF “image” (the file is the one I have included in the attached zip) and referenced using a full path. Adjust the path to point to your PDF file (test using the one I am attaching first, since it does work).
[code] absolute-position=”absolute”
top=”-30mm”
left=”-30mm”
right=”-40mm”
bottom=”-40mm”
background-image=”C:ArtWorkForXEPcover_page_background.pdf”
background-repeat=”no-repeat”>[/code]

6. Inside the same object and just inside (before) the closing tag add the following to close the we just added:

7. Save the file.

8. Generate output using the deliverable “XMetaL Enhanced PDF via RenderX XEP”.

This should produce a PDF with an additional container block on the title page and one copy of your image.
The image will have been copied here when you generate output (unless it was an SVG or PDF file):
/Customization/OpenTopic/common/artwork/cover_page_background.jpg

---

Things to check if this does not work for you:

1) Interference from other DITA OT changes you have made previously. In this case you might do my steps 1 and 2 (after backing up your changes).
2) Make sure the log.xml file does not contain any warnings or errors specific to the XSLT / XSL-FO changes that we have made and that output was successful. If output fails you are usually given the option to open this file. You can also open this file by selecting File > Open Output Log.
3) Make sure the image format is supported. RenderX XEP has specific requirements for image types. If you run into problems with one type (eg: JPG) try another such as GIF, or another image of the same type created by another application.
4) Make sure the image is in fact being copied to the location specified.
5) Check the topic.fo file that is generated to see that the path to the image is correct. By default this file is cleaned up after output is complete. To disable this cleanup enable the following setting:
Tools > Configure Output > Advanced (tab) > Other output parameter (textbox): cmd_synchro_mode  =  2
6) If you don't see your image in the PDF but you are sure everything is OK look for a “missing image” icon. That will tell you that the XSLT is working but that the image can't be found, so something is wrong with the path.
7) If you don't see your image in the PDF but otherwise everything seems OK, check to see that the image fits on the page. Images may not embed (or render) if they are too big to fit the width or height of their container block in the PDF. I believe this is not the case when the FO property “absolute-position” is used (as I have done here).

---

Attached in the zip:

• cover_page_background.pdf: A PDF “image” that contains an attempt to reproduce your JPG as a vector drawing (thereby reducing file size to about 2KB).
• test_topic.xml: A test DITA topic.
• test_topic.pdf: The PDF that results from generating output for the test topic together with the modifications above that use the PDF image as the cover.

Reply