webPDF 8: New Features of the Webservice Toolbox Operation Outline

Minimum Technical Requirements​

  • Java version: 8
  • webPDF version: 8
  • wsclient version: 2

Part 1: Editing the Outline with the webPDF wsclient Library​

In this article, we use an example, the Outline operation, to show how you can use operations of the webPDF Toolbox Webservice with the help of the wsclient library.

Important Note​

The following code example is based on the webPDF wsclient library. To understand and apply the example correctly, you should first read the relevant introductory blog post.

Creating a REST or SOAP Session​

To call the webservice in the way we present here, it is assumed that you have already created a REST or SOAP session and can therefore create either a ToolboxWebService object for a SOAP session by calling WebserviceFactory:

ToolboxWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

Or a ToolboxRestWebService object for a REST session:

ToolboxRestWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

You should also have passed either a RestDocument or a SoapDocument object to this WebService object using the setDocument() method.

How Do You Get Write Access to a Document?​

To get write access to a document, you must pass the current open and/or permission password of the document to the webservice call. You can do this directly on the created toolboxWebService object:

toolboxWebService.getPassword().setOpen("password");
toolboxWebService.getPassword().setPermission("password");

If the document is not password-protected, you can skip this step.

The Toolbox Webservice​

The Toolbox Webservice is an endpoint of your webPDF server that combines a range of operations for directly manipulating a PDF document. Here we focus specifically on the Outline operation, that is, creating and editing outlines, as part of the new features introduced in webPDF 8.0.

The Outline operation allows you to modify the outline of your PDF document.

You add an Outline operation to your WebService object as follows:

OutlineType outline = new OutlineType();
toolboxWebService.getOperation().add(outline);

The following parameters can be set on the outline object.

The add Object​

To create an outline for your document, add an OutlineType.Add object to the Outline object.

OutlineType.Add add = new OutlineType.Add();
outline.setAdd(add);

The following elements can be added to the Add object.

The item Object​

Each Item object represents a node in the document outline. You can add any number of these objects to the Add object and thus create a tree structure of any complexity.

ItemType firstPage = new ItemType();
add.getAdd().getItem().add(firstPage);

The following parameters can be set on the ItemType object.

path (default value: "")​

Defines the slash-separated path where the element should be added to the outline structure, starting with an initial slash. The paths of the elements can build on each other in any way, allowing you to create the tree structure of the outline.

firstPage.setPath("/root");

itemName (default value: "")​

The name of the new element in the outline structure.

firstPage.setItemName("page1");

pathPosition (default value: "inplace")​

Positions the new element relative to the path selected via path:

  • BEFORE = The element is positioned on the same level and before the element selected via path.
  • INPLACE = The element selected via path is used as the parent element of the new element.
  • AFTER = The element is positioned on the same level and after the element selected via path.
firstPage.setPathPosition(AddPositionType.INPLACE);

isOpen (default value: "false")​

If this value is set to true, the node is displayed fully expanded when the document is opened.

firstPage.setIsOpen(true);

bold (default value: "false")​

If this value is set to true, the name of the node is displayed with a heavier font weight.

firstPage.setBold(true);

italic (default value: "false")​

If this value is set to true, the name of the node is displayed in italics.

firstPage.setItalic(true);

color (default value: "#000000")​

Defines the font color used to display the node name.

firstPage.setColor("#FF0000");

ActionType Objects​

Any number of ActionType objects can be added to an Item object. Each of these ActionType objects represents an action that should be triggered when the element in the outline is clicked. If several of these actions are defined, they are executed sequentially in the document.

The following ActionTypes are available.

goTo ActionType​

The GoTo ActionType selects elements of the document as jump targets. By specifying corresponding sub-elements, you can, for example, choose pages or markers as destinations.

GoToDestinationActionType goTo = new GoToDestinationActionType();
firstPage.getActions().add(goTo);

The following jump targets can be selected for a GoTo action.

zoomPage Destination​

Jumps to a selected page and sets the zoom level of that page view.

ZoomDestinationType zoomDestination = new ZoomDestinationType();
goTo.setDestination(zoomDestination);

The following parameters can be set for a zoomDestination.

page (default value: "1")​

Defines the page to jump to.

zoomDestination.setPage(1);

leftOffset (default value: "0")​

Defines the distance between the view and the left page margin.

zoomDestination.setLeftOffset(15);

topOffset (default value: "0")​

Defines the distance between the view and the top page margin.

zoomDestination.setTopOffset(10);

metrics (default value: "px")​

Defines the measurement unit in which the offsets are specified. Possible values:

  • MM = Millimeters
  • PX = Pixels
zoomDestination.setMetrics(MetricsType.MM);

zoom (default value: "0")​

Defines the zoom value as a percentage.

zoomDestination.setZoom(140);

fitPage Destination​

Jumps to a selected page and fits it to the view.

FitPageDestinationType fitPageDestination = new FitPageDestinationType();
goTo.setDestination(fitPageDestination);

The following parameters can be set for a fitPageDestination.

page (default value: "1")​

Defines the page to jump to.

fitPageDestination.setPage(1);

fitWidth Destination​

Jumps to a selected page and fits its width to the view.

FitWidthDestinationType fitWidthDestination = new FitWidthDestinationType();
goTo.setDestination(fitWidthDestination);

The following parameters can be set for a fitWidthDestination.

page (default value: "1")​

Defines the page to jump to.

fitWidthDestination.setPage(1);

topOffset (default value: "0")​

Defines the distance between the view and the top page margin.

fitWidthDestination.setTopOffset(10);

metrics (default value: "px")​

Defines the measurement unit in which the offsets are specified. Possible values:

  • MM = Millimeters
  • PX = Pixels
fitWidthDestination.setMetrics(MetricsType.MM);

fitHeight Destination​

Jumps to a selected page and fits its height to the view.

FitHeightDestinationType fitHeightDestination = new FitHeightDestinationType();
goTo.setDestination(fitHeightDestination);

The following parameters can be set for a fitHeightDestination.

page (default value: "1")​

Defines the page to jump to.

fitHeightDestination.setPage(1);

leftOffset (default value: "0")​

Defines the distance between the view and the left page margin.

fitHeightDestination.setLeftOffset(15);

metrics (default value: "px")​

Defines the measurement unit in which the offsets are specified. Possible values:

  • MM = Millimeters
  • PX = Pixels
fitHeightDestination.setMetrics(MetricsType.MM);

Go to webPDF 8: Operation Outline - Part 2 - Additional ActionTypes.