1.13.8. Labeled blocks

If an image or a table has a title assigned, then a label is shown in the exported publication before or after the image / table (the position of the label depends on the output configuration).

Figure 1.13.47. A labeled image

For example, if an image has the title "Sunset and sea" and it is the second image in the first chapter, then the label in the exported publication is for instance "Figure 1.2 Sunset and sea". The advantage of such an numbered label is, that the image can be referenced from any place within a publication via its unique ID (the alias name), and depending on the link settings, the link text is automatically replaced in the exported publication by the generated label number (e.g. "Figure 1.2"). This way the reader can easily locate the referenced image or table.
Labeled blocks are not only useful for images and tables, but also for other types of content, e.g. listings, examples, theorems and so on. Docmenta supports the numbering of arbitrary content, by allowing the generation of labels for any user-defined block-style.
To follow the tutorial, create a new block-style with ID "listing". In the style-dialog set the CSS properties to be applied to listings, e.g. a grey background-color and a top-margin of 8 points:

Figure 1.13.48. Style settings for the listing-style

Furthermore, to enable the generation of a label for this style, check the "Show label before/after block" box:

Figure 1.13.49. Creating a labeled block-style

Entering a Label-ID is optional. The Label-ID identifies the type of content. Leaving the Label-ID empty is the same as entering the Style-ID as Label-ID. If you want two or more block-styles to share the same number sequence, then you have to use the same Label-ID for all these styles.
If the "Show label before/after block" box is checked, then you also have to define at least four GenText properties for this style.To do this, select the file  System > gentext.properties. The content of the file is then shown in the preview area:

Figure 1.13.50. Editing the gentext.properties file

To edit the file, click the "Edit" button in the bottom bar of the preview area and add four lines with following structure (each line defines one GenText property)
 
  ID=Pattern
  title|ID=Pattern
  xref-number|ID=Pattern
  xref-number-and-title|ID=Pattern
 
where ID is the Label-ID that you have set for the style (or the Style-ID if a Label-ID is not supplied) and Pattern is the localized text to be used for this GenText property. In our example (assuming that the style-ID is "listing" and a Label-ID is not supplied), add following lines:
 
  listing=Listing
  title|listing=Listing %n. %t
  xref-number|listing=Listing %n
  xref-number-and-title|listing=Listing %n, \u201C%t\u201D
    
The first line defines the label name. As the style shall be used to mark listings the label name is "Listing". If, for instance, the style is used to mark examples, then the label name should be "Example" instead. Note that the text has to be localized, i.e. if the content language were German, then the text had to be in German, e.g. "Beispiel" instead of "Example".
The property "title|ID" defines the localized pattern used for the generated title line, i.e. the line that is inserted before/after the block. You can use the placeholders %n and %t within the pattern. During export, the placeholder %n is replaced by the generated number, and %t is replaced by the title of the content-block. For example, given the pattern in the example above ("Listing %n. %t"), then the generated title of the first listing in the first chapter is "Listing 1.1. My first listing" (assuming that the title of the listing is "My first listing").

When you create a link, you can set the option whether the generated link text shall be only the generated label number or the label number and the title of the referenced block (see Chapter 1.4, Linking content on how to create links). The properties xref-number|ID and xref-number-and-title|ID define the patterns for these two options. For example, given the patterns in the example above, the generated link text for links that reference the first listing in the first chapter with title "My listing", would be either "Listing 1.1" or "Listing 1.1, ‘My listing’",
depending on whether the link option was set to only include the number or the number and the title.

Figure 1.13.51. Updating the gentext.properties file

Note: \u201C is the Unicode escape for an opening quotation mark and \u201D is the
Unicode escape for a closing quotation mark.
Save the modified gentext.properties file by clicking the "Save" button in the bottom bar of the preview-area.
Now that all the configuration work is done, you can use the style to format content as listing. Open a previously created content-node in the content-editor, select one or more paragraphs and apply the style with ID "listing" .

Figure 1.13.52. Applying the listing-style to content

Finally, save the content. When you preview the node, a title-line should be shown below the content to which the listing-style was applied:

Figure 1.13.53. HTML preview of the labeled block

The next exercise is to assign a title to the listing and to create a link that references the listing. Before we can reference the listing, we have to assign an ID to the listing. To assign a title and an ID, we have to select the listing-block in the content-editor.The easiest way to select the listing-block is to place the cursor somewhere within the listing and then select the path element div.listing in the status line of the content-editor:

Figure 1.13.54. Selecting the listing block

After having selected the block, click the "Insert/Edit Attributes" button. In the opened dialog enter an ID for the listing, e.g. "my_listing", and a title:

Figure 1.13.55. Assigning a title and an ID

Close the dialog by clicking "Insert".
Note: The block-selection via status line may not work for all browsers. If you experience problems, then use the HTML-editor to assign a title and an ID to the block. For more information see the note "Browser Issues" in the chapter Section 1.9.2, “Dynamic Templates”.
Now that we've assigned an ID, we can create a link that references the listing. For example, enter the text "As you can see in the listing above" below the listing, select the words "the listing above" and click the "Insert/Edit Link" button. In the opened dialog enter "#my_listing" as Link URL and check the "Use target title" box (see Chapter 1.4, Linking content for an introduction on creating links):

Figure 1.13.56. Referencing the labeled block

Click the "Insert" button to close the dialog. Finally, save the modified content-node.
When you preview the node, you may notice that the link text is still "the listing above". This is because the link text replacement is done during export but not for HTML preview. However, you can check that the link text is correctly replaced during export, by creating a PDF preview of the content-node (i.e. click the PDF-preview button in the toolbar):

Figure 1.13.57. Previewing link text replacement

The PDF preview shows the link text according to the pattern defined by the GenText property xref-number-and-title|ID.