Display options

The way in which PDFs are displayed in standard-compliant reader programs can be influenced in webPDF with parameter options in web service Toolbox. Most of the available display options are associated with a specific display scenario, and are accordingly extremely context-dependent.

By using effects and, above all, automating page changes, PDFs can be used to implement full screen slideshows and presentations.

You can use the settings for modifying the initial page, the page layout, the initial view, and the magnification factor in order to ensure that the document to be opened with the ideal display settings. This will not only enable the user to easily navigate through the document, but will enable you to provide the user with the contents the way you want to present them as well.

You can also use page backgrounds and headers and footers to add more information to the document.

You can scale the page boxes to optimize the page size and the various areas for display and printing. In addition, you can also remove these page boxes.

Start page

The "initial page" parameter opens the document on the page you specify. This can come in handy of you want to steer the user’s attention towards specific contents that are not found on the document’s first page. An example of this would be if you wanted to have the document open on a table of contents with destinations that will enable the user to easily navigate through the document from the get-go.

Page layout

The page layout parameter applies exclusively to the standard view for documents and affects the number, order, and magnification factor of the pages shown simultaneously in a reader program .

• singlePage
  Shows individual pages isolated from their context. If you scroll beyond a page, the view will jump to the next page directly.

• singlePageContinous
  Shows individual pages as a continuous vertical column so that the user will be able to scroll through the pages without abrupt jumps.

• twoPages
  Shows two consecutive pages next to each other. The two pages will be shown isolated from their context. If you scroll beyond the pages, the view will jump to the next couple of pages directly.

• twoPagesContinous
  Shows two consecutive pages next to each other. The pages will be shown as a continuous vertical column so that the user will be able to scroll through page pairs without abrupt jumps.

Initial view

The "initial view" parameter is used to configure how the document should be presented immediately after being opened and which tab should be open initially.

• none
  The document will not be shown in a special view, and no special tab will be open initially.

• outlines
  Opens the document with the “Bookmarks” tab open. This assumes that the document has proper bookmarks that will enable the user to navigate effectively throughout the document.

• thumbnails
  Opens the document with the “Page thumbnails” tab open. This will enable the user to navigate using a continuous list of visual page images.

• fullscreen
  Opens the document directly in full screen mode. This option makes sense for presentations in particular.

Magnification

The "magnification" parameter applies exclusively to the standard view for documents, where it sets the initial magnification factor for the view.

• none
  No special initial magnification factor will be used for the document. The reader program will simply use the default setting.

• fitWidth
  Selects a magnification factor that will resize the page so that the page’s entire width will be shown.

• fitPage
  Selects a magnification factor that will resize the page so that the entire page will be shown.

• fitHeight
  Selects a magnification factor that will resize the page so that the page’s entire height will be shown.

• fitVisible
  Selects a magnification factor that will resize the page so as to ensure that the entire width of the actual page content will be shown.

• fitActual
  The page will be shown in its original size (100% zoom factor).

• zoom
  Defines a specific magnification factor for the document.

Page transition effects

The "transition effect" parameter applies only to the full screen view and can be used to highlight scrolling from one page to the next by using transition effects. In addition, some of these transition effects can be affected by the corresponding effect direction. Please note that all transition effects always refer to a specific page range or even to a single individual page, meaning you are free to vary the effects in your document or highlight specific pages with effects in a targeted manner. You can also automate page transitions in order to create slideshows with PDF documents, as well as full screen presentations that need a single click to start.

• none
  The page will change directly without any special effects. The transition direction will not affect this effect

• blinds
  Cuts the page into several strips and collapses them individually, revealing the next page. The transition direction will not affect this effect

• box
  Expands the next page as a rectangle starting from the centre of the display area until it replaces the previously shown page. The transition direction will not affect this effect

• cover
  Makes the next page slide in from the side until it covers the current page. The transition direction will affect this effect.

• dissolve
  Makes the current page fade out in squares, revealing the next page. The transition direction will not affect this effect

• fade
  Makes the current page fade gradually so that the next one comes in accordingly. The transition direction will not affect this effect

• fly
  Makes the next page “fly in” from the side until it covers the current page. The transition direction will affect this effect. The "fly" effect has additional configuration options.

• glitter
  Dissolves the current page in squares and, at the same time, shows the next page along a line in the background. The transition direction will affect this effect.

• push
  Makes the next page slide in from the side so that it “pushes” the current page out. The transition direction will affect this effect.

• split
  Splits the current page and pulls the two halves away from each other until they are no longer visible, revealing the next page. The transition direction will not affect this effect

• uncover
  Makes the current page slide out, revealing the next page, which is underneath. The transition direction will affect this effect.

• wipe
  Smoothly hides the current page as a moving line moves across the screen. The transition direction will affect this effect.

Page transition direction

The "transition direction" parameter affects the direction of the transition animation (provided that it can be applied to the animation).

• none
  Removes the transition direction if possible.

• leftToRight
  Movement from left to right.

• bottomToTop
  Movement from bottom to top.

• rightToLeft
  Movement from right to left.

