Positioning Text with Block Containers: fo:block-container

Positioning Text with Block Containers: <fo:block-container>

XSL-FO processors are much like HTML browsers in one respect: They insert blocks into a pages flow, which means those blocks can flow throughout the document, just as they would in an HTML browser. On the other hand, sometimes its important to place items in a page at specific locations. And in XSL-FO, you can position items at absolute page coordinates, or at relative ones with respect to other items.

To show how this works, I use the <fo:block-container> element, which works as youd expect: as a container for blocks. What makes this element useful is that block containers support absolute positioning properties, which blocks dont.

You can use the following properties with the <fo:block-container> element:

Common absolute position properties: absolute-position, top, right, bottom, left
Common border, padding, and background properties: background-attachment , background- color , background-image, background-repeat , background-position-horizontal, background-position-vertical, border-before-color, border-before-style, border-before-width, border-after-color, border-after-style, border-after-width, border-start-color, border-start-style, border-start-width, border-end-color, border-end-style, border-end-width, border-top-color, border-top-style, border-top-width, border-bottom-color, border-bottom-style, border-bottom-width, border-left-color, border-left-style, border-left-width, border-right-color, border-right-style, border-right-width, padding-before, padding-after, padding-start, padding-end, padding-top, padding-bottom, padding-left, padding-right
Common margin properties for blocks: margin-top, margin-bottom, margin-left, margin-right, space-before, space-after, start-indent, end-indent
block-progression-dimension
break-after
break-before
clip
display-align
height
id
inline-progression-dimension
keep-together
keep-with- next
keep-with-previous
overflow
reference-orientation
span
width
writing-mode

In the following example, Im using block containers as wrappers for blocks that I want to place at specific locations on the page:

Listing 12.3 blockcontainer.fo

 <?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 margin-right="20mm" margin-left="20mm"              margin-bottom="10mm" margin-top="10mm" page-width="300mm"              page-height="400mm" master-name="page">              <fo:region-body margin-right="0mm" margin-left="0mm"                  margin-bottom="10mm" margin-top="0mm"/>              <fo:region-after extent="10mm"/>          </fo:simple-page-master>      </fo:layout-master-set>      <fo:page-sequence master-name="page">          <fo:flow flow-name="xsl-region-body">              <fo:block-container height="4cm" width="12cm" top="0cm"                  left="0cm"                  position="absolute">                  <fo:block text-align="start" line-height="18pt"                  font-family="sans-serif" font-weight="bold" font-size="14pt">                       Starpowder                  </fo:block>                  <fo:block text-align="start" line-height="18pt"                      font-family="sans-serif"                      font-size="14pt">                      The Starpowder Building                  </fo:block>                  <fo:block text-align="start" line-height="18pt"                      font-family="sans-serif"                      font-size="14pt">                      1 Starpowder Avenue                  </fo:block>                  <fo:block text-align="start" line-height="18pt"                      font-family="sans-serif"                      font-size="14pt">                      New York, NY, 10011                  </fo:block>              </fo:block-container>              <fo:block-container height="1cm" width="6cm" top="0cm"                  left="14cm"                  position="absolute">                  <fo:block text-align="start" line-height="22pt"                      font-family="sans-serif"                      font-size="23pt">                      Invoice                  </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                  border-width="1pt" height="0.7cm" width="3.5cm" top="1.2cm"                  left="12.0cm" padding="2pt" position="absolute">                  <fo:block text-align="start" line-height="15pt"                      font-family="sans-serif"                      font-size="12pt">                      Date                  </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                  border-width="1pt" height="0.7cm" width="3.5cm" top="1.9cm"                  left="12.0cm" padding="2pt" position="absolute">                  <fo:block text-align="start" line-height="15pt"                      font-family="sans-serif" font-size="12pt">                      January 1, 2002                  </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                  border-width="1pt" height="0.7cm" width="3.5cm" top="1.2cm"                  left="15.5cm" padding="2pt" position="absolute">                  <fo:block text-align="start" line-height="15pt"                      font-family="sans-serif" font-size="12pt">                      Terms                  </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                 border-width="1pt" height="0.7cm" width="3.5cm" top="1.9cm"                 left="15.5cm" padding="2pt" position="absolute">                 <fo:block text-align="start" line-height="15pt"                     font-family="sans-serif" font-size="12pt">                     Immediate                 </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                  border-width="1pt" height="1.0cm" width="9cm" top="3cm"                  left="0cm" padding="2pt" position="absolute">                  <fo:block text-align="center" line-height="22pt"                      font-family="sans-serif" font-size="18pt">                      Description of Service                  </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                  border-width="1pt" height="4cm" width="9cm" top="4.0cm"                  left="0cm"                  padding="2pt" position="absolute">                  <fo:block text-align="start" line-height="15pt"                      font-family="sans-serif" font-size="12pt">                  </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                  border-width="1pt" height="1.0cm" width="9cm" top="3cm"                  left="10cm"                  padding="2pt" position="absolute">                  <fo:block text-align="center" line-height="22pt"                      font-family="sans-serif" font-size="18pt">                      Address for Payment                      </fo:block>              </fo:block-container>              <fo:block-container border-color="black" border-style="solid"                  border-width="1pt" height="4cm" width="9cm" top="4.0cm"                  left="10cm"                  padding="2pt" position="absolute">                  <fo:block text-align="start" line-height="15pt"                      font-family="sans-serif" font-size="12pt">                  </fo:block>              </fo:block-container>          </fo:flow>      </fo:page-sequence>  </fo:root>

