Context Fields

Context fields are specially formatted pieces of text that are substituted during rendering.

For example, you may assign "See #l #0 on page #p" to the text property of a fragment.

(#l, #0 and #p are the fields.) If the fragment has its GoToAction or Reference pointing to a table that has its Label property set to "Table" and is rendered on page 6, then the fragment appears in PDF as "See Table 3 on page 6".

The following sub-sections discuss the different cases in which context fields can be used.

Label and Caption Properties

The Label property of a Paragraph reflects the nature of the content. Typical examples are “Table” and “Code Sample”. The Caption property is normally a single line summarizing the content of the Paragraph. For example, if a table shows the telephone region numbers of say Spain, then a typical Caption would be “Telephone region numbers of Spain”. In TallPDF.NET you can set these properties so that you can include this text through a reference field in e.g. a cross references or a ‘List of Tables’ without duplicating these values.

The following code shows how to add an image and set its Caption and Label properties.

Image image = new Image( "c:\images\portraits\vincentvangogh.jpg" );
image.Label = "Figure";
image.Caption = "Self-portrait of Vincent van Gogh";
image.Width = section.PageSize.Width * 0.8;
image.HorizontalAlignment = HorizontalAlignment.Center;
image.KeepWithNext = true;
section.Paragraphs.Add( image );

Code sample: Add an image with a label and caption in C#

Next, you want to add a line below this image that is formatted like: “Figure 3. Self-portrait of Vincent van Gogh”. Without duplication the caption or the label values, you would use the following code:

TextParagraph text = new TextParagraph();
Fragment fragment = new Fragment("#l #0. #c");
Fragment.Reference = image;
text.Fragments.Add(fragment);
section.Paragraphs.Add(text);

Code sample: Add a text line below an image that uses context fields for formatting

Bookmark Property of Heading

The Bookmark property of class Heading is of type string and specifies the format of the heading as respresented in the bookmark/outline tree of the PDF reader application.

The following table shows the different reference fields you may use and how they are interpreted.

Context fields for the Heading.Bookmark property

Heading heading = new Heading(0); // level 0
heading.SpacingBefore = 8;
heading.SpacingAfter = 4;
heading.Label = "Chapter";
heading.Caption = "Conceptual Overview";
heading.Fragments.Add(new Fragment("#l #0 - #c", Font.HelveticaBold, 16));
heading.Bookmark = "#0. #c";
section.Paragraphs.Add(heading);

Code sample: Add a heading and format the bookmark

The following table shows some specific samples.

Heading.Bookmark samples

Fragment with HasContextFields

This case applies to the fields in the Text property of a Fragment object that has its HasContextFields property set and has its Reference field set to null.

Context fields for fragments that do not refer to a paragrap

Fragment that Refers to a Heading

This case applies to the Text property of a Fragment of which either the Reference property or the GoToAction points to a Heading.

Context fields for fragments that refer to a heading

Context field samples for fragments that refer to a heading.

Fragment that Refers to a Paragraph

This case applies to the Text property of a Fragment that has a GoToAction or Reference that points to another paragraph such as a Table or Image. Note that in that case you always specify 0 as the level since paragraphs other than Heading paragraphs do not have a level.

Context fields for fragments that refer to a paragraph

Context field samples for fragments that refer to a heading.

Fragment as Part of a Heading

This case applies to the Text property of a Fragment that is part of a Heading. These fragments are treated as if they have a Reference that points to the enclosing Heading paragraph. See the Section Fragment that Refers to a Heading.

CrossreferenceSection

The CrossreferenceSection lets you generate sections such as a ‘Table of Contents’, a ‘List of Tables’ or a ‘List of Figures’. The CrossreferenceSection was already introduced shortly in Sections. Because it relies heavily on the concepts introduced in this Chapter, we will discuss it in more detail now.

The mechanism of the CrossreferenceSection is based on the ComposeEntry event. This event is fired for each paragraph in the document. The event handler decides whether and how an entry has to be added to the CrossreferenceSection. E.g. if you want to generate a table of contents, then you would ignore all paragraphs that are not of type Heading.

The following code sample shows how to generate a simple table of contents.

CrossreferenceSection toc = new CrossreferenceSection();
toc.ComposeEntry += new ComposeEntryEventHandler( renderTocEntry );
doc.Sections.Add( toc );

Code sample: Add a CrossreferenceSection to a document in C#

The code below references the event handler renderTocEntry. Its implementation is shown in the next code sample:

static void renderTocEntry(
   CrossreferenceSection section, ComposeEntryEventArgs args )
{
   // check to see if the paragraph is a heading – if not, ignore
   Heading heading = args.CurrentParagraph as Heading;
   if ( !( args.CurrentParagraph is Heading ) ) return;

   // only includes level 0 and level 1 entries
   int level = heading.Level;
   if ( level > 1 ) return;

   // add an entry for this heading
   TextParagraph text = new TextParagraph();
   section.Paragraphs.Add( text );

   // the entry is a clickable link to the heading
   Fragment fragment = new Fragment();
   fragment.Actions.Add( new GoToAction( args.CurrentParagraph ) );
   text.Fragments.Add( fragment );

   // the content of the entry is formatted using context fields
   switch (level)
   {
      case 0:
         fragment.Text = "#0 #c - #p";
         fragment.FontSize = 12;
         break;
      case 1:
         fragment.Text = "#0.#1 #c - #p";
         fragment.FontSize = 10;
         break;
   }
}

Code sample: Handle the CrossreferenceSection.ComposeEntry event in C#