• topToBottom
  Movement from top to bottom.

• topLeftToBottomRight
  Diagonal movement from top left to bottom right.

The fly effect

The "fly" effect has additional parameters available that affect how it is displayed. These parameters will not apply to any other effects.

• flyScale
  Affects the starting size of the page that “flies in.” Starting from this scaling value, the page will be gradually and smoothly scaled throughout the animation until it reaches the actual page size being displayed, giving the impression, for example, of falling onto the display area from above.

• flyAreaOpaque
  If this parameter is enabled, the background for the page that “flies in” will be transparent. This means that only the page’s contents (texts, images) will “fly in,” giving the impression of directly replacing the contents of the previous page.

Automatic page change

Automatic page changes can be used in order to implement automatic slideshows in full screen mode that will scroll through page ranges or through the entire document without requiring any interaction with the user. In addition, you can use transition effects to make these automatic page transitions more interesting.

• autoScroll
  If this parameter is enabled, automatic page changes will be enabled for the specified page range. After a specific time, the document will move to the next page automatically if the user has not already done this manually.

• autoScrollTime
  This parameter specifies the time after which the document will switch to the next page automatically. This parameter only has an effect when used together with the "autoScroll" Boolean flag.

Backgrounds

Backgrounds are shown behind all other page contents. As of this writing, it is not possible to set more than one background per document. Moreover, pages on which this background is shown must follow a fixed interval for directly consecutive pages. Before you can add a background to a document, you will first need to remove any existing backgrounds. You can do this with the "remove" operation or by using the "replaceExisting" parameter.

• Image background
  The content for this type of background consists of an image that will be shown in the defined area.

• Solid colour background
  The content for this type of background consists of a colour that will fill out the defined area.

Solid colour backgrounds fill the whole page by default, while background images will keep their original dimensions. However, you can use an additional scaling factor to modify the background’s dimensions. Rotation can cause scaled backgrounds to project beyond the page margin. In order to prevent this, you can use the "pageRelative" parameter, which will cause the scaling factor to be interpreted as a percentage of the page dimensions rather than as an absolute value. If you use relative scaling, the rotated background will be scaled within the resulting page area regardless of its original dimensions.

Headers and Footers

Headers and footers are shown at the top and bottom of the page and can be used to show additional contextual information on pages, including the date when the document was created and the page number. As of this writing, it is not possible to set more than one header and footer configuration per document. Moreover, pages on which the header and footer are shown must follow a fixed interval for directly consecutive pages. Before you can add headers and footers to a document, you will need to remove any existing headers and footers first. You can do this with the "remove" operation or by using the "replaceExisting" parameter.

You can define a header and footer that consist of three different fixed positions (left page margin, centre of page, right page margin) where content can be shown.

You can also modify the position of the header and footer contents by specifying a box that can be used with offsets from the various page margins.

The header and footer can contain simple and static text contents on every page (the document’s name / title / author, for example), but can also integrate dynamic context-sensitive formats. Within this context, the available dynamic formats consist of the date format, the page number format, and the Bates number format.

Dynamic header and footer contents

In addition to static text contents, headers and footers can also contain the dynamic contents that are described below. The content of these elements will depend either on the document’s properties (data of last modification) or on the properties of the relevant page (page number). The syntax for dynamic content requires for it to be placed between double angle brackets: <<Format>>. You can combine static and dynamic content together: First format- <<Format1>> -additional content- <<Format2>>. Dynamic content needs to be specified with a specific syntax, i.e., there is a limited set of options for the content between the angle brackets, and this content follows the rules below:

• Date format
  A date consists of two or three date elements that are separated by a separator. You can choose any separator of your choice, but the actual date elements must be as follows: y - year, m - month, d - day
  The number of identical consecutive date elements determines what the number of digits will be. More specifically, the year number is allowed to have 2 or 4 digits, while the day and month number is allowed to have 1 or 2 digits. You can place these elements in any order you want. This means that the following would be two valid date format examples: <<yyyy-dd-m>>, <<mm.yy>>. The date elements will then be replaced on the page as per the “date last modified” in the header and footer.

• Page number format
  A page number can either be by itself or together with the total number of pages. The page number format consists of an optional prefix of your choice, the page number itself [i], an optional separator expression of your choice, and, optionally, the total number of pages [n]. The placeholder for the page number will be replaced with the number of the corresponding page, while the total number of pages will be replaced with the number of pages in the document. This means that the following would be valid page number format examples: <<Page i of n>>, <<i>>, <<i/n>>, <<i of n>>. The page number format elements will be replaced on the page itself in conformity with the page’s position in the document. You can use the "firstPageNumber" parameter to specify a page number starting from which the pages should be counted. This parameter will affect both [i] and [n] accordingly.

