SVG 1.2 - 27 October 2004

Previous | Top | Next

5 Multiple pages

An SVG 1.2 document or document fragment can have multiple pages. While the concept of a "page" usually applies to printed media, a page in SVG is defining an ordered list of groups containing graphics, with only one group being displayed at any time. This translates to a printed page for hardcopy output.

The following is an example using multiple pages:

<svg xmlns="http://www.w3.org/2000/svg" version="1.2">

  <pageSet>
     
     <!-- here is the first page -->
     <page>
       <circle cx="100" cy="100" r="20" fill="blue"/>
     </page>

     <!-- here is the second page -->
     <page>
       <rect x="100" y="100" width="20" height="20"
             fill="red"/>
     </page>

  </pageSet>

</svg>

There are two pages in the example above. The first page has a blue circle; The second page has a red rectangle.

All pages are contained within a single pageSet element. A pageSet may contain any number of page elements. Each page element defines a single container of graphical objects.

The pageSet and page elements introduce different reference scoping rules from the rest of the SVG language. Each page element has a local scope. References in a page can only be to elements within the same page or in the root SVG document (i.e. before the pageSet element). It is an error to refer to content in a different page element, regardless of its position in the document. Any resources defined on a page are local to that page and go out of scope once the page is no longer being rendered. External references are permitted, but authors are strongly encouraged to use the externalResourcesRequired feature in this case.

The scoping mechanism allows an implementation to free any resources required to render a single page if the streamedContents attribute is equal to "discard". The behavior is described in the chapter on Streamed Contents. The scoping also provides a simple mechanism to render page ranges by skipping content between page elements until the desired page range is reached.

Below is an example of an SVG document with multiple pages:

<svg xmlns="http://www.w3.org/2000/svg" version="1.2"
     streamedContents="true">

   <defs>
     <!-- definitions here are always available -->
   </defs>

   <g>
     <!-- graphics here are always visible -->
   </g>

   <pageSet>

      <page>
        <defs>
          <!-- These definitions are local to this page. -->
        </defs>
        <!-- graphics for page 1 go here -->
      </page>

      <page orientation="90">
        <!-- graphics for page 2 go here -->
      </page>

      <page>
        <!-- graphics for page 3 go here -->
      </page>

   </pageSet>

   <!-- No SVG content is allowed here -->
</svg>

No element from the SVG namespace is allowed between the closing pageSet tag and the closing svg tag. For example:

    <svg>
        <pageSet>
        </pageSet>
        <!-- No SVG elements are allowed here -->
    </svg>

This also precludes any content in this location from another namespace that through a binding mechanism such as sXBL would create shadow content using elements from the SVG language. Any document that violates this rule is in error.

The pageSet and page elements faciliate streamed animation. Many animations involve a set of scenes shown in sequence, such as cartoons. In SVG, each scene in the animation is mapped to a page element. Once a scene has ended (the animations running on the page complete), then the next scene is shown, or the user agent pauses until the entire next scene/page is downloaded.

5.1 Displaying Pages

In a screen-based user agent, only one page element is displayed at any time on the main canvas. The page displayed is referred to as the "current page". The first page in document order is the default "current page". User agents are expected to provide some mechanism for modifying the current page, and therefore allowing the user to navigate between pages. Page navigation may also occur automatically in a streamed document.

User agents are allowed to provide an alternate view, in a separate canvas if possible, to facilitate operations such as print preview, where multiple pages may be displayed at once. If the alternate view of a multiple page document is not animated, then the view should use the begin time of the individual pages.

If printing is invoked on an SVG document, i.e. the root element of the document is an SVG element, all pages should be printed or the user agent will provide a means for selecting the pages to print. In general if printing is invoked on a document in another namespace, such as XHTML, that contains an SVG document fragment with pageset and pages, the "current page" of the SVG fragment at the begin time for that page should be printed. If an SVG file or document fragment is encapsulated inside a namespace capable of specifying control over the job information (e.g. JDF) then it is expected that this information will be followed.

Content after the opening svg tag and before the opening pageSet tag is always displayed, regardless of what page is current. Graphical elements here can be considered part of a "master page" that is rendered before the individual page contents are rendered.

If an SVG document fragment with multiple pages is embedded in, or referenced by, a document from another namespace, such as XHTML, then typically it is up to that namespace to define the processing of pages. The recommended behavior is that the container document display the "current page" of the SVG fragment, unless it has some mechanism to allow the paged media.

5.2 Timing and animation

The pageSet and page elements are SMIL time containers. The pageSet element is the equivalent of a seq element in SMIL. The page element is the equivalent of the par element in SMIL. For details on their behaviors refer to the SMIL specification references given in section 8.3 and 8.4 respectively. The combination of the pageSet and page elements and the SMIL timing attributes provide a method to stream long-running declarative animations.

