Contents | < Hello World | Flow Layout >

Paragraphs

In XSL-FO, paragraphs are created using fo:block elements. Various attributes can be set on a paragraph:

Horizontal alignment is controlled by text-align attribute.
Borders are set using borders attribute.
Font is set using font-family, font-size, font-weight, etc.
Spacing between two adjacent paragraphs is set using space-before and space-after.

<?xml version="1.0" encoding="utf-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
    <fo:layout-master-set>
        <fo:simple-page-master master-name="LetterPage" 
                                  page-width="6in" page-height="5in">
            <fo:region-body region-name="PageBody" margin="0.7in"/>
        </fo:simple-page-master>
    </fo:layout-master-set>
    <fo:page-sequence master-reference="LetterPage">
        <fo:flow flow-name="PageBody" font-family="Arial" font-size="12pt" > 
            <fo:block text-align="justify" space-after="0.5cm"   
                      border="0.5pt solid green" >
                This is the first paragraph of justified text. Notice how text 
                fills all available space. The surrounding border is 0.5 points 
                wide, solid, green color. This paragraph has a space-after 
                equal to 0.5 cm.
            </fo:block>
            <fo:block text-align="justify" space-before="2cm"  
                      border="0.5pt dotted red" >
                This is the second paragraph of justified text. This time 
                the border is dotted and red. This paragraph has a 
                space-before equal to 2 cm.
            </fo:block>
        </fo:flow>
    </fo:page-sequence>
</fo:root>

For the complete source code for this code example see "Tutorial/Simple Paragraphs.fo" located under XML Documents Samples/Tutorial folder.

In this example, we have two paragraphs of justified text, surrounded by borders, with 2 centimeters distance between them. The result of rendering should be identical with the following figure.

Figure 1

There are several things to notice:

We set the font to Arial, 12 points height on the parent fo:flow element.

The distance between paragraphs is not additive; instead, the largest value will prevail. If a fo:block is the first or the last element in a page, you will also notice that the space is not present anymore! This behavior is controlled by space-before.conditionality and space-after.conditionality attributes. If set to "retain", the corresponding space will not be discarded.

Text Alignment

Horizontal alignment of text is controlled by two attributes: text-align which will set the alignment for all lines of text, except the last one, which is set to text-align-last.

This is important to remember, because if your paragraph has only one line of text, you have to use text-align-last to set the alignment.

Possible values for text-align and text-align-last are:

left (the default) to perform alignment to the right.
right, to perform alignment to the right.
center, to center the paragraph.
justify, to justify the text, so that if fills the whole line.

Fonts

There are six properties that control the aspect of text: font-family, font-style, font-variant, font-weight, font-size, line-height.

To set the font face, you use font-family attribute. For example font-family="Arial" will specify that Arial font must be used.

If multiple font families are specified, the renderer will pick the first available, so you should list the fonts from the most specific to the most generic. For example, font-family="Arial, Helvetica" will select "Helvetica" if "Arial" is not present in the system.

The weight of the font can be specified using font-weight attribute. You can set it to either an absolute value ("bold" or "normal"), or to a value relative to parent element's font weight ("bolder" or "lighter").

To specify the font size, use font-size attribute. This size can be a length (1cm, 0.5in, 10pt, etc) or a percentage (0.5, 50%) from parent element's font.

A very important, and often misused property is line-height. This property determines the minimum line-height for a block element. The default value for line-height is 120%, that is, the line will be 20% taller than the text. For example, if the text is 10 points height, the line height will be of 12 points. The text will be centered on the line, 1 point from top, and 1 points from bottom. In the next example we set the line-height to 200%:

<?xml version="1.0" encoding="utf-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
    <fo:layout-master-set>
        <fo:simple-page-master master-name="LetterPage" 
                               page-width="6in" page-height="5in">
            <fo:region-body region-name="PageBody" margin="0.7in"/>
        </fo:simple-page-master>
    </fo:layout-master-set>
    <fo:page-sequence master-reference="LetterPage">
        <fo:flow flow-name="PageBody">
            <fo:block font-family="Arial" font-size="12pt" line-height="200%"  
                      border="1px outset blue">
                For this paragraph, the line-height is set to 200% ... 
            </fo:block>
        </fo:flow>
    </fo:page-sequence>
</fo:root>

For the complete source code for this code example see "Tutorial/Line Height.fo" located under XML Documents Samples/Tutorial folder.

The result of rendering is displayed in following figure.

Figure 2

We have mentioned before that this is the minimum line height: if a line contains an image of let's say 100 points in height, the total line height (only for that line) will be of 102 points.

To set all font properties at once you can use font shortcut attribute. A shortcut attribute will set the values for multiple attributes at once. The shortcut attribute font has the following syntax:

font="{style} {variant} {weight} {size}/{line-height} family".

For example, to achieve the same effect as the first example in this chapter, you could use font="10pt Arial". Please note that by using this shortcut attribute, instead of specifying each font property individually, you will reset the values of non specified attributes:

<fo:flow flow-name="PageBody">
    <fo:block font="10pt bold Arial"  border="1px solid blue">
        This is the parent block element with a 12 points, bold, 
        Arial font.
        <fo:block font="10pt Verdana"  border="1px solid red">
            This is the child block element; the same shortcut is 
            used for changing the font, but because the weight 
            was omitted, the font is no longer bold.
        </fo:block>
        When the child block ends, the remaining of parent's
        content is displayed.
    </fo:block>
</fo:flow>

For the complete source code for this code example see "Tutorial/Inheritance.fo" located under XML Documents Samples/Tutorial folder.

The result of rendering is displayed in following figure.

Figure 3

XF Rendering Server 2008 can use both Type1 Postscript fonts and TrueType fonts.