• Bates number
  A Bates number will link a document page to a specific identification number following a fixed syntax. The Bates number can be a “natural” page number that is specific to the individual document’s context, but can also be used for numbering across documents so as to place the corresponding page in a larger context. The Bates number will number pages continuously starting from a fixed starting number. This type of number is made up of a prefix of your choice, a number with a fixed number of digits (with leading zeros as necessary), and a suffix of your choice. The format is specified with four values separated by hash characters (#), with the first value specifying the number of digits, the second the starting number for the continuous numbering, the third the content of the prefix, and the fourth the context of the suffix. If you do not need a suffix, you can omit the fourth value. If you do not need a prefix, you can leave the third value blank. This means that the following would be valid Bates number format examples: <<#6#2#prefix#suffix>>, <<#8#256## suffix but no prefix>>, <<#1#0#prefix but no suffix>>. The Bates numbers for two consecutive pages could accordingly look as follows: "No. 000245 SVD", "No. 000246 SVD"

caution

The formats described here provide more freedom than most PDF editors do – for example, you can use any order of your choice for the date format. This means that if the header and footer are edited in an external PDF editor, there may be deviations. The displayed headers and footers themselves are not affected by this.

tip

The "firstPageNumber" parameter can be used in combination with the page interval in order, for example, to start counting pages from the second page and to also only count pages starting from the second page in the total number of pages. This makes it possible, for instance, to take into account a cover sheet in the page number and to start counting from 1 only after the cover sheet.

Setting page boxes

The contents in a PDF page are placed inside various nested boxes, and are normally positioned relative to these boxes. In addition, the boxes determine which page contents will be visible in reader programs and which of these elements will be printable. This means that an element shown in a reader program will not necessarily be printed out and vice versa. Finally, the boxes are used for spatial grouping and for differentiating between content importance.

The following rules apply to the boxes:

The media box defines the actual physical size of the medium being printed, and accordingly should encompass all contents and boxes. It is not absolutely necessary to adjust or use all boxes. In fact, the media box is the only box that must be used without fail, and it should always be initialized in valid documents already independently of webPDF. If you do not need or want specific boxes, you can simply adjust them to match the other boxes that enclose them (i.e., use the corresponding position and dimensions). Boxes that are not entered into the PDF structure (because, for example, they have been removed) can still be retrieved, since the art, trim, and bleed boxes will match the crop box if they have not been otherwise configured. If you do not configure the crop box, all the boxes (including the crop box) will instead match the media box.

In the case of newly created documents that have not been configured further, it is very likely that all existing boxes will match the media box (or that only the media box is configured). In most cases, and particularly for documents that will only be used digitally, this is more than enough. However, if you want high-quality printed results, it often makes more sense to use the boxes as follows in order to be able to configure the printout in a more detailed manner:

• Media box
  The media box defines the physical dimensions of the untrimmed, printed medium. It is the box that encompasses everything, meaning that all contents must at least be positioned within its limits, as they will otherwise be cropped.

• Crop box The crop box is the document area that is actually visible. All contents outside of the crop box will fall within the dimensions of the printed medium, but will normally not be visible in reader programs. Contents located between the crop box and media box will not be removed or cropped, but hidden instead.

• Bleed box The bleed box defines the absolute content limits, including the trim box. Normally, the only elements between the bleed box and media box will be elements that are needed but that are not intended to be in the printed end product, e.g., printer marks and notes for internal use. Contents should project into the area between the trim box and the bleed box only if it is necessary to ensure that printed elements will reach all the way to the edge of the paper (bleed-off images). The trim area between the bleed box and the trim box is a tolerance area when trimming the printed result, and within which the sheet trim should be located.

• Trim box The trim box defines the desired, trimmed end size for the printed product and positions the contents of the page in the area that will actually be printed and found on the end product.

• Art box The art box is used to indicate all the content objects on the page that are actually shown, making it possible to exclude unfilled or irrelevant page areas for fully automated, faster processing in the prepress phase. This means that, in contrast to the trim box, the art box does not define the printable area, but rather the page area that contains actually relevant elements. The art box is frequently left out or is merged directly with the trim box.

caution

The specifications above mean that the boxes’ positions and dimensions are subject to certain limits and in some cases will depend heavily on the boxes that surround them. Size changes to boxes must not result in a box projecting beyond the borders of the media box. In other words, it is necessary to ensure that whenever the media box is resized (or when a change is made to the boxes in it), none of the boxes in it exceed its dimensions.

caution

While it is possible to make the art or trim box be bigger than the bleed box, doing so does not really make sense.

Removing page boxes; default page box values

Due to various reasons, it can make sense to remove a box from a page. webPDF makes it possible to do this for a specific box. This will not affect the boxes surrounded by the removed box negatively, since the larger boxes will take over the function of the removed box. If, for instance, you remove the bleed box, the art and trim box will instead use the crop box as a reference. If you remove the crop box instead, the boxes it surrounded will use the media box as a reference instead.
The media box is the only box that must always be defined for a PDF document page and that cannot be removed.

caution

You can edit boxes and remove other boxes in a single processing step. However, keep in mind that boxes will be removed before box scaling if both operations are carried out in the same step.

tip

In a minimal layout, this means that a page will only have a defined media box and that all the other boxes will automatically use the media box’s dimensions as well.