Document Properties
Kbid2K3711
Last Modified04-Feb-2020
Added to KB20-Dec-2012
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - PDF Creation

1 Introduction

As the PDF format becomes more and more interesting for shop managers, this feature is now available with the IS7 standard product solution.
One of the main targets of the integration was to implement a solution that provides a general PDF generation from any HTML/XHTML source and especially to support the rendering of CMS pagelet entry points.

2 Glossary

PDF

Portable Document Format

Flying Saucer

3rd-party library that provides PDF rendering with XHTML as input

3 PDF Generation

3.1 Related Cartridges

Cartridge

Description

bc_pdf

for basic PDF render interfaces and exception class

ac_pdf_flyingsaucer

to provide specific implementation of an xhtml2pdf renderer as a managed service, contains 3rd-party html2pdf lib

sld_pdf

to provide a new interaction processor for generating PDF output

3.2 PDF API

3.2.1 Pipeline Layer

  • New page entry point interaction processor called PageEntryPoint2PDFInteractionProcessor
    This interaction processor creates a PDF stream from a given pagelet entry point and embeds it into a response stream.
    If a pipeline with that interaction processor is called, the user will be able to save or view directly the rendering result in PDF format. (The standard save file dialog of the browser/os will appear)
    • Parameters

      PageletEntryPointID

      system entrypoint to set that should be rendered and used for PDF generation

      Dictionary

      dictionary to set that should be used by the system page rendering process to access required data

      DefaultFileName

      the default file name which is provided to the front end user that receives the result of the rendering

3.2.2 Java API

For generating the PDF stream data a new managed service called "XHTML2PDFFlyingSaucerRenderer" is used.
This service adapter implements the following interface:
com.intershop.component.pdf.capi.PDFRenderer

For more information on managed services refer to the corresponding cookbook .

Since the creation of the PDF simply uses the first PDF renderer service that is available, it is necessary to remove the existing standard service if a custom service should be used with the existing interaction node for PDF creation.

PDFRenderer
/**
 * A common interface for pdf renderer that transform a given input into pdf
 * stream data.
 *
 */
public interface PDFRenderer
{
    /**
     * This method transforms content that was given as input stream into a pdf
     * stream. The system supports currently only html as input.
     *
     * @param contentStream input stream with content
     * @return
     * @throws PDFRenderException
     */
    OutputStream createPDF(final InputStream contentStream) throws PDFRenderException;

    /**
     * This method transforms content that was given as a string into a pdf
     * stream. The system supports currently only html as input.
     *
     * @param content
     * @return
     * @throws PDFRenderException
     */
    OutputStream createPDF(final String content) throws PDFRenderException;

}
PDFRendererConfig
/**
 * A common interface for configuration tasks of pdf renderer.
 *
 * @author Frank E. Hofmann
 *
 */
public interface PDFRendererConfig
{
    /**
     * Add a specific font to the pdf render config.
     *
     * @param source
     * @param encoding
     * @param family
     * @param bold
     * @param italic
     * @param embedded
     */
    void addFont(final String source, final String encoding, final String family, final boolean bold,
                    final boolean italic, final boolean embedded);

    /**
     * Add a given font directory to the pdf render config.
     *
     * @param fontDirectory
     * @param embedded
     */
    void addFontDirectory(final String fontDirectory, final boolean embedded);

    /**
     * Set the encryption of the generated pdf.
     *
     * @param userPassword
     * @param ownerPassword
     * @param allowedPrivileges
     * @param encryptionType
     */
    void setEncryption(final byte[] userPassword, final byte[] ownerPassword, final int allowedPrivileges,
                    final int encryptionType);

    /**
     * Set the pdf version number to be used for the created pdf.
     *
     * @param version
     */
    void setVersion(final String version);
}

Cookbook_PDF_Generation_Cartridges

3.3 Rendering Issues

3.3.1 Remote Includes