You can see the PDF document fop creates from blockcontainers.fo in Figure 12.2. As you see in that figure, Ive positioned various blocks at various locations in that document. Some boxes must be positioned directly on top of others, so positioning is very important in this case.

Figure 12.2. Using block containers.

In fact, its easy to use block containers. For example, take a look at the Description of Service box in Figure 12.2. I create this box using two block containers, one holding the title, Description of Service, and the other holding the blank box directly underneath. To create the title box, I use the <fo:block-container> element, specifying this boxs dimensions with the height and width properties, and giving it a border with the border-width property. I also set its position on the page by setting the position property to absolute and using the left and top properties to position the top left corner of the box with respect to the top left corner of the page:

 <fo:block-container border-color="black" border-style="solid"      border-width="1pt" height="1.0cm" width="9cm" top="3cm"      left="0cm" padding="2pt" position="absolute">      .      .      .  </fo:block-container>

Now I can enclose a block with the title, Description of Service, in it:

 <fo:block-container border-color="black" border-style="solid"      border-width="1pt" height="1.0cm" width="9cm" top="3cm"      left="0cm" padding="2pt" position="absolute">      <fo:block text-align="center" line-height="22pt"          font-family="sans-serif"          font-size="18pt">          Description of Service      </fo:block>  </fo:block-container>

Next, I position a blank box directly beneath the title box:

 </fo:block-container>  <fo:block-container border-color="black" border-style="solid"      border-width="1pt" height="1.0cm" width="9cm" top="3cm"      left="0cm" padding="2pt" position="absolute">      <fo:block text-align="center" line-height="22pt"          font-family="sans-serif"          font-size="18pt">          Description of Service      </fo:block>  </fo:block-container>  <fo:block-container border-color="black" border-style="solid"      border-width="1pt" height="4cm" width="9cm" top="4.0cm"      left="0cm"      padding="2pt" position="absolute">      <fo:block text-align="start" line-height="15pt"      font-family="sans-serif"      font-size="12pt">      </fo:block>  </fo:block-container>

And you can see the results in Figure 12.2. To me, this is one of the most useful aspects of XSL-FO: the ability it gives you to place items exactly where you want them. You can rely on the flow of objects as created by the XSL-FO processor, but sometimes you really want to place objects in a specific place, and now you can do it.