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 either use the same PDF template for both graph and map downloads, or use a different template for each.

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 information from the map or graph at download time.

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

Create a PDF Template

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, you might create the initial document in Microsoft Word:
When you have finished creating your initial template, export the document to PDF.
Open your PDF in Adobe Acrobat.
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.

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 graph or map.	Both map and graph downloads.
Map Title	The table name.	Both map and graph downloads.
Information	Details of what is being counted in the table.	Both map and graph downloads.
Database Label	The name of the database.	Both map and graph downloads.
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.

By default, SuperWEB2 is supplied with separate templates for map and graph downloads. This allows for the best use of space in the template, as the graph download template does not need to include the Legend and LegendTitle fields.

If you want to continue to use different templates then you will need to create two copies of your PDF, one for graph downloads and one for maps.

If you prefer, you can use a single template for both. If you want to do this the template must include all the form fields listed in the table. The ones that do not apply to graph downloads will simply be left blank when users download a graph.

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 is where the map or graph will be placed in the document.

For example:
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.

Make sure that the font type used in your form fields supports the character set of your databases. The sample PDF templates supplied with SuperWEB2 use one of the default Adobe Reader fonts (Helvetica), which supports only Latin characters. If you are using other character sets in your deployment then you will need to replace the supplied PDF templates with your own versions, and choose a suitable font to use in your template.

If this is the case, you may also need to configure SuperWEB2 to embed your font(s) in the PDF. When fonts are not embedded, PDFs only display correctly if the user opening the PDF has the specific font installed on their computer. See the section on embedding fonts below for more information.

Make sure the fields are big enough to accommodate the text (such as the table name and details of what is being counted) that is likely to be generated from your tables. If the text strings written to the template by SuperWEB2 are longer than the available space in the field then they will automatically be truncated.

Some strategies you can use to increase the number of characters that can be written to the form fields include increasing the size of the field in the PDF template, reducing the font size of the form field, and enabling the multi-line option in the form field properties to allow the text to wrap onto multiple lines (this option is not selected by default; to enable it, right-click the field in Acrobat and select Properties > Options > Multi-line).

It may not be possible to create a template with fields that are big enough to incorporate the text for every possible table that your users might create (for example if they create very complex tables with extremely long titles). You may need to use some trial and error to settle on a size of form field and font size that provides a good compromise that is flexible enough to support your users while still making good use of the available space.
On your graph template, right-click the Map field and select Properties, then the Position tab.
Make a note of the Width and Height of the Map field in inches. You need these values to tell SuperWEB2 how big to generate the graph image that will be placed in the PDF.
Save your graph template as <tomcat_home>\webapps\webapi\SWDownloadGraph.pdf and save your map template as <tomcat_home>\webapps\webapi\SWDownloadMap.pdf

If you are using a single template for both graphs and maps then you can give it whatever filename you like, as long as you save it to the <tomcat_home>\webapps\webapi\ directory. In a subsequent step you will change the SuperWEB2 configuration so that it knows where to find your template file.
Open <tomcat_home>\webapps\webapi\scripts\sw2-charts\sw2-chart-export-options.js in a text editor.
Edit the values for chartimgsizex and chartimgsizey so that they match the width and height (in inches) of the Map field in your graph template that you obtained from Acrobat. For example:
CODE
```
    "pdf": {
        "chartimgsizex": 11.17,
        "chartimgsizey": 5.35,
        "dpi": 72,
```
You may also wish to adjust the dpi value. This controls the dots per inch used to render the graph image when creating the PDF. The default is 72dpi, which is standard print resolution.
Save your changes.
You can now test the template by logging in to SuperWEB2 and creating a table, then downloading a graph and map to PDF.

Using a Single Template for both Graphs and Maps

By default, graph and map downloads have separate PDF templates: <tomcat_home>\webapps\webapi\SWDownloadGraph.pdf and <tomcat_home>\webapps\webapi\SWDownloadMap.pdf

This allows for the best use of space on the page, as the graph template can omit the fields that do not apply to graphs.

If you prefer, you can create a single template and use it for both types of download.

To use the same template:

Create your single template PDF file and save it to <tomcat_home>\webapps\webapi\

It must include all the of the form fields listed in the table above.
Edit <tomcat_home>\webapps\webapi\WEB-INF\classes\configuration.properties in a text editor.

Make a backup copy of this file before making any changes.
Locate the following section:
XML
```
graph.graphPdfTemplateName=
```
This sets the name of the PDF template used for graph downloads.
Change the property value to match the filename of your single PDF template (without the .pdf extension). For example:
XML
```
graph.graphPdfTemplateName=SWDownloadTemplate
```
Locate the following section:
XML
```
map.mapPdfTemplateName=
```
This sets the name of the PDF template used for map downloads.
Change the parameter value to match the filename of your single PDF template (without the .pdf extension). For example:
XML
```
map.mapPdfTemplateName=SWDownloadTemplate
```
Save your changes to the file.
If you have not already done so, in Acrobat obtain the width and height of the Map field on your template (see above for details). Use these values to update chartimgsizex and chartimgsizey in <tomcat_home>\webapps\webapi\scripts\sw2-charts\sw2-chart-export-options.js
Restart Tomcat or the SuperWEB2 service.
Create a table and download a PDF of a graph and a map to verify that the single template is 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.

Embedded Fonts

Depending on your PDF template, you may need to configure SuperWEB2 to embed fonts in PDF downloads.

The Adobe Reader application has a set of default fonts (known as the Adobe Base 14 fonts). These fonts are always available and do not need to be embedded. However, if your document uses other fonts then the PDF will only display correctly if users viewing the PDF have those fonts installed on their computers.

To ensure that your downloaded PDFs always display correctly, regardless of what fonts a user has installed, you can configure SuperWEB2 to embed the fonts in the PDF.

Open <tomcat_home>\webapps\webapi\WEB-INF\classes\configuration.properties in a text editor.
Locate the following property:
CODE
```
externalLink.pdfTemplateFonts=
```
By default this is set to no value, which means that SuperWEB2 will not embed any fonts in the PDF.
For each font you want to embed, add the full path to the font file on the machine running SuperWEB2. If you are specifying multiple fonts, separate them with commas. You must use forward slashes in the path. For example:
CODE
```
externalLink.pdfTemplateFonts=C:/Windows/Fonts/ARIALUNI.TTF,C:/Windows/Fonts/mingliu.ttc
```
To obtain the full path to a font installed on your computer, go to Control Panel > Appearance and Personalisation > Fonts, then right-click the font and select Properties:
Save your changes, and then restart Tomcat or the SuperWEB2 service to apply the change.

Before deciding to embed fonts in your PDFs, check the end user licence agreement of the font to confirm that it allows you to embed the font in a PDF.

Graph PDF Settings

The additional graph PDF settings are configured in <tomcat_home>\webapps\webapi\scripts\sw2-charts\sw2-chart-export-options.js.

See sw2-chart-export-options.js for full details.

Map PDF Settings

The additional map PDF settings are configured in <tomcat_home>\webapps\webapi\WEB-INF\classes\configuration.properties. You can change the following settings:

Parameter	Defines
map.mapPdfDocumentPropertyAuthor	The Author Document Property in the generated PDF.
map.mapPdfDocumentPropertyKeywords	The Keywords in the Document Properties in the generated PDF.
map.mapPdfDocumentPropertyApplication	The Application Document Property in the generated PDF.