A page can have transition effects applied as the user agent moves from one page to the next. The transin and transout attributes are allowed on the page element.

5.3 The pageSet element

The pageSet element is the container for a set of page elements.

pageSet Schema

  <define name="pageSet">
    <element name="pageSet">
      <ref name="attlist.pageSet"/>
      <ref name="SVG.pageSet.content"/>
    </element>
  </define>

  <define name="attlist.pageSet" combine="interleave">
    <ref name="SVG.Core.attrib"/>
    <ref name="SVG.Style.attrib"/>
    <ref name="SVG.Presentation.attrib"/>
    <ref name="SVG.GraphicalEvents.attrib"/>
  </define>

  <define name="SVG.pageSet.content">
    <zeroOrMore>
      <ref name="SVG.Description.class"/>
    </zeroOrMore>
    <zeroOrMore>
      <ref name="defs"/>
    </zeroOrMore>
    <zeroOrMore>
      <ref name="page"/>
    </zeroOrMore>
  </define>

A pageset element has the time container behavior of the SMIL2 "seq" element. Like seq, pageSet supports all timing attributes except endsync.

5.4 The page element

The page element contains graphics that are rendered when the page is the "current page".

page Schema

  <define name="page">
    <element name="page">
      <ref name="attlist.page"/>
      <ref name="SVG.page.content"/>
    </element>
  </define>

  <define name="attlist.page" combine="interleave">
    <ref name="SVG.Core.attrib"/>
    <ref name="SVG.Style.attrib"/>
    <ref name="SVG.Presentation.attrib"/>
    <ref name="SVG.Focusable.attrib"/>
    <ref name="SVG.Transition.attrib"/>
    <ref name='SVG.AnimationTiming.attrib'/>
    <optional>
      <attribute name="page-orientation" a:defaultValue="0" svg:animatable="true" svg:inheritable="false">
        <choice>
          <value>-270</value>
          <value>-180</value>
          <value>-90</value>
          <value>0</value>
          <value>90</value>
          <value>180</value>
          <value>270</value>
        </choice>
      </attribute>
    </optional>
  </define>

  <define name="SVG.page.content">
    <zeroOrMore>
      <ref name="SVG.Description.class"/>
    </zeroOrMore>
    <zeroOrMore>
      <choice>
        <ref name="SVG.Structure.class"/>
        <ref name="SVG.Description.class"/>
        <ref name="SVG.Animation.class"/>
        <ref name="SVG.Handler.class"/>
        <ref name="SVG.Structure.class"/>
        <ref name="SVG.Conditional.class"/>
        <ref name="SVG.Image.class"/>
        <ref name="SVG.MultiImage.class"/>
        <ref name="SVG.Audio.class"/>
        <ref name="SVG.Video.class"/>
        <ref name="SVG.Shape.class"/>
        <ref name="SVG.Text.class"/>
        <ref name="SVG.FlowText.class"/>
        <ref name="SVG.Hyperlink.class"/>
        <ref name="SVG.View.class"/>
        <ref name="SVG.Script.class"/>
        <ref name="SVG.XMLEvents.class"/>
      </choice>
    </zeroOrMore>
  </define>

The page-orientation attribute is described below.

Conceptually, the page element is similar to an svg element but without transformation and positioning. All pages are in the coordinate system of their pageSet, which is in the coordinate system of the root svg element.

The page element has the time container behavior of the SMIL "par" element. The page element, like par, supports all SMIL timing attibutes. Since the pageSet element is equivalent to a SMIL seq, a page element cannot have negative offset values for begin. The dissallowed begin values are listed in the specification of the "seq" element.

5.5 The page-orientation property

When printing an SVG file, the definition of most printing properties, such as paper size, printer tray and double-sided, is controlled by the system (commonly called the job ticket) and is not part of the SVG content. There are two printing properties that can be defined by the SVG content itself, in both cases to assist in on-screen display.

The SVG content typically defines a page dimension or aspect ratio in the topmost svg element and its viewBox. The viewBox transformation applies to printed SVG in the same way as screen display.

The orientation of each page element can be controlled by the page-orientation property. This enables the content to define whether a portrait or landscape mode is used for display and printing.

page-orientation
Value: -270 | -180 | -90 | 0 | 90 | 180 | 270
Initial: 0
Applies to: page elements
Inherited: no
Percentages: N/A
Media: visual print
Animatable: yes

When displaying a page on screen the value of the page-orientation property introduces the following transform before the top-level viewport transformation:

0
No additional transform
-90 or 270
translate(0 height) rotate(-90)
180 or -180
translate(width height) rotate(180)
90 or -270
translate(width 0) rotate(90)

