================================
Pages Numbers
================================
Putting numbers in pages is often a requirement, but honestly we have never liked the CSS approach.
.. figure:: ../images/samples_pagenumberFor.png
:alt: Page numbers for another component.
:width: 600px
:class: with-shadow
At scryber we have taken a slightly more declarative approach with the 'page' tag. Browsers do not understand this tag, and will ignore it.
The scryber engine will understand and output the current page number
.. code:: html
The page number component classes are ``PageNumberLabel`` and ``PageOfLabel`` in the
``Scryber.Components`` namespace.
.. code:: csharp
//using Scryber.Components
var pgNum = new PageNumberLabel(){ DisplayFormat = "{0} of {1}" };
var pgOf = new PageOfLabel() { ComponentName = "#id", NotFoundText = "Oops!" };
Generation methods
-------------------
All methods and files in these samples use the standard testing set up as outlined in :doc:`../overview/samples_reference`
Current Page Numbers
---------------------
The tag can be placed anywhere within the text of a document, and will render in the current style. Although it does also support the
inline style options from as with any other span.
.. code-block:: html
My Document
This is the content on page
.. code:: csharp
public void CurrentPageNumber()
{
var path = GetTemplatePath("PageNumbers", "PageNumbersCurrent.html");
using (var doc = Document.ParseDocument(path))
{
using (var stream = GetOutputStream("Links", "PageNumbersCurrent.pdf"))
{
doc.SaveAsPDF(stream);
}
}
}
.. figure:: ../images/samples_pagenumberCurrent.png
:target: ../_images/samples_pagenumberCurrent.png
:alt: Simple Pages.
:width: 600px
:class: with-shadow
`Full size version <../_images/samples_pagenumberCurrent.png>`_
Total number of pages
---------------------
The page tag also supports the property attribute for displaying the 'total' number of pages.
.. code-block:: html
My Document
This is the content on page of
This is the content on page of
This is the content on page of
This is the content on page of
.. code:: csharp
public void TotalPageNumbers()
{
var path = GetTemplatePath("PageNumbers", "PageNumberTotal.html");
using (var doc = Document.ParseDocument(path))
{
using (var stream = GetOutputStream("PageNumbers", "PageNumberTotal.pdf"))
{
doc.SaveAsPDF(stream);
}
}
}
.. figure:: ../images/samples_pagenumberTotal.png
:target: ../_images/samples_pagenumberTotal.png
:alt: Total Page numbers.
:width: 600px
:class: with-shadow
`Full size version <../_images/samples_pagenumberTotal.png>`_
The page *for* another component
------------------------------
Conversly to the current page number, it is also possible to get the page number of another element.
By using the ``for`` attribute.
The example below is a table of contents with links to sections based on their
ID and a line leading to the page numbers on the right cell.
.. note:: The for referenced component can be following the current content, and not yet laid out. It is only once everything is laid out would the page numbers for another component be evaluated.
.. code-block:: html
My Document
Table of Contents
This is the content on page of
This is the content on page of
This is the content on page of
.. code:: csharp
public void ForComponentPageNumbers()
{
var path = GetTemplatePath("PageNumbers", "PageNumbersFor.html");
using (var doc = Document.ParseDocument(path))
{
using (var stream = GetOutputStream("PageNumbers", "PageNumbersFor.pdf"))
{
doc.SaveAsPDF(stream);
}
}
}
Is is also possible to use also databinding to achieve this (see :doc:`links_reference` in the next section for an example of this).
.. figure:: ../images/samples_pagenumberFor.png
:target: ../_images/samples_pagenumberFor.png
:alt: Page numbers for another component.
:width: 600px
:class: with-shadow
`Full size version <../_images/samples_pagenumberFor.png>`_
.. note:: The page index of a component can be forward as in this case, as well as backward looking,
but will always be the very first page the component is laid out at, even if it overflows onto another page.
Page Numbers in code
---------------------
The use of the ``PageNumberLabel`` and ``PageOfLabel`` in coded documents is just the same as in templates.
Creating a five page document with headings on each and a reference to each of the the headings on the first page.
The spans are added as individual blocks, showing the page numbers of following headings.
.. code:: csharp
public void CodedPageNumbers()
{
using (var doc = new Document())
{
for(var i = 0; i < 5; i++)
{
var pg = new Page();
var head = new Head1() { ID = "Item" + i };
var lit = new TextLiteral() { Text = "This is the heading index " + i + " on page " };
var num = new PageNumberLabel() { DisplayFormat = "{0} of {1}" };
pg.Style.Margins.All = 20;
doc.Pages.Add(pg);
pg.Contents.Add(head);
head.Contents.Add(lit);
head.Contents.Add(num);
if(i == 0) //First page add links to components on the nex
{
var div = new Div();
div.Style.Margins.All = 20;
div.Style.Border.Color = PDFColors.Black;
pg.Contents.Add(div);
for (int j = 0; j < 5; j++)
{
var span = new Span() { PositionMode = PositionMode.Block, Padding = new PDFThickness(4) };
span.Contents.Add(new TextLiteral("The page number of index " + j + " is "));
span.Contents.Add(new PageOfLabel() { ComponentName = "#Item" + j });
div.Contents.Add(span);
}
}
}
using (var stream = GetOutputStream("PageNumbers", "PageNumbersCoded.pdf"))
{
doc.SaveAsPDF(stream);
}
}
}
.. figure:: ../images/samples_pagenumberCoded.png
:target: ../_images/samples_pagenumberCoded.png
:alt: Page numbers in code.
:width: 600px
:class: with-shadow
`Full size version <../_images/samples_pagenumberCoded.png>`_
Page number spacing
-------------------
Because the page numbers are calculated at the end of the layout, the spacing needed for the total number of pages (or the page number of a following component)
is deferred to the end of the layout. Before then a proxy value is used.
By default this is '99', so enough space will be left for the number '99' to be rendered in the content. For smaller numbers, very long documents, or very large font sizes
this may alter the layout too much and potentially casue character clashes.
The ```` element supports the `data-page-hint` attribute.
And the ``PageNumberLabel`` and ``PageOfLabel`` support the `TotalPageCountHint` properties that can be set to an integer value where clashes need to be fixed.
.. code:: html
.. code:: csharp
var pglbl = new PageOfLabel() { ComponentName = "#VeryLastComponent", TotalPageCountHint = 9999 };