Fonts must be installed in Windows before use. To install a new font, simply drag and drop the font files in Control Panel/Fonts.

Borders

The border properties specify the width, color, and style of the borders a object. These properties apply to all XSL-FO elements.

Border widths are set using border-top-width, border-right-width, border-bottom-width, border-left-width attributes. The value can be specified as a length (1pt, 0.5cm, etc). To set all four widths at once you can use border-width shorthand. For example, to set all borders to 0.1 inches thick, you use
```
border-width="0.1in"
```
.
The border color properties are border-top-color, border-right-color, border-bottom-color, border-left-color. The shorthand for setting the color for all four borders at once is border-color.

The border style properties specify the line style of a box's border (solid, double, dashed, etc.). The properties defined in this section refer to the border-style value type, which may take one of the following:

none or hidden	No border.
dotted	The border is a series of dots.
dashed	The border is a series of short line segments.
solid	The border is a single line segment.
double	The border is two solid lines. The sum of the two lines and the space between them equals the value of 'border-width'.
groove	The border looks as though it were carved into the canvas.
ridge	The opposite of 'grove': the border looks as though it were coming out of the canvas.
inset	The border makes the entire box look as though it were embedded in the canvas.
outset	The opposite of 'inset': the border makes the entire box look as though it were coming out of the canvas.

All borders are drawn on top of the box's background.

To set all attributes for a given border, you can use border-top, border-right, border-bottom, border-left shorthand attributes. The format is:

border-top="{width} {style} {color}".

The following notations are equivalent:

<fo:block border-top-style="solid" border-top-color="red" border-top-width="1mm"> 
	... 
</fo:block>
<fo:block border-top="1mm solid red"> 
	... 
</fo:block>

The border property is a shorthand property for setting the same width, color, and style for all four borders of a box. The border property cannot set different values on the four borders. To do so, one or more of the other border properties must be used. The format is:

border="{width} {style} {color}".

Rounded Borders

XF Rendering Server 2008 supports drawing boxes with rounded corners using the border-radius properties described in the CSS3 Backgrounds and Borders Module.

You can set the radius for each corner individually by changing border-top-right-radius, border-bottom-right-radius, border-bottom-left-radius, border-top-left-radius properties. To change all four corners at once, use border-radius. The format is:

<length> <length>?

If only one value is specified, the corner will be drawn as a circle; if two values are specified, the corner will be drawn as an ellipse.

You can read more about CSS3 Backgrounds and Borders Module in the CSS3 W3C Working Draft.

The following sample will draw a paragraph surrounded by a rounded border:

<fo:block border="3pt solid red" border-radius="5pt" 
          background="pink" padding="2pt">Hello World</fo:block>

Please note that the background will have rounded corners even if the border is not visible.

Figure 4

Drop Shadows

Another new feature described in CSS3 is the ability to specify drop shadows for various page elements. You can read more in the CSS3 W3C Working Draft.

In the next example, the shadow is drawn at a 3pt offset in both horizontal and vertical directions, in a light green color. The shadow is transparent, so that the overlapped text can be seen through it.

<fo:block>
				The following 
 				<fo:inline background="yellow" box-shadow="3pt 3pt lime" padding="3pt" 
 				border-radius="4pt">word</fo:inline>
 				has an yellow background and a light green shadow.
 			</fo:block>

Figure 5

For the complete source code, see "Tutorial/RoundedBorders.fo" located under XML Documents Samples/Tutorial folder.

Backgrounds

XSL-FO object's backgrounds may be colors or images. Background properties allow authors to position a background image, repeat it, etc.

To set the background color of an element use background-color attribute. It can be set to either a color value or the keyword "transparent".
background-image sets the background image of an element. When setting a background image, authors should also specify a background color that will be used when the image is unavailable. When the image is available, it is rendered on top of the background color. (Thus, the color is visible in the transparent parts of the image). Values for this property are either an URL, to specify the image, or 'none', when no image is used.

If a background image is specified, background-repeat attribute specifies whether the image is repeated (tiled), and how. It may take one of the following values:

repeat	The image is repeated both horizontally and vertically.
repeat-x	The image is repeated horizontally only.
repeat-y	The image is repeated vertically only.
no-repeat	The image is not repeated: only one copy of the image is drawn.

If a background image has been specified, background-position property specifies its initial position. Values have the following meanings:

pecentage percentage	With a value pair of '0% 0%', the upper left corner of the image is aligned with the upper left corner of the box's padding edge. A value pair of '100% 100%' places the lower right corner of the image in the lower right corner of padding area. With a value pair of '14% 84%', the point 14% across and 84% down the image is to be placed at the point 14% across and 84% down the padding area.
length length	With a value pair of '2cm 2cm', the upper left corner of the image is placed 2cm to the right and 2cm below the upper left corner of the padding area.
top left and left top	Same as '0% 0%'.
top, top center and center top	Same as '50% 0%'.
right top and top right	Same as '100% 0%'.
left, left center and center left	Same as '0% 50%'.
center and center center	Same as '50% 50%'.
right right center and center right	Same as '100% 50%'.
bottom left and left bottom	Same as '0% 100%'.
bottom bottom center and center bottom	Same as '50% 100%'.
bottom right and right bottom	Same as '100% 100%'.

If only one percentage or length value is given, it sets the horizontal position only, the vertical position will be 50%. If two values are given, the horizontal position comes first. Combinations of length and percentage values are allowed, (e.g., '50% 2cm'). Negative positions are allowed. Keywords cannot be combined with percentage values or length values (all possible combinations are given above).

To set all attributes for one element's background, you can use background shortcut attribute. The format is:

background="{color} {image} {repeat} {position}".

Contents | < Hello World | Flow Layout >