Since the common Intershop template rendering process uses constructs like waInclude, there is a need to change the system to avoid such non-HTML-conform constructs.
It is necessary to create a complete HTML website without any web adapter-related tags because the system is not allowed to create a second request within the current one to resolve such statements.
This will be avoided by using only CMS components and templates that abdicate such remote includes.

3.3.2 Resource Loading

A further task is to avoid new HTTP calls by resource loading of the website (ex. all media resources, image includes, CSS).
The solution to this problem is to replace the HTTP URLs by resource URLs that make use of the file protocol instead.

This can be done by creating a callback class which extends the ITextUserAgent.

PDFUserAgentCallback.java
public class PDFUserAgentCallback extends ITextUserAgent
{
    @Override
    public String resolveURI(String uri)
    {
        // set Base URL if needed
    }

    @Override
    protected InputStream resolveAndOpenStream(String uri)
    {
        //transform uri into desired uri format (file protocol)
    }
 }


...
  //using the callback for resource resolving
    ITextRenderer renderer = new ITextRenderer();

    PDFUserAgentCallback uac = new PDFUserAgentCallback(renderer.getOutputDevice());
    uac.setSharedContext(renderer.getSharedContext());
    enderer.getSharedContext().setUserAgentCallback(uac);

4 Fonts

4.1 New Fonts

New fonts can simply be copied into the <IS_SHARE>\system\fontsdirectory so that the PDF service will load them from that location.
It is also possible to embed those fonts into the generated PDF. But always keep in mind that there must be a license for that.
The PDF service embeds font of the fonts directory if the option "embed fonts" of the managed PDF service is selected in the back office.

4.2 Support of Chinese Fonts

The current version of the Intershop product is not delivered with Chinese fonts. But there are several fonts available and the integration into the system is pretty simple (as mentioned above), see https://wiki.archlinux.org/index.php/Fonts#Font_packages .

5 Example: Cart as PDF

5.1 PDF API - Pipeline Layer

  • New view pipeline ViewCartPDF
    • New start node Cart.pdf
      • Flow

        Call Prefix

         

        call ProcessCart-GetCurrentCart

        to retrieve basket

        check
        if CurrentCart:ProductLineItemsCount > 0

        if not call ViewPage-Start

        GetPageletEntryPointByID

        to get system entrypoint

        KeyMapper

        to set DefaultFileName from PageletEntryPoint:ConfigurationParametersAsMap:DefaultFileName:Value

        KeyMapper

        Dictionary=CurrentRequest:PipelineDictionary
        PageletEntryPointID=PageletEntryPoint:ConfigurationParametersAsMap:DefaultFileName:Value, CartReadonly=true
        CartReadonly is used inside the ISML templates to choose different behavior on a PDF rendering

        Interaction Node

        processor: PageEntryPoint2PDFInteractionProcessor that creates the PDF

5.2 PDF Template

The template should be designed using the CMS and Pageletentrypoint.
The shopping cart PDF template must be implemented by the CMS as a page variation so that a shop manager/content manager is able to edit and to customize the Shopping Cart Email template.
This PDF template must have the same localization settings like the shop does have so that the customer (sender) will send the email in the same language the shop has.

It contains 4 sections:

  • header with logo and name
  • headline + info text
  • shopping cart snapshot (items and costs summary)
  • footer with disclaimer and general information

The following settings are available at the system page:

configuration parameter

type

default value

comment

DefaultFileName

java.lang.String

Shopping_Cart_PrimeTechSpecials.pdf

text-parameter at the system page

avoid webadapter commands

All used templates and CMS components have to match the criteria mentioned under topic "Rendering Issues"; otherwise, the system can run into a request handler error!

5.3 Settings

The following application-related shopping cart & checkout settings are available in the Shopping Cart tab on all applications with B2C WebShop as application type.

name

type

default

comment

Save Cart as PDF

boolean

enabled

pdf button in storefront is only available if this is checked; note that the pdf service must be available too

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets