Working With Text Objects in Pages Documents
This chapter works through a series of examples in Pages documents, describing how text objects in each example are stored and laid out in XML. Understanding how Pages documents store and lay out text is important if you want to customize and design your own page layouts, or modify the existing XML of your documents.
How Pages Stores and Lays Out Various Text Objects
The chapter discusses the following group of examples used in Pages documents to lay out various text objects:
“Main Body Text Objects With Character Styles” examines a page layout comprised of main body text, along with a bolded character style in its second paragraph, and a tab.
“Lists Text Object” discusses the elements and attributes of a list of text items in a hierarchical outline view.
“Multiple Column Text Objects” discusses a page layout that is comprised of multiple columns.
“Text Objects With Date-Time Fields and Hyperlinks” discusses how you can work with a page layout comprised of a date-time field, page numbers, bookmarks, and hypertext links.
“A Footnote Text Object” looks at a text object with two footnotes and their corresponding superscripts.
“A Text Object With an Image and a Drawable Attachment” explains how you can work with a text object with an image and a drawable attachment.
The examples are intended to illustrate how Pages documents store text objects in XML and how they are laid out.
Main Body Text Objects With Character Styles
“Figure 4-1” illustrates the output for a Pages text storage object with a page layout comprised of a main body text and a bolded character style in a second paragraph, followed by a tab. “Listing 4-1” describes the XML for this text storage object.
Listing 3-1 The XML for the main body text and a second paragraph with a bolded character style
<sf:text-storage sf:kind="body" sfa:ID="SFWPStorage-8"> |
<sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/> |
<sf:text-body> |
<sf:section sf:name="Chapter 1" sf:style="section-style-0"> |
<sf:layout sf:style="layout-style-20"> |
<sf:p sf:style="paragraph-style-32">Main body text.<sf:br/></sf:p> |
<sf:p sf:style="SFWPParagraphStyle-44">Second paragraph with a |
<sf:span sf:style="SFWPCharacterStyle-5">character</sf:span> style and a<sf:tab/>tab.<sf:br/></sf:p> |
<sf:p sf:style="paragraph-style-32"> |
<sf:br/> |
</sf:p> |
</sf:layout> |
</sf:section> |
</sf:text-body> |
</sf:text-storage> |
Defining Characteristics
The <sf:text-storage> element has one required attribute other than the sfa:ID attribute: the sf:kind, which indicates the usage of the text. The value must be one of "body", "header", "footnote", "textbox", "note", or "cell". The text storage sf:kind attribute must have a value corresponding to its use in the document. For example, the text storage used for a header must have a sf:kind="header" in order to avoid undefined or unpredictable types of behavior.
A <sf:text-storage> element must have a <sf:stylesheet-ref> child element that refers to the document or prototype stylesheet and may have a child <sf:attachment> element. Body text storages can also have a <sf:footnotes> child element.
A <sf:text-storage> element must have a <sf:text-body> child element. The next immediate child of the <sf:text-storage> element depends on the text storage kind.
The child elements of a <sf:text-storage> with an sf:kind of "body" must follow the strict hierarchy of <sf:section> elements, containing <sf:layout> elements that contain <sf:p> elements, which indicate the section, layout style, and paragraph style, respectively, of the contained mixed content.
The child elements of a <sf:text-storage> with an sf:kind of "textbox", "cell" , or "note" must follow the strict hierarchy of <sf:layout> elements containing <sf:p> elements, which indicate the layout style, and paragraph style, respectively, of the contained mixed content.
The child elements of a <sf:text-storage> with an sf:kind of "header" or "footnote" elements contain <sf:p> elements, which indicate the paragraph style of the contained mixed content.
Note: The <sf:p> element does not itself indicate the break character which ends the paragraph and must be included immediately prior to the close of the paragraph element (except on the last paragraph of the text storage).
Style runs at the sub-paragraph level are enclosed in <sf:span> elements, and reference character styles. Note that spans are used only for sub-paragraph style runs and define only the variations from the enclosing paragraph style. Any style that applies to all of the text in a paragraph should be defined by the paragraph style. Note that <sf:span> elements do not nest.
The standard paragraph break is indicated by a <sf:br/> element. Other paragraph breaking elements are <sf:pgbr/> for page breaks, <sf:sectbrbr/> for section breaks, <sf:layoutbr/> for layout breaks, <sf:contbr/> for container breaks, and <sf:footnotebr/> for footnote breaks.
Style References
All styles in an iWork document have up to three attributes that can be used to identify the style. Like many other elements, all style elements have an sfa:ID attribute with a unique string as a value. Many style elements also have an sf:ident attribute with a value that is unique for all style elements of that type. Some style elements also have an sf:name attribute with a user-visible string as the value.
Text styles are referred to elsewhere in the document by a sf:style attribute the value of which is either the style’s sf:ident, or its sfa:ID.
The <sf:section> element must have an <sf:name> attribute (which is not exposed to the user), and an sf:style attribute referencing a section style.
The <sf:layout> and <sf:p> elements reference layout and paragraph styles, respectively.
Lists Text Object
“Figure 4-2” illustrates the output for a Pages text object with a page layout comprised of a list of items in an outline view. “Listing 4-2” describes the XML for text in outline form.
Listing 3-2 The XML for an item list in outline form
<sf:text-storage sf:kind="body" sfa:ID="SFWPStorage-8"> |
<sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/> |
<sf:text-body> |
<sf:section sf:name="Chapter 1" sf:style="section-style-0"> |
<sf:layout sf:style="layout-style-20"> |
<sf:p sf:style="paragraph-style-32">List of items:<sf:br/></sf:p> |
<sf:p sf:style="SFWPParagraphStyle-45" sf:restart-list="true">First<sf:br/></sf:p> |
<sf:p sf:style="SFWPParagraphStyle-45" sf:list-level="1">Sublevel 1<sf:br/></sf:p> |
<sf:p sf:style="SFWPParagraphStyle-45" sf:list-level="2">Sublevel 2<sf:br/></sf:p> |
<sf:p sf:style="SFWPParagraphStyle-46">Second<sf:br/></sf:p> |
<sf:p sf:style="SFWPParagraphStyle-43">Third<sf:br/></sf:p> |
<sf:p sf:style="paragraph-style-32"> |
<sf:sectbr/> |
</sf:p> |
</sf:layout> |
</sf:section> |
</sf:text-body> |
</sf:text-storage> |
Defining Characteristics
The fact that a paragraph is an element in a list is indicated by an sf:list-level attribute with an integer value in the range of "1" to "9" on the <sf:p> element. An sf:restart-list attribute with a value of "true" indicates that the paragraph begins a new sequence at this level rather than continuing a previous one.
The appearance of the list element––that is, bullets, indentation, and so on––is found in the paragraph style.
Multiple Column Text Objects
“Figure 4-3” illustrates a Pages text object with a page layout comprised of multiple columns. In this case, the text flows and wraps over all three columns. “Listing 4-3” describes the XML for text in multiple columns.
Listing 3-3 The XML for a multiple column page layout
<sf:text-storage sf:kind="body" sfa:ID="SFWPStorage-8"> |
<sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/> |
<sf:text-body> |
<sf:section sf:name="Chapter 2" sf:style="section-style-22"> |
<sf:layout sf:style="layout-style-35"> |
<sf:p sf:style="paragraph-style-32">Text in the second section.<sf:layoutbr/></sf:p> |
</sf:layout> |
<sf:layout sf:style="SFWPLayoutStyle-13"> |
<sf:p sf:style="paragraph-style-32">New layout with multiple columns. New layout with multiple columns. New layout with multiple columns. New layout with multiple columns. New layout with multiple columns. New layout with multiple columns. New layout with multiple columns. <sf:layoutbr/> |
</sf:p> |
</sf:layout> |
<sf:layout sf:style="layout-style-36"> |
<sf:p sf:style="paragraph-style-32"> |
<sf:br/> |
</sf:p> |
</sf:layout> |
</sf:section> |
</sf:text-body> |
</sf:text-storage> |
Defining Characteristics
The <sf:layout> element indicates the layout style for the multiple column text view that is generated in “Figure 4-3.” Note that the column count is a property of the layout style.
The sf:style attribute specifies the paragraph style, which includes the “New layout with multiple columns” text, followed by a sf:layoutbr break attribute.
The <sf:layoutbr> element is the most notable item of interest in this XML example. The last paragraph in a layout is terminated by an <sf:layoutbr> instead of a paragraph break.
Text Objects With Date-Time Fields and Hyperlinks
“Figure 4-4” illustrates the output for a Pages text object with a page layout comprised of a date-time field, along with page numbers, bookmarks, and hypertext links. “Listing 4-4” describes the XML for this text-storage object.
Figure 3-4 Example output for a text object with date-time fields, page numbers, bookmarks, and hypertext links
Listing 3-4 The XML for date-time fields, page numbers, bookmarks, and hypertext links
<sf:text-storage sf:kind="body" sfa:ID="SFWPStorage-8"> |
<sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/> |
<sf:text-body> |
<sf:section sf:name="Chapter 2" sf:style="section-style-22"> |
<sf:layout sf:style="layout-style-36"> |
<sf:p sf:style="paragraph-style-32">Some fields and attachments: |
<sf:date-time sf:format="MMMM d, yyyy h:mm a" sf:locale="en_US" |
sf:date-style="long" sf:time-style="short" |
sf:auto-update="true">April 19, 2005 11:46 PM</sf:date-time> page number: |
<sf:page-number sf:value="2"/> of: |
<sf:page-count sf:value="2"/>. |
<sf:br/> |
</sf:p> |
<sf:p sf:style="paragraph-style-32"> |
<sf:br/> |
</sf:p> |
<sf:p sf:style="paragraph-style-32">Text in a |
<sf:bookmark sf:name="bookmark" sf:ranged="true" sf:page="2" sfa:ID="SFWPBookmarkField-0"> |
book<sf:br/></sf:bookmark> |
</sf:p> |
<sf:p sf:style="paragraph-style-32"><sf:bookmark-ref sfa:IDREF="SFWPBookmarkField-0">mark |
</sf:bookmark-ref>, and a <sf:link href="http://web.apple.com"><sf:span sf:style="SFWPCharacterStyle-6"> |
hyperlink</sf:span></sf:link>.<sf:br/></sf:p> |
</sf:layout> |
</sf:section> |
</sf:text-body> |
</sf:text-storage> |
Defining Characteristics
This section discusses the defining characteristics of the various fields of this text object, including bookmark, placeholder text, hyperlink, date-time, and page number and page count.
Bookmark Fields
A bookmark field is defined by a <sf:bookmark> element with no attributes other than an optional sfa:ID, which only needs to be defined if the bookmark crosses a paragraph boundary, in which case the continuation is indicated by a <sf:bookmark-ref> element with an sfa:IDREF attribute with a value corresponding to the value of the sfa:ID of the <sf:bookmark> element that is being continued.
Placeholder Text Fields
A placeholder text field is defined by a <sf:ghost-text> element with no attributes other than an optional sfa:ID, which only needs to be defined if the placeholder text crosses a paragraph boundary, in which case the continuation is indicated by a <sf:ghost-text-ref> element with an sfa:IDREF attribute with a value corresponding to the value of the sfa:ID of the <sf:ghost-text> element which is being continued. A placeholder text field should contain textual content only.
Hyperlink Fields
A hyperlink field is defined by a <sf:link> element with a single attribute. A hyperlink field must not cross a paragraph boundary, and cannot contain graphical attachments, date-time fields, placeholder text, or other hyperlink fields. It may contain <sf:span> elements.
The href attribute defines either a standard web (http:) or mail (mailto:) URL, or a bookmark name prefix by ‘#’.
Date-Time Fields
A date-time field is defined by a <sf:date-time> element with five possible attributes, and no child elements. The content of the field is text only, and is the resulting formatted text seen in the document.
The sf:format attribute defines the format of the date or time text. The syntax of this string is defined by the ICU library http://icu.sourceforge.net/userguide/formatDateTime.html. (Only a small selection of possible formats are exposed in the UI.)
The sf:locale attribute specifies the locale used to format the date time string. The possible values are those defined by CFLocale.
The optional sf:date-style and sf:time-style attributes define the style indicated by the format in the sf:format attribute. The possible values are "short", "medium", "long", and "full" , which correspond to CFDateFormatterStyle values. These attributes are defined only if together they result in the format specifed by the value of the sf:format attribute; otherwise, they are omitted.
If the sf:auto-update attribute has a value of "true", then the field is auto-updating.
Page Number and Page Count Fields
A page number field is defined by a <sf:page-number> element with a single attribute and no content.
A page count field is defined by a <sf:page-count> element with a single attribute and no content.
The value of the sf:value attribute of page number and page count fields is an integer corresponding to the most recent value represented by the field, and is recomputed whenever the text containing the field is laid out.
A Footnote Text Object
“Figure 4-5” illustrates the output for a Pages text object with two footnotes and their footnote references (the superscripted numbers in the body text). “Listing 4-5” describes the XML for this text-storage object.
Listing 3-5 The XML for a footnotes text object
<sf:text-storage sf:kind="body" sfa:ID="SFWPStorage-8"> |
<sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/> |
<sf:footnotes> |
<sf:text-storage sfa:ID="SFWPStorage-7" sf:kind="footnote"> |
<sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/> |
<sf:attachments/> |
<sf:text-body> |
<sf:p sf:style="kSFWPFootnoteTextStyleIdentifier"><sf:span sf:style="SFWPCharacterStyle-4"> |
<sf:footnote-mark sf:mark="1"/></sf:span> First footnote<sf:footnotebr/></sf:p> |
<sf:p sf:style="kSFWPFootnoteTextStyleIdentifier"><sf:span sf:style="SFWPCharacterStyle-4"> |
<sf:footnote-mark sf:mark="2"/></sf:span> This is the footnote text.<sf:footnotebr/></sf:p> |
<sf:p sf:style="paragraph-style-default"/> |
</sf:text-body> |
</sf:text-storage> |
</sf:footnotes> |
<sf:text-body> |
<sf:section sf:name="Chapter 2" sf:style="section-style-22"> |
<sf:layout sf:style="layout-style-36"> |
<sf:p sf:style="paragraph-style-32">Footnotes<sf:span sf:style="SFWPCharacterStyle-4"> |
<sf:footnote sf:index="0" sf:autonumber="1"/></sf:span>, too<sf:span sf:style="SFWPCharacterStyle-4"> |
<sf:footnote sf:index="0" sf:autonumber="2"/></sf:span><sf:br/></sf:p> |
<sf:p sf:style="paragraph-style-32"> |
<sf:br/> |
</sf:p> |
</sf:layout> |
</sf:section> |
</sf:text-body> |
</sf:text-storage> |
Defining Characteristics
This section discusses the defining characteristics of the various fields of this text object, including footnotes and footnote references.
Footnotes
The <sf:footnotes> element defines a single <sf:text-storage> element that must have a sf:kind value of "footnote".
Within the footnote storage, individual footnotes are separated by <sf:footnotebr> elements.
The footnote numbers are indicated by optional <sf:footnote-mark> elements with a single attribute. The value of the sf:mark attribute defines the number given to the footnote.
Footnote References
The footnote references are defined in the body text as <sf:footnote/> elements with two attributes and no content.
The value of the sf:index attribute defines a valid index into the text of the <sf:footnotes> element. (Zero for the first footnote and so on.)
If the value of the sf:autonumber attribute is "YES", then the sf:mark attribute on the corresponding <sf:footnote-mark> is renumbered as footnotes are added and removed.
A Text Object With an Image and a Drawable Attachment
“Figure 4-6” illustrates a Pages text object with an image attachment and a drawable attachment. “Listing 4-6” describes the XML for this text-storage object.
Listing 3-6 The XML for a text storage object with an image and a drawable attachment
<sf:text-storage sf:kind="body" sfa:ID="SFWPStorage-8"> |
<sf:stylesheet-ref sfa:IDREF="SFSStylesheet-1"/> |
<sf:attachments> |
<sf:attachment sfa:ID="SLDrawableAttachment-0" sfa:sfclass="" sf:kind="drawable-attachment"> |
<sf:line sfa:ID="SFDLineInfo-0"> |
</sf:line> |
</sf:attachment> |
<sf:attachment sfa:ID="SLDrawableAttachment-1" sfa:sfclass="" sf:kind="drawable-attachment"> |
<sf:image sfa:ID="SFDImageInfo-0"> |
</sf:image> |
</sf:attachment> |
</sf:attachments> |
<sf:text-body> |
<sf:section sf:name="Chapter 2" sf:style="section-style-22"> |
<sf:layout sf:style="layout-style-36"> |
<sf:p sf:style="paragraph-style-32"> |
<sf:attachment-ref sfa:IDREF="SLDrawableAttachment-0" sf:kind="drawable-attachment"/> |
<sf:attachment-ref sfa:IDREF="SLDrawableAttachment-1" sf:kind="drawable-attachment"/> |
</sf:p> |
</sf:layout> |
</sf:section> |
</sf:text-body> |
</sf:text-storage> |
Defining Characteristics
This section discusses the defining characteristics of the various fields of this text object, including attachments and attachment references.
Attachments
The <sf:attachments> element defines a sequence of <sf:attachment> elements, each of which defines a single attachment appearing in the following <sf:text-body> element.
The <sf:attachment> element has two attributes (in addition to an sfa:ID attribute) and has a child element that is either a <sf:line>, <sf:drawable-shape>, or <sf:image>.
The sfa:class attribute must always have a value of "".
The sf:kind attribute has a value of "drawable-attachment" if the child element is an <sf:line>, <sf:drawable-shape>, or <sf:image>.
Attachment References
Within the text body, attachment points are defined by <sf:attachment-ref> elements with one attribute, in addition to the sfa:IDREF attribute that references the attachment in the <sf:attachments> element.
The sf:kind attribute must have the same value as the sf:kind attribute on the referenced attachment.
Last updated: 2005-11-09
  |
||
|
|
|
|
| ||
Get information on Apple products.
Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice |