Introduction to XSL-FO

XSL-FO is about formatting XML data for output.
What You Should Already Know
Before you study XSL-FO you should have a basic understanding of XML and XML Namespaces.
If you want to study these subjects first, please read our XML Tutorial .
What is XSL-FO?
- XSL-FO is a language for formatting XML data
- XSL-FO stands for Extensible Stylesheet Language Formatting Objects
- XSL-FO is a W3C Recommendation
- XSL-FO is now formally named XSL
XSL-FO is About Formatting
XSL-FO is an XML based markup language describing the formatting of XML data for output to screen, paper or other media.
XSL-FO is Formally Named XSL
Why this confusion? Is XSL-FO and XSL the same thing?
Yes it is, but we will give you an explanation:
Styling is both about transforming and formatting information. When the World Wide Web Consortium (W3C) made their first XSL Working Draft, it contained the language syntax for both transforming and formatting XML documents.
Later the XSL Working Group at W3C split the original draft into separate Recommendations:
- XSLT, a language for transforming information
- XSL or XSL-FO, a language for formatting information
- XPath, a language for defining parts of an XML document
The rest of this tutorial is about formatting information: XSL-FO also called XSL.
You can read more about XSLT in our XSLT Tutorial .
You can read more about XPath in our XPath Tutorial .
XSL-FO is a Web Standard
XSL-FO became a W3C Recommendation 15. October 2001. Formally named XSL.
To read more about the XSL activities at W3C please read our W3C Tutorial .
XSL-FO Documents

