Servigistics InService Customization > Customizing Printing > The Servigistics InService Book Print > Customizing Book Print
  
Customizing Book Print
The XML content rendered to XSL FO is styled using XSLT transform stylesheet assets associated to each data type (IE XML, GRAPHICS, and PARTSLIST). The base print stylesheet of each such data type is called defaultPrint.xsl.
There are two additional print stylesheets: One for the cover (CoverPage.xsl) in the InS_Data/Work/Applications/PrintServer/Work/Templates folder and defaultPresentationToc.xsl for the TOC, in the InS_Data/Work/Applications/PrintServer/Data/Ext/PrintStorage/Templates folder.
You can customize the PDF Book Print in several ways:
Through configuration, by changing print settings
Programmatically, via a BookPrint Delegate
By customizing print transform stylesheets
All stylesheets include a customization stylesheet named print-customizations.xsl to allow for arbitrary customizations of the styling using standard XSLT methods like adding higher priority template matches to take control during the transform process.
The Print Settings Configuration File
The print-settings.xml file is located in InS_SW/Config/System/Config/Core/Settings and lets you control several aspects of the book print via configuration.
The settings file contains:
An inclusion of sibling file custom-print-settings.xml for customization support.
Page geometry definitions (various page sizes, page orientation, margins, and the vertical space allotted to header and footer for each page).
Various default settings, default text, and default localized strings.
The sibling file custom-print-settings.xml is included during parsing of print-settings.xml to add custom settings (for custom code) and/or override default print settings. The format of the print settings file uses but a few conventions and is nearly free-form.
Settings with ID Attribute
Except for page geometry definitions, settings are not constrained to specific element names or markup hierarchy beyond having an id attribute: Elements associated to a setting must have an attribute named id. The attribute naming suggests uniqueness of the corresponding setting only. Consequently, in order to look-up settings, the print related stylesheets use an xsl:key defined to match any element with an id attribute:
The custom-print-settings.xml file is included prior to any default values via an entity reference:
When a setting is looked-up from the print settings file using its id value, the xsl:key will return all of the elements that match in document order – meaning that any custom element with same ID attribute value as a default setting will be returned first, as the custom settings appear before the ootb section.
Consequently, the stylesheets are written to select the first element returned by the key lookup, so that a customized setting will have precedence over the default value by appearing before a corresponding default value.
As only the element’s id value is used to look-up a setting, the XML hierarchy and element names of the settings can pretty much be freely modified; if a custom element is meant to replace a default setting, it should simply use the same id attribute value as used on the default setting that it overrides.
Page Layout Definitions
Each pagesizes/page element has attributes for corresponding layout properties. The selected page definition applies to all content rendered to PDF via XSL FO (cover, TOC, and all data types except PDF IEs). PDF IEs included for book printing are embedded at their existing, intrinsic page size.
The currently defined page sizes are A4 and US Letter, in Portrait and Landscape orientation. Each page has an attribute id (A4, A4L, US, and USL).
The default page size (applied for XML content being rendered for printing) is set via parent setting pagesizes attribute default whose value references a page element using the id value.
Note that the page element is required to have attributes related to the page geometry that the element defines (values for page size, margins, vertical space of header / footer) and to appear as a child of the setting with id value pagesizes. You can override the default page setting by only providing your own element with id attribute value pagesizes, and set its attribute value to the id value of a corresponding page element without respecting the default element hierarchy. However, as the intention is to extend the Book Preview dialog with a drop-down to let users dynamically choose a page size and orientation and to drive the drop-down logic from the current default markup of the print settings, any customization of the page geometry definitions must follow the same convention for the drop-down functionality to work properly.
Customizing Cover Header Contents
The cover page styling is performed by stylesheet InS_Data/Work/Applications/PrintServer/Work/Templates/CoverPage.xsl. The cover page contents are fully derived from the stylesheet and the parameters that it gets; the cover.xml file is merely a placeholder to satisfy the requirement that a stylesheet is applied on XML.
In the print-settings.xml file the default element <application id="application"> holds the string displayed in the upper right corner of the cover’s recto and verso pages:
To replace this string with a custom value, you simply add an element with same id value in the custom-print-settings.xml file:
As the custom element is selected first its definition trumps the default value:
The image to insert in the cover's header left corner is provided via XSLT parameter imageUrl. By default, the BL assigns it the value http://localhost.ptc.com:8080/PrintServer/Images/ptc-master-color.png. The corresponding image resides under InS_SW/SW/Applications/e3C.ear/PrintServer.war/Images alongside other default images used for print such as icons for part lists, media and such:
The image path passed via imageUrl is resolved dynamically via the BookPrint delegate and this Business Logic can be customized programmatically. If you replace the image in customization, you can set its height using the print settings ID cover-image-height. The unit must be one of cm, mm, in, pt, pc, px, or em. See https://www.w3.org/TR/2001/REC-xsl-20011015/xslspec.html#section-N8185-Definitions-of-Units-of-Measure.
The default template emits the cover header in named template CoverHeader. To summarize, this evaluates parameter imageUrl as source of image, scales the image height according to setting cover-image-height, and inserts the value of setting application in the header’s right corner:
Alternatively, if you customize the cover layout further, you can change the XSLT stylesheet processing itself through the customization stylesheet.
Finally, the URL value for the image can overridden using the XML catalog to map to another URI.
Localized Strings
The cover stylesheet expects a single string value to be inserted in the right corner of the header. A stylesheet may also reference an element which is expected to be localized. The cover and TOC use but three default localized strings: The TOC title, a boilerplate text for intentionally blank pages, and a localized timestamp for the PDF generation.
The convention is to have localized content in a parent element with id attribute whose children hold localizations, each with its corresponding language code in attribute xml:lang. Thus, a default localized string can be overridden in the same way as any other setting via its id attribute, but the customization must follow the convention of having the localizations as children elements:
IE XML and PARTLIST content use a similar convention in referenced XLIFFs and XML files holding localized strings, where the localized content resides in separate files. As the print settings hold but a few localizations, the corresponding strings are included directly in the print settings file.
Resolving Localized Content Using Extension Function
When resolving a localized string, the print stylesheets look-up the element via its id attribute value, and then select one of its children using an XSLT extension function. The select-lang() extension function returns the first child whose xml:lang value matches one of the parameters in the function, testing each parameter value in turn from left to right. The user’s set of language preferences (from the UI) are provided as a parameter to the print stylesheet where the language code(s) are assigned to variables named lang1 through lang6.
For the custom element with id attribute value thispageintentionallyleftblank as defined in image above, when selecting German as preferred language in the UI drop-down, the stylesheet will return the content of child with xml:lang value de:
Printing Date and Time
The localized printing date timestamp is emitted using XSLT extension function formattedDate() which is based on the ICU library (http://site.icu-project.org/). As the print server can be executing in another location than from where it is being physically accessed, or the server might not have been configured to the same time zone as the user’s location, the displayed printing date and time is chosen to be the Coordinated Universal Time standard (UTC) using extension function utc-timestamp().
The formattedDate() extension function takes up to three parameters:
1. A date timestamp string – This can be provided in a variety of timestamp formats but you can use a date in YYYY-MM-DD numerical format such as “2018-02-26”.
2. A format specification string – this value is used “as is”. This parameter specifies in a language-independent manner the desired format for the output according to Unicode Common Locale Data Repository conventions. There are many options, for example, see the Date Field Symbol Table under http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Field-Symbol-Table or the CLDR Date Field SymbolTable at http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table. The format specification string is used to list what date / time components to include in the output, such as the name of the month, date, weekday, year.
Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not enclosed within single quotes.
The single quote is used to 'escape' letters. Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote.
If this parameter is missing the function will apply a default value.
3. A locale that specifies the country and language code (e.g. “ru” for Russian or “fr” for French, “pt-BR” for Brazilian Portuguese). If this parameter is missing the function will apply a default value.