Branding PDF Downloads - SuperWEB2

Users can download PDFs from Graph View and Map View. SuperWEB2 is supplied with a default template for the downloads, but you can replace this with your own version. You can also create separate PDF templates for graph and map downloads.

In order to change the template for PDF downloads, you must create a PDF form containing specific form fields. SuperWEB2 will populate the form fields with the map or graph at download time.

To create the PDF form, you need access to Adobe Acrobat. This is the full, paid, version of the Adobe Acrobat software, not the free Adobe Reader software (which only allows you to view PDFs, not create and edit them).

Create a PDF Template

1. The first step is to create a basic PDF to use as the template.
   
   This should include any static items you want to appear in the downloaded file, such as your company logo, branding, and copyright statements.
   
   You can use whatever tool you like to create the initial document, as long as it can export your document to PDF. For example:
   

   

2. When you have finished creating your initial template, export the document to PDF.
3. Open your PDF in Adobe Acrobat.

4. Choose the option to create a form (the exact option will depend on the version of Acrobat you are using):

   

   You may be prompted to confirm how to create the form.

   If prompted, choose to create a form From Existing Document:

   And choose to base the form on the Current Document:

   Then choose the option to Add New Field.

5. Add the following form fields to your document (the field names must match the ones shown here exactly):

   Field Name	Will be populated with...	Applies to...
   Map	The main content of the download. For graph downloads this field will be populated with the graph; for map downloads it will be populated with the map image.	Both map and graph downloads.
   Information	The database name (graph downloads). Details of what is being counted in the table (map downloads).	Both map and graph downloads.
   Map Title	The table name.	Map downloads only.
   Legend	The legend/key for the map.	Map downloads only.
   LegendTitle	The value of the Field drop-down list from Map View (i.e. it indicates what field is being visualised on the map).	Map downloads only.

6. Position the form fields where you want to items to appear on the page. You will typically want to make the Map field the biggest and most prominent, because this where the map or graph will be placed in the document.

   For example:
   

   

   

   It is possible to use a single template for both map and graph downloads. If you are planning to do this then your template must include all of the form fields (the ones that do not apply to graph downloads will simply be left blank).

   If you prefer, you can create two different templates. In this case, the template for map downloads must include all of the form fields; the graph template only needs to include the two fields that are used in graph downloads.

7. Use the options in Acrobat to set any field properties that you want to apply to your template, such as the font type, font size and text alignment, as well as border and background colours on the form elements (if any). These properties will be applied at download time when SuperWEB2 writes the map/graph contents to the template.

8. Save the file as <tomcat_home>\webapps\webapi\SWDownload.pdf

9. You can now test the template by logging in to SuperWEB2 and creating a table, then downloading a graph and map to PDF:

Using Separate Templates for Graphs and Maps

By default, both graph and map downloads use the same PDF template: <tomcat_home>\webapps\webapi\SWDownload.pdf

If you prefer you can create separate templates for each type of download. This allows you to create a download template for graphs without the three form fields that do not apply to this type of download.

To use two different templates:

1. Create your two different template PDF files and save them in <tomcat_home>\webapps\webapi\
   

   Your map template must include all five form fields listed in the table above, but your graph template only needs to include the Map and Information fields. For example:
   

   

2. Edit <tomcat_home>\webapps\webapi\WEB-INF\faces-config.xml in a text editor.
   
   

   Make a backup copy of this file before making any changes.

3. Locate the following section:

   XML

           <managed-property>
               <property-name>pdfTemplateURL</property-name>
               <value>http://localhost:8080/webapi/SWDownloadTemplate.pdf</value>
           </managed-property>

4. Change the property value to match the filename of your graph PDF template. You must specify the full URL for the PDF. For example:

   XML

            <managed-property>
               <property-name>pdfTemplateURL</property-name>
               <value>http://localhost:8080/webapi/SWDownloadTemplateGraph.pdf</value>
           </managed-property>

5. Save your changes to the file.
6. Edit <tomcat_home>\webapps\webapi\WEB-INF\web.xml in a text editor.
   
   

   Make a backup copy of this file before making any changes.

7. Locate the following section:

   XML

        <context-param>
           <description>
               MapView PDF Template Name 
            </description>
           <param-name>mapPdfTemplateName</param-name>
           <param-value>SWDownloadTemplate</param-value>
       </context-param>

8. Change the parameter value to the name of your map template, without the .pdf extension. For example:

   XML

         <context-param>
           <description>
               MapView PDF Template Name 
            </description>
           <param-name>mapPdfTemplateName</param-name>
           <param-value>SWDownloadTemplateMap</param-value>
       </context-param>

9. Save your changes to the file.
10. Restart Tomcat or the SuperWEB2 service.
11. Create a table and download a PDF of a graph and a map to verify that the two different templates are being applied.

Other PDF Configuration Settings

In addition to changing the template PDF, there are some other configuration settings you can adjust for PDF downloads:

Graph PDF Settings

The additional graph PDF settings are configured in <tomcat_home>\webapps\webapi\graphViewTab.jsp. The settings are defined in the following section:

<charting-wc:downloadChartPDF
    templatename="#{externalLinkBean.pdfTemplateURL}"
    messagekey="mapView.download.pdf"
    subject="test subject"
    author="test author"
    application="test application"
    keywords="test keywords"
    title="test title"
    fieldnames="Map,Information"
    fieldvalues="null,#{tableBean.tableDataModel.databaseDisplayName}"
    fieldvaluetypes="MAP,TEXT"
    imagescales="Scale to fit,null"
    chartimagesizex="1280"
    chartimagesizey="1024"/>

The settings you can change include:

Map PDF Settings

The additional map PDF settings are configured in <tomcat_home>\webapps\webapi\WEB-INF\web.xml. The settings are defined in the following section:

    <context-param>
        <description>
            MapView PDF Author Document Property - used to set the Document Properties for generated PDFs. 
         </description>
        <param-name>mapPdfDocumentPropertyAuthor</param-name>
        <param-value></param-value>
    </context-param>
    <context-param>
        <description>
            MapView PDF Keywords Document Property - used to set the Document Properties for generated PDFs. 
         </description>
        <param-name>mapPdfDocumentPropertyKeywords</param-name>
        <param-value></param-value>
    </context-param>
    <context-param>
        <description>
            MapView PDF Application Document Property - used to set the Document Properties for generated PDFs. 
         </description>
        <param-name>mapPdfDocumentPropertyApplication</param-name>
        <param-value></param-value>
    </context-param>

These settings define:

mapPdfDocumentPropertyAuthor

mapPdfDocumentPropertyKeywords

mapPdfDocumentPropertyApplication