6. Widgets

Widgets are available for setting the :

There are four types of widgets

Each widget can be edited directly from the settings panel. In this case, the widget can be reused as a template with predefined formatting. This type of editing is recommended for Text and Image widgets where the content can be modified for each reuse.

6.1. Classic widgets

Procedure 41. To set up a widget :

  1. Click on to the right of the widget name.

    A window opens with the settings.

  2. Click on one of the colored parts of the margins and borders diagram to display its characteristics:

    The result of the setting is displayed in the preview area at the bottom of the window.

    [Tip]

    To apply the rounded corners to the widget borders, click the border (yellow box on the diagram), select the corner or corners you want to round, and apply the desired radius value.

6.2. Custom Xpath widget

The custom Xpath widget can be used to retrieve elements from the XML document that are not available in widgets linked to a particular element.

Xpath is a language for identifying the elements of an XML structure. The configuration of the widget consists in composing an access path for the element of the XML document. This path consists of the nodes (elements, attributes, processing instructions, etc.) linked together by path expressions.

Figure 23. Example of the path

Example of the path

[Note]

The use of path expression types is described in Table 1, “Most Common Path Expressions”.

The Information block contains information that is not published by default. The custom XPath widget allows them to be published.

Elements that can be retrieved from the style sheet via xpath, must also be placed in the Information block of the XML document:

Figure 24. Example of the Information block and its contents

Example of the Information block and its contents

Procedure 42. To compose the xpath:

  1. In the Information block, select the desired element.

  2. In the Context, locate the name of this element.

    Figure 25. Example of an element name in Context

    Example of an element name in Context

    [Note]

    These names are part of the naming convention according to the DocBook standard and are displayed in the tooltip when hovering over each element.

  3. In the studio, drag the widget into the preview area. Click on to the right of the widget name.

  4. In the XPath field of the studio, place the nodes represented by the names of the elements. Precede each name with d: and separate with /. Since the elements are placed in the Information block, the path will start with d:info/.

    [Important]

    For xpath elements in the header or footer, the path must start with /*/.

    This allows the style sheet to retrieve the element for all the page sequences generated by the structure elements (chapters, sections, preface, etc.) present in the document.

    Figure 26. Example of location path in header or footer

    Example of location path in header or footer

[Important]

So that the elements imageobject and mediaobject are correctly interpreted by the style sheet, it is necessary to apply the apply-templates:

Figure 27. Example of the setting for an image

Example of the setting for an image

Setting the xpath to select particular elements of the same type

It is possible to retrieve several elements of the same type (several images, several tables, etc.) in the style sheet via xpath.

Here is the example of the image recovery procedure.

  1. Place all the necessary images in the Information block > Cover.

  2. Give each image a different value in the role attribute by selecting the imageobject element.

    Figure 28. role attribute for imageobject

    role attribute for imageobject

  3. Compose the xpath for each image as follows in the example: d:info//d:imageobject[@role='image_produit'].

Table 1. Most Common Path Expressions

Syntax

Use

Example

d:

indicates that the element belongs to the DocBook namespace.

d:info/d:date

/

used to select children of an element. It indicates that we want to select an element that is directly under the parent element.

d:info/d:date

For the example given, the date element is a child of the info element.

//

used to search items in depth.

d:info//d:date

For the given example, we will search for all the date elements that are in the info block regardless of their parents.

*

selects all items.

d:info/d:legalnotice/d:*

[]

used to filter selected items based on their attributes or values. Or to represent an index in a list.

d:info/d:legalnotice[2]

For the given example, the xpath selects the second legalnotice element, child of the info element.

@

selects attributes.

d:info/d:date[@role='anniversaire']

For the given example, we select the imageobject elements that have the role attribute with the value “anniversary”.


6.3. Grid widget

The Grid widget allows widgets to be organized into rows and columns for more accurate positioning in relation to each other.

The Grid widget is available in the Header and footer and Title pages menus.

The grid has 2 operating modes:

  • Dragging To activate dragging mode, click on the icon:

  • Column editing. To activate column editing, click on the icon:

  1. Drag - drop the widget Grid in the preview area.

  2. Click on to add rows and columns and set the width of the columns:

    [Tip]

    It is possible to set the default number of columns and rows in the widget template:

  3. Drag - drop the necessary widgets inside the cells, on the green background that appears the moment the widget hovers over the cell's borders.

    [Tip]

    If the widgets are to be very close to each other in the vertical direction, it is recommended that they be placed in the same cell.

    [Note]

    It is possible to drag and drop widgets from one grid to another.

  4. For small images, click to access the settings menu.

    Figure 29. Preview of grid settings in the studio

    Preview of grid settings in the studio

    Figure 30. Publication result

    Publication result

    [Caution]

    The image embedded inside the grid via the widget or the custom Xpath, takes the width of the column. It must not have any dimensional or alignment settings in the XML editor (WXE).

When the grid is located in the header or footer area (and not on a title page), column widths can be defined either in millimeters or proportionally. To switch from one to the other, use the button: or .

[Note]

Using a proportional unit grid is useful for PDF documents with alternative page formats, such as certain landscape pages in a portrait document.

This is because the proportional grid will adapt to the zone in which it is located.

When the grid uses proportional column widths, it occupies all the space in the zone.

Explanation of proportional column widths :

The total width of a grid is the sum of its column widths.

The width of one of its columns is therefore the ratio of the width of that column divided by the sum of the column widths multiplied by the width of the zone.

Example 3. Proportional grid

A grid in a 185 mm wide header.

Grid units are proportional.

The grid has 3 columns.

The following column widths: 1, 2, 3

The first column: 1 / ( 1 + 2 + 3 ) x 185 = 30.8mm

The second column: 2 / ( 1 + 2 + 3 ) x 185 = 61.7mm

The third column: 3 / ( 1 + 2 + 3 ) x 185 = 92.5mm


[Note]

It is possible to duplicate a widget grid with its widgets and their settings.