webPDF 8: New features of the Webservice Toolbox – Operation Outline

Part 1:

Editing the table of contents with the webPDF wsclient library

In this article we would like to show an example (Outline Operation) how you can use operations of the webPDF Toolbox webservice with the help of the wsclient library.

Important note:

The following coding example is based on the use of the webPDF wsclient library. In order to understand and apply the example, the following blog post should be considered first:

webPDF and Java: very easy with the “wsclient” library

Creating a REST or SOAP Session

In order to be able to call the Webservice as we would like to present it here, it is assumed that you have already created a REST or SOAP session and can therefore either create a ToolboxWebService object (for a SOAP session) by calling the WebserviceFactory:

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

Or create a ToolboxRestWebService object (for a REST session):

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

And have passed either a RestDocument or a SoapDocument object to this WebService object by calling the method setDocument().

How do you get changing access to a document?

To get modifying 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 at the created toolboxWebService object:

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

If the document does not have an appropriate password protection, you can skip this point.

The Toolbox Webservice…

The Toolbox Webservice is an endpoint of your webPDF server that summarizes a number of operations with which you can directly manipulate your PDF document. This is now about the outline operation (creating and editing outlines) in the course of the new features of webPDF 8.0.

The outline operation allows you to manipulate the table of contents 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 a table of contents 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 table of contents of the document. 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 for the ItemType object:

path (default value: “”)

Specifies the path separated by slashes (/) where the element is to be added to the content structure, starting with an initial slash. The paths of the elements may build on each other as desired and thus allow the tree structure of the table of contents to be built up.

firstPage.setPath("/root");

itemName (default value: “”)

The name of the new element in the content 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 in front of the element selected via path.
• INPLACE = The element selected via path is used as 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 larger font size.

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”)

Specifies 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 item is clicked in the table of contents. 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 to jump to them. By specifying corresponding sub-elements, pages or jump marks can be selected as targets.

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 zooms in on the view size of that page.

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

The following parameters can be set for a zoomDestination:

page (default value: “1”)

Specifies the page to jump to.

zoomDestination.setPage(1);

leftOffset (default value: “0”)

Sets the distance between the view and the left margin of the page.

zoomDestination.setLeftOffset(15);

topOffset (default value: “0”)

Sets the distance between the view and the top of the page.

zoomDestination.setTopOffset(10);

metrics (default value: “px”)

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

• MM = Millimetre
• PX = Pixel

zoomDestination.setMetrics(MetricsType.MM);

zoom (default value: “0”)

Sets the percentage magnification value.

zoomDestination.setZoom(140);

fitPage Destination

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

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

The following parameters can be set for a fitPageDestination:

page (default value: “1”)

Specifies the page to jump to.

fitPageDestination.setPage(1);

fitWidth destination

Jumps to a selected page and adjusts 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”)

Specifies the page to jump to.

fitWidthDestination.setPage(1);

topOffset (default value: “0”)

Sets the distance between the view and the top of the page.

fitWidthDestination.setTopOffset(10);

metrics (default value: “px”)

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

• MM = Millimetre
• PX = Pixel

fitWidthDestination.setMetrics(MetricsType.MM);

fitHeight Destination

Jumps to a selected page and adjusts 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”)

Specifies the page to jump to.

fitHeightDestination.setPage(1);

leftOffset (default value: “0”)

Sets the distance between the view and the left margin of the page.

fitHeightDestination.setLeftOffset(15);

metrics (default value: “px”)

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

• MM = Millimetre
• PX = Pixel

fitHeightDestination.setMetrics(MetricsType.MM);

Click here for webPDF 8: Operation Outline – Part 2 – Presentation of further ActionTypes