The values for width and height are the dimensions of the top-level viewBox in the user coordinate system or the dimensions of the top-level viewport if there is no viewBox specified.

This transformation is only applied when displaying on the screen in a manner that expects the orientation of the page to be convenient to the user. For example, a print preview dialog would not apply this transformation.

Below is an example of the page-orientation property:

<svg width="8.5in" height="11in" viewBox="0 0 612 792">
  <rect x="36" y="36" width="540" height="720" 
        fill="yellow" stroke-width="15" stroke="black"/>
  <pageSet>
     <page>
        <text font-size="30" x="72" y="108">This is portrait</text>
     </page>
     <page page-orientation="90">
        <text font-size="30" x="72" y="108">This is landscape</text>
     </page>
   </pageSet>
</svg>

The above example is equivalent to the following two pages when printed:

<svg width="8.5in" height="11in" viewBox="0 0 612 792">
  <rect x="36" y="36" width="540" height="720" 
        fill="yellow" stroke-width="15" stroke="black"/>
  <text font-size="30" x="72" y="108">This is portrait</text>
</svg>

<svg width="8.5in" height="11in" viewBox="0 0 612 792">
  <rect x="36" y="36" width="540" height="720" 
        fill="yellow" stroke-width="15" stroke="black"/>
  <text transform="translate(612 0) rotate(90)" 
        font-size="30" x="72" y="108">This is portrait</text>
</svg>

And equivalent to the following two pages when viewed:

<svg width="8.5in" height="11in" viewBox="0 0 612 792">
  <rect x="36" y="36" width="540" height="720" 
        fill="yellow" stroke-width="15" stroke="black"/>
  <text font-size="30" x="72" y="108">This is portrait</text>
</svg>

<svg width="11in" height="8.5in" viewBox="0 0 792 612"> 
    <!-- fake top-level transform -->
  <g transform="translate(0 612) rotate(-90)">
    <rect x="36" y="36" width="540" height="720" 
          fill="yellow" stroke-width="15" stroke="black"/>
    <text transform="translate(612 0) rotate(90)" 
          font-size="30" x="72" y="108">This is portrait</text>
  </g>
</svg>

In the printing environment, the printing system can override the value of this property. For example, the user may wish to print all pages in portrait mode.

Since pageSet and page are equivalent to the SMIL seq and par elements, the "current page" is determined by the current time of the document. The syncbase of the first page is that of the pageSet element. For subsequent pages the implicit syncbase of a page is its previous page sibling. Therefore each page will play after the previous page has finished. Hyperlinking to a page will seek the document to the begin time of that page.

It is also suggested that user agents bind input methods, such as the PageUp and PageDown keys if available, to page navigation. These should act the same way as hyperlinking, i.e. the document will seek to the begin time of that page. In a view without animation, such as print preview, the view will use the begin times of each page.

The begin and end of pageSet / page will raise a "begin" event and "end" event respectively. Repeating of a page / pagSet using the repeat attribute will raise a "repeat" event.

The SMIL timing attributes begin, end and dur are one simple way to control the duration of each page. Please see the SMIL specification for an explanation of all valid attributes and their use. In this first example each page has a simple duration. Thus the navigation between pages is fixed and will advance to the next page at the completion of the previous page's duration. The first page will have a duration from 0 to 30 seconds, the next page from 30 seconds to 90 seconds, the third page from 90 seconds to 120 seconds, etc.

<svg>
   <pageSeq begin="0s">
      <page id="page1" dur="30s">
         ...
      </page>

      <page id="page2" dur="60s">
         ...
      </page>

      <page id="page3" dur="30s">
         ...
      </page>

      <page id="page4" dur="90s">
         ...
      </page>

   </pageSeq>
</svg>

The begin and end attributes, and hence the active duration of pages, can be defined by events, see the SMIL timing attributes and the event value syntax.

All events supported in SVG can be used on SMIL timing attributes that support event values

In this next example, the pages are flipped by clicking on the presentation. The end of the active interval is resolved when the event happens. The begin time is resolved using the implicit syncbase which is the previous page. Each page will begin 0 seconds after the end of the previous page elements duration.

<svg>
   <pageSeq begin="0s">
      <page id="page1" begin="0s" end="page1.click">
         ...
      </page>

      <page id="page2" begin="0s" end="page2.click">
         ...
      </page>

      <page id="page3" begin="0s" end="page3.click">
         ...
      </page>

      <page id="page4" begin="0s" end="page4.click">
         ...
      </page>

   </pageSeq>
</svg>

Once this example has been played and the begin and end times resolved, seeking to a page will not reset these values. The element state will reset when the parent time container repeats or restarts.