XSL-FO documents are XML files with output information.
XSL-FO Documents
XSL-FO documents are XML files with output information. They contain information about the output layout and output contents.
XSL-FO documents are stored in files with a *.fo or a *.fob extension. It is also quite normal to see XSL-FO documents stored with the *.xml extension, because this makes them more accessible to XML editors.
XSL-FO Document Structure
XSL-FO documents have a structure like this:
1<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
2<fo:layout-master-set>
3<fo:simple-page-master master-name="A4">
4<!-- Page template goes here -->
5</fo:simple-page-master>
6</fo:layout-master-set>
7<fo:page-sequence master-reference="A4">
8<!-- Page content goes here -->
9</fo:page-sequence>
10</fo:root>
Structure explained
XSL-FO documents are XML documents, and must always start with an XML declaration:
The
1<fo:root> element contains the XSL-FO document. It also declares the namespace for XSL-FO:
2
3
4 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
5<!-- The full XSL-FO document goes here -->
6</fo:root>
7
8---
9
10The <fo:layout-master-set> element contains one or more page templates:
11
12
13 <fo:layout-master-set>
14<!-- All page templates go here -->
15</fo:layout-master-set>
16
17---
18
19Each <fo:simple-page-master> element contains a single page template. Each template must have a unique name (master-name):
20
21
22 <fo:simple-page-master master-name="A4">
23<!-- One page template goes here -->
24</fo:simple-page-master>
25
26---
27
28One or more <fo:page-sequence> elements describe page contents. The master-reference attribute refers to the simple-page-master template with the same name:
29
30
31 <fo:page-sequence master-reference="A4">
32<!-- Page content goes here -->
33</fo:page-sequence>
34
35---
36
37**Note** : The master-reference "A4" does not actually describe a predefined page format. It is just a name. You can use any name like "MyPage", "MyTemplate", etc.
38
39* * *
40
41# XSL-FO Areas
42
43 
44
45* * *
46
47XSL-FO uses rectangular boxes (areas) to display output.
48
49* * *
50
51## XSL-FO Areas
52
53The XSL formatting model defines a number of rectangular areas (boxes) to display output.
54
55All output (text, pictures, or whatever) will be formatted into these boxes and then displayed or printed to a target media.
56
57We will take a closer look at the following areas:
58
59 * Pages
60 * Regions
61 * Block areas
62 * Line areas
63 * Inline areas
64
65
66
67* * *
68
69## XSL-FO Pages
70
71XSL-FO output is formatted into pages. Printed output will normally go into many separate pages. Browser output will often go into one long page.
72
73XSL-FO Pages contain Regions.
74
75* * *
76
77## XSL-FO Regions
78
79Each XSL-FO Page contains a number of Regions:
80
81 * region-body (the body of the page)
82 * region-before (the header of the page)
83 * region-after (the footer of the page)
84 * region-start (the left sidebar)
85 * region-end (the right sidebar)
86
87
88
89XSL-FO Regions contain Block areas.
90
91* * *
92
93## XSL-FO Block Areas
94
95XSL-FO Block areas define small block elements (the ones that normally starts with a new line) like paragraphs, tables and lists.
96
97XSL-FO Block areas can contain other Block areas, but most often they contain Line areas.
98
99* * *
100
101## XSL-FO Line Areas
102
103XSL-FO Line areas define text lines inside Block areas.
104
105XSL-FO Line areas contain Inline areas.
106
107* * *
108
109## XSL-FO Inline Areas
110
111XSL-FO Inline areas define text inside Lines (bullets, single character, graphics, and more).
112
113* * *
114
115# XSL-FO Output
116
117 
118
119* * *
120
121XSL-FO defines output inside <fo:flow> elements.
122
123* * *
124
125## XSL-FO Page, Flow, and Block
126
127"Blocks" of content "Flows" into "Pages" and then to the output media.
128
129XSL-FO output is normally nested inside <fo:block> elements, nested inside <fo:flow> elements, nested inside <fo:page-sequence> elements:
130
131
132 <fo:page-sequence>
133<fo:flow flow-name="xsl-region-body">
134<fo:block>
135<!-- Output goes here -->
136</fo:block>
137</fo:flow>
138</fo:page-sequence>
139
140---
141
142
143
144* * *
145
146## XSL-FO Example
147
148It is time to look at a real XSL-FO example:
149
150
151 <?xml version="1.0" encoding="ISO-8859-1"?>
152<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
153<fo:layout-master-set>
154<fo:simple-page-master master-name="A4">
155</fo:simple-page-master>
156</fo:layout-master-set>
157<fo:page-sequence master-reference="A4">
158<fo:flow flow-name="xsl-region-body">
159<fo:block>Hello W3Schools</fo:block>
160</fo:flow>
161</fo:page-sequence>
162</fo:root>
163
164---
165
166The output from this code would be something like this:
167
168Hello W3Schools
169
170---
171
172
173
174* * *
175
176# XSL-FO Flow
177
178 
179
180* * *
181
182XSL-FO pages are filled with data from <fo:flow> elements.
183
184* * *
185
186## XSL-FO Page Sequences
187
188XSL-FO uses <fo:page-sequence> elements to define **output pages** .
189
190Each **output page** refers to a page master which defines **the layout** .
191
192Each **output page** has a <fo:flow> element defining **the output** .
193
194Each **output page** is printed (or displayed) **in sequence** .
195
196* * *
197
198## XSL-FO Flow
199
200XSL-FO pages are filled with content from the <fo:flow> element.
201
202The <fo:flow> element contains all the elements to be printed to the page.
203
204When the page is full, the same page master will be used over (and over) again until all the text is printed.
205
206* * *
207
208## Where To Flow?
209
210The <fo:flow> element has a "flow-name" attribute.
211
212The value of the flow-name attribute defines where the content of the <fo:flow> element will go.
213
214The legal values are:
215
216 * xsl-region-body (into the region-body)
217 * xsl-region-before (into the region-before)
218 * xsl-region-after (into the region-after)
219 * xsl-region-start (into the region-start)
220 * xsl-region-end (into the region-end)
221
222
223
224* * *
225
226# XSL-FO Pages
227
228 
229
230* * *
231
232XSL-FO uses page templates called "Page Masters" to define the layout of pages.
233
234* * *
235
236## XSL-FO Page Templates
237
238XSL-FO uses page templates called "Page Masters" to define the layout of pages. Each template must have a unique name:
239
240
241 <fo:simple-page-master master-name="intro">
242<fo:region-body margin="5in"></fo:region-body>
243</fo:simple-page-master>
244<fo:simple-page-master master-name="left">
245<fo:region-body margin-left="2in" margin-right="3in"></fo:region-body>
246</fo:simple-page-master>
247<fo:simple-page-master master-name="right">
248<fo:region-body margin-left="3in" margin-right="2in"></fo:region-body>
249</fo:simple-page-master>
250
251---
252
253In the example above, three <fo:simple-page-master> elements, define three different templates. Each template (page-master) has a different name.
254
255The first template is called "intro". It could be used as a template for introduction pages.
256
257The second and third templates are called "left" and "right". They could be used as templates for even and odd page numbers.
258
259* * *
260
261## XSL-FO Page Size
262
263XSL-FO uses the following attributes to define the size of a page:
264
265 * page-width defines the width of a page
266 * page-height defines the height of a page
267
268
269
270* * *
271
272## XSL-FO Page Margins
273
274XSL-FO uses the following attributes to define the margins of a page:
275
276 * margin-top defines the top margin
277 * margin-bottom defines the bottom margin
278 * margin-left defines the left margin
279 * margin-right defines the right margin
280 * margin defines all four margins
281
282
283
284* * *
285
286## XSL-FO Page Regions
287
288XSL-FO uses the following elements to define the regions of a page:
289
290 * region-body defines the body region
291 * region-before defines the top region (header)
292 * region-after defines the bottom region (footer)
293 * region-start defines the left region (left sidebar)
294 * region-end defines the right region (right sidebar)
295
296
297
298Note that the region-before, region-after, region-start, and region-end is a part of the body region. To avoid text in the body region to overwrite text in these regions, the body region must have margins at least the size of these regions.
299
300| Margin Top
301---
302
303M
304a
305r
306g
307i
308n
309
310L
311e
312f
313t
314
315
316| | REGION BEFORE
317---
318R
319E
320G
321I
322O
323N
324
325S
326T
327A
328R
329T |
330
331REGION BODY
332
333| R
334E
335G
336I
337O
338N
339
340E
341N
342D
343
344REGION AFTER
345M
346a
347r
348g
349i
350n
351
352R
353i
354g
355h
356t
357Margin Bottom
358
359
360
361* * *
362
363## XSL-FO Example
364
365This is an extract from an XSL-FO document:
366
367
368 <fo:simple-page-master margin-bottom="1cm" margin-left="1cm" margin-right="1cm" margin-top="1cm" master-name="A4" page-height="210mm" page-width="297mm">
369<fo:region-body margin="3cm"></fo:region-body>
370<fo:region-before extent="2cm"></fo:region-before>
371<fo:region-after extent="2cm"></fo:region-after>
372<fo:region-start extent="2cm"></fo:region-start>
373<fo:region-end extent="2cm"></fo:region-end>
374</fo:simple-page-master>
375
376---
377
378The code above defines a "Simple Page Master Template" with the name "A4".
379
380The width of the page is 297 millimeters and the height is 210 millimeters.
381
382The top, bottom, left, and right margins of the page are all 1 centimeter.
383
384The body has a 3 centimeter margin (on all sides).
385
386The before, after, start, and end regions (of the body) are all 2 centimeters.
387
388The width of the body in the example above can be calculated by subtracting the left and right margins and the region-body margins from the width of the page itself:
389
390297mm - (2 x 1cm) - (2 x 3cm) = 297mm - 20mm - 60mm = 217mm.
391
392Note that the regions (region-start and region-end) are not a part of the calculation. As described earlier, these regions are parts of the body.
393
394* * *
395
396# XSL-FO Blocks
397
398 
399
400* * *
401
402XSL-FO output goes into blocks.
403
404* * *
405
406## XSL-FO Pages, Flow, and Block
407
408"Blocks" of content "Flow" into "Pages" of the output media.
409
410XSL-FO output is normally nested inside <fo:block> elements, nested inside <fo:flow> elements, nested inside <fo:page-sequence> elements:
411
412
413 <fo:page-sequence>
414<fo:flow flow-name="xsl-region-body">
415<fo:block>
416<!-- Output goes here -->
417</fo:block>
418</fo:flow>
419</fo:page-sequence>
420
421---
422
423
424
425* * *
426
427## Block Area Attributes
428
429Blocks are sequences of output in rectangular boxes:
430
431
432 <fo:block border-width="1mm">
433 This block of output will have a one millimeter border around it.
434 </fo:block>
435
436---
437
438Since block areas are rectangular boxes, they share many common area properties:
439
440 * space before and space after
441 * margin
442 * border
443 * padding
444
445space before
446
447---
448margin
449| border
450| padding
451|
452
453
454content
455
456
457
458
459---
460
461
462
463
464
465
466space after
467
468---
469
470The **space before** and **space after** is the empty space separating the block from the other blocks.
471
472The **margin** is the empty area on the outside of the block.
473
474The **border** is the rectangle drawn around the external edge of the area. It can have different widths on all four sides. It can also be filled with different colors and background images.
475
476The **padding** is the area between the border and the content area.
477
478The **content** area contains the actual content like text, pictures, graphics, or whatever.
479
480* * *
481
482## Block Margin
483
484 * margin
485 * margin-top
486 * margin-bottom
487 * margin-left
488 * margin-right
489
490
491
492* * *
493
494## Block Border
495
496Border style attributes:
497
498 * border-style
499 * border-before-style
500 * border-after-style
501 * border-start-style
502 * border-end-style
503 * border-top-style (same as border-before)
504 * border-bottom-style (same as border-after)
505 * border-left-style (same as border-start)
506 * border-right-style (same as border-end)
507
508
509
510Border color attributes:
511
512 * border-color
513 * border-before-color
514 * border-after-color
515 * border-start-color
516 * border-end-color
517 * border-top-color (same as border-before)
518 * border-bottom-color (same as border-after)
519 * border-left-color (same as border-start)
520 * border-right-color (same as border-end)
521
522
523
524Border width attributes:
525
526 * border-width
527 * border-before-width
528 * border-after-width
529 * border-start-width
530 * border-end-width
531 * border-top-width (same as border-before)
532 * border-bottom-width (same as border-after)
533 * border-left-width (same as border-start)
534 * border-right-width (same as border-end)
535
536
537
538* * *
539
540## Block Padding
541
542 * padding
543 * padding-before
544 * padding-after
545 * padding-start
546 * padding-end
547 * padding-top (same as padding-before)
548 * padding-bottom (same as padding-after)
549 * padding-left (same as padding-start)
550 * padding-right (same as padding-end)
551
552
553
554* * *
555
556## Block Background
557
558 * background-color
559 * background-image
560 * background-repeat
561 * background-attachment (scroll or fixed)
562
563
564
565* * *
566
567## Block Styling Attributes
568
569Blocks are sequences of output that can be styled individually:
570
571
572 <fo:block font-family="sans-serif" font-size="12pt">
573 This block of output will be written in a 12pt sans-serif font.
574 </fo:block>
575
576---
577
578Font attributes:
579
580 * font-family
581 * font-weight
582 * font-style
583 * font-size
584 * font-variant
585
586
587
588Text attributes:
589
590 * text-align
591 * text-align-last
592 * text-indent
593 * start-indent
594 * end-indent
595 * wrap-option (defines word wrap)
596 * break-before (defines page breaks)
597 * break-after (defines page breaks)
598 * reference-orientation (defines text rotation in 90" increments)
599
600
601
602* * *
603
604## Example
605
606
607 <fo:block font-color="red" font-family="verdana" font-size="14pt" space-after="5mm" space-before="5mm">
608 W3Schools
609 </fo:block>
610<fo:block font-family="verdana" font-size="12pt" space-after="5mm" space-before="5mm" text-indent="5mm">
611 At W3Schools you will find all the Web-building tutorials you
612 need, from basic HTML and XHTML to advanced XML, XSL, Multimedia
613 and WAP.
614 </fo:block>
615
616---
617
618Result:
619
620
621W3Schools
622
623At W3Schools you will find all the Web-building tutorials you need, from basic HTML and XHTML to advanced XML, XSL, Multimedia and WAP.
624
625
626---
627
628When you look at the example above, you can see that it will take a lot of code to produce a document with many headers and paragraphs.
629
630Normally XSL-FO document do not combine formatting information and content like we have done here.
631
632With a little help from XSLT we can put the formatting information into templates and write a cleaner content.
633
634You will learn more about how to combine XSL-FO with XSLT templates in a later chapter in this tutorial.
635
636* * *
637
638# XSL-FO Lists
639
640 
641
642* * *
643
644XSL-FO uses List Blocks to define lists.
645
646* * *
647
648## XSL-FO List Blocks
649
650There are four XSL-FO objects used to create lists:
651
652 * fo:list-block (contains the whole list)
653 * fo:list-item (contains each item in the list)
654 * fo:list-item-label (contains the label for the list-item - typically an <fo:block> containing a number, character, etc.)
655 * fo:list-item-body (contains the content/body of the list-item - typically one or more <fo:block> objects)
656
657
658
659An XSL-FO list example:
660
661
662 <fo:list-block>
663<fo:list-item>
664<fo:list-item-label>
665<fo:block>*</fo:block>
666</fo:list-item-label>
667<fo:list-item-body>
668<fo:block>Volvo</fo:block>
669</fo:list-item-body>
670</fo:list-item>
671<fo:list-item>
672<fo:list-item-label>
673<fo:block>*</fo:block>
674</fo:list-item-label>
675<fo:list-item-body>
676<fo:block>Saab</fo:block>
677</fo:list-item-body>
678</fo:list-item>
679</fo:list-block>
680
681---
682
683The output from this code would be:
684
685
686* Volvo
687* Saab
688
689---
690
691
692
693* * *
694
695# XSL-FO Tables
696
697 
698
699* * *
700
701XSL-FO uses the <fo:table-and-caption> element to define tables.
702
703* * *
704
705## XSL-FO Tables
706
707The XSL-FO table model is not very different from the HTML table model.
708
709There are nine XSL-FO objects used to create tables:
710
711 * fo:table-and-caption
712 * fo:table
713 * fo:table-caption
714 * fo:table-column
715 * fo:table-header
716 * fo:table-footer
717 * fo:table-body
718 * fo:table-row
719 * fo:table-cell
720
721
722
723XSL-FO uses the ** <fo:table-and-caption> ** element to define a table. It contains a < **fo:table** > and an optional ** <fo:caption> ** element.
724
725The <fo:table> element contains optional ** <fo:table-column> ** elements, an optional ** <fo:table-header> ** element, a ** <fo:table-body> ** element, and an optional ** <fo:table-footer> ** element. Each of these elements has one or more ** <fo:table-row> ** elements, with one or more ** <fo:table-cell> ** elements:
726
727
728 <fo:table-and-caption>
729<fo:table>
730<fo:table-column column-width="25mm"></fo:table-column>
731<fo:table-column column-width="25mm"></fo:table-column>
732<fo:table-header>
733<fo:table-cell>
734<fo:block font-weight="bold">Car</fo:block>
735</fo:table-cell>
736<fo:table-cell>
737<fo:block font-weight="bold">Price</fo:block>
738</fo:table-cell>
739</fo:table-header>
740<fo:table-body>
741<fo:table-row>
742<fo:table-cell>
743<fo:block>Volvo</fo:block>
744</fo:table-cell>
745<fo:table-cell>
746<fo:block>$50000</fo:block>
747</fo:table-cell>
748</fo:table-row>
749<fo:table-row>
750<fo:table-cell>
751<fo:block>SAAB</fo:block>
752</fo:table-cell>
753<fo:table-cell>
754<fo:block>$48000</fo:block>
755</fo:table-cell>
756</fo:table-row>
757</fo:table-body>
758</fo:table>
759</fo:table-and-caption>
760
761---
762
763The output from this code would something like this:
764
765Car | Price
766---|---
767Volvo | $50000
768SAAB | $48000
769
770
771
772* * *
773
774# XSL-FO and XSLT
775
776 
777
778* * *
779
780XSL-FO and XSLT can help each other.
781
782* * *
783
784## Remember this Example?
785
786
787 <fo:block font-color="red" font-family="verdana" font-size="14pt" space-after="5mm" space-before="5mm">
788 W3Schools
789 </fo:block>
790<fo:block font-family="verdana" font-size="12pt" space-after="5mm" space-before="5mm" text-indent="5mm">
791 At W3Schools you will find all the Web-building tutorials you
792 need, from basic HTML and XHTML to advanced XML, XSL, Multimedia
793 and WAP.
794 </fo:block>
795
796---
797
798Result:
799
800
801W3Schools
802
803At W3Schools you will find all the Web-building tutorials you need, from basic HTML and XHTML to advanced XML, XSL, Multimedia and WAP.
804
805
806---
807
808The example above is from the chapter about XSL-FO Blocks.
809
810* * *
811
812## With a Little Help from XSLT
813
814Remove the XSL-FO information from the document:
815
816
817 <header>
818 W3Schools
819 </header>
820<paragraph>
821 At W3Schools you will find all the Web-building tutorials you
822 need, from basic HTML and XHTML to advanced XML, XSL, Multimedia
823 and WAP.
824 </paragraph>
825
826---
827
828Add an XSLT transformation:
829
830
831 <xsl:template match="header">
832<fo:block font-color="red" font-family="verdana" font-size="14pt" space-after="5mm" space-before="5mm">
833<xsl:apply-templates></xsl:apply-templates>
834</fo:block>
835</xsl:template>
836<xsl:template match="paragraph">
837<fo:block font-family="verdana" font-size="12pt" space-after="5mm" space-before="5mm" text-indent="5mm">
838<xsl:apply-templates></xsl:apply-templates>
839</fo:block>
840</xsl:template>
841
842---
843
844And the result will be the same:
845
846
847W3Schools
848
849At W3Schools you will find all the Web-building tutorials you need, from basic HTML and XHTML to advanced XML, XSL, Multimedia and WAP.
850
851
852---
853
854
855
856* * *
857
858# XSL-FO Software
859
860 
861
862* * *
863
864XSL-FO needs formatting software to produce output.
865
866* * *
867
868## XSL-FO Processors
869
870An XSL-FO processor is a software program for formatting XSL documents for output.
871
872Most XSL-FO processors can output PDF document, and quality print as well as HTML and other formats.
873
874Here is a list of the most common XSL-FO processors:
875
876* * *
877
878## XSL Formatter
879
880XSL Formatter is a software to format XML documents for production-quality printing and output to PDF.
881
882Antenna House has been providing version V2 of the same product since January, 2002 in the global market, and XSL Formatter was rated as one of the best quality product at the XML 2002, XML 2003 conferences held in Europe.
883
884Building on over 4 years of experience developing XSL-FO software, Antenna House has completely written from scratch an entirely new Formatter that offers significant enhancements and provides a solid foundation on which to continue to move forward.
885
886Visit Antenna House
887
888* * *
889
890## Xinc Beta Release
891
892Xinc is an XSL-FO processor by Lunasil LTD.
893
894Xinc is designed to be fast, multithreaded and memory efficient. A Swing based XSL-FO viewer allows you to view and print XSL-FO files as well as generate PDF files with the click of a button. Xinc can be used as a server component via its Java API. Xinc can also be used in a Microsoft server environment by using its COM interface. New features include hyphenation, basic-link, PDF output, memory/speed optimizations and a simple COM interface.
895
896Visit Lunasil Ltd
897
898* * *
899
900## Scriptura
901
902Inventive Designers Scriptura is a cross-platform document design and generation solution based on XSLT and XSL-FO.
903
904Scriptura has a WYSIWYG design tool and engine. The XSL-FO formatter used in the engine is no longer based on Apache FOP, but is written from scratch by Inventive Designers. The new features in this release are: support for bulleted and numbered lists, 'break-before' and 'break-after' properties, extended bar code options and improved number and currency formatting. A free trial version is available for download.
905
906Visit Inventive Designers
907
908* * *</fo:table-cell></fo:table-row></fo:table-footer></fo:table-body></fo:table-header></fo:table-column></fo:table></fo:caption></fo:table-and-caption></fo:table-and-caption></fo:block></fo:block></fo:page-sequence></fo:flow></fo:block></fo:simple-page-master></fo:flow></fo:flow></fo:flow></fo:flow></fo:flow></fo:page-sequence></fo:flow></fo:page-sequence></fo:flow></fo:block></fo:flow></fo:page-sequence></fo:simple-page-master></fo:layout-master-set></fo:root>