Background Color:
 
Background Pattern:
Reset
Search
Home Recent Changes Show All Pages

References and Component Re-use

Not Rated Yet

You would never build a web site in a single page, it is always good practice to put your styles in a separate css file. In the same way, scryber supports easily splitting up content into discreet and reusable files, that you can reference from your document and even other referenced files.

 

Article Contents

 

Extension convention and paths

 

When working with scryber and multi-file documents it helps to stick to the standard extensions.

*.pdfx
This is a top level document. Contains styles and pages, and also references to style files etc.
*.ppfx
This is a single page, section or page group. Contains one or more pages that can be referenced from a document.
*.psfx
This is a stylesheet - contains one or more style definitions. It can be referenced from a document or another stylesheet.
*.pcfx
This is a page content component. Contains visual elements that will be rendered on the page(s) that references this component.
Scryber does not enforce these extensions, and ultimately they are just simply xml data - however it helps to identify specific types of items, and for web-projects the scryber Nuget Package blocks the download of non-document known file types with web.config.

 

When referencing other files, the path is always taken relative from the current file (even if it is not the top level document). If there is no base location, when building from code for example, then the path will be relative to either the current executing application, or virtual directory of the web application.

It is always an error if there is a reference to a file and it does not exist of cannot be read.

 

Referencing a stylesheet

 

One of the most common references to be made will be to an external stylesheet. If we have a couple of documents in our project, then they can both share the common styles in an external stylesheet.

Let's create 3 files - 2 documents and a shared stylesheet.

 

SalesReport.pdfx

<?xml version="1.0" encoding="utf-8" ?>
<pdf:Document xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">
  <Styles>
    <style:Styles-Ref source="./Stylesheets/Common.psfx" />
  </Styles>
  <Pages>
    <pdf:Page>
      <Content>
        <pdf:H1 style:class="report-title">Sales report</pdf:H1>
        <pdf:H2 style:class="report-company">Contoso Incorporated</pdf:H2>
        <pdf:H4 style:class="report-date"><pdf:Date /></pdf:H4>
      </Content>
    </pdf:Page>

    <!-- Content for the sales report -->

  </Pages>
</pdf:Document>

 

BudgetReport.pdfx

<?xml version="1.0" encoding="utf-8" ?>
<pdf:Document xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">
  <Styles>
    <style:Styles-Ref source="./Stylesheets/Common.psfx" />
  </Styles>
  <Pages>
    <pdf:Page>
      <Content>
        <pdf:H1 style:class="report-title">Budget report</pdf:H1>
        <pdf:H2 style:class="report-company">Contoso Incorporated</pdf:H2>
        <pdf:H4 style:class="report-date"><pdf:Date /></pdf:H4>
      </Content>
    </pdf:Page>

    <!-- Content for the budget report -->
  </Pages>
</pdf:Document>

 

Common.psfx

<?xml version="1.0" encoding="utf-8" ?>
<style:Styles xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">

  <!-- Page style -->
  <style:Style applied-type="pdf:Page" >
    <style:Page size="A4"/>
    <style:Margins all="0pt"/>
  </style:Style>


  <!-- Report Title-->
  <style:Style applied-class="report-title" applied-type="pdf:H1" >
    <style:Background color="#CCCCCC"/>
    <style:Margins top="100pt"/>
    <style:Padding all="10pt"/>
    <style:Position full-width="true"/>
    <style:Font family="Helvetica" size="36" bold="true" italic="false" />
  </style:Style>

  <!-- Report Company -->
  <style:Style applied-class="report-company" applied-type="pdf:H2" >
    <style:Background color="#222222"/>
    <style:Fill color="white"/>
    <style:Padding all="10pt"/>
    <style:Position full-width="true"/>
    <style:Font family="Helvetica" size="30" bold="true" italic="false" />
  </style:Style>

  <!-- Report Date -->
  <style:Style applied-class="report-date" applied-type="pdf:H4">
    <style:Text date-format="D"/>
    <style:Padding all="10pt"/>
  </style:Style>

</style:Styles>

 

Now if we generate both the documents we can see the shared styles in Common.psfx are being applied to each document.

 


 

We are not limited to one reference, and the stylesheet can also reference other stylesheets, so we can build our document structure as needed

Styles are applied in the order they are read, so we can add another stylesheet (e.g. Budget.psfx) and if we reference Common.psfx from within there, then we can override some styles, and know that all the correct stylesheets are included.

 

Budget.psfx

<?xml version="1.0" encoding="utf-8" ?>
<style:Styles xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">

  <!-- Include the common stylesheet before the overrides -->
  <style:Styles-Ref source="Common.psfx" />

  <!-- Report Title-->
  <style:Style applied-class="report-title" >
    <style:Background color="#55FF55"/>
  </style:Style>

</style:Styles>

 

BudgetReport.pdfx

<?xml version="1.0" encoding="utf-8" ?>
<pdf:Document xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">
  <Styles>
    <style:Styles-Ref source="./Stylesheets/Budget.psfx" />
  </Styles>
  <Pages>
    <pdf:Page>
      <Content>
        <pdf:H1 style:class="report-title">Budget report</pdf:H1>
        <pdf:H2 style:class="report-company">Contoso Incorporated</pdf:H2>
        <pdf:H4 style:class="report-date"><pdf:Date /></pdf:H4>
      </Content>
    </pdf:Page>

    <!-- Content for the budget report -->
  </Pages>
</pdf:Document>

 


 

Referencing a page

 

Whilst styles are common inclusions, we can also add shared pages and sections into our documents in a similar way. This will allow us to build key features into a document without creating a complex document (e.g. separate our a complex databinding grid), or include standard pages (e.g Terms and Conditions).

Because a referenced page becomes part of the document object graph, it also forms part of the binding hierarchy. So you can alter a binding source in a higher level component, and then include a page that simply expects a standard schema for binding to.

 

Legal.ppfx

<?xml version="1.0" encoding="utf-8" ?>
<pdf:Section id="LegalStatements" xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">
  <Content>
    <pdf:Div style:class="legal-statements" style:padding="20 20 20 20" style:font-size="12pt" style:fill-color="#333333">
      <!-- Legal statements -->
      <pdf:H2 style:class="legal-title" >Confidentiality</pdf:H2>
      <pdf:Div style:class="legal-description">The contents of this report are confidential. Please do not distribute.</pdf:Div>
      <pdf:H2 style:class="legal-title" >Security</pdf:H2>
      <pdf:Div style:class="legal-description">The contents of this document are secure. Please do not tell anyone the password.</pdf:Div>
      <pdf:H2 style:class="legal-title" >Data Protection</pdf:H2>
      <pdf:Div style:class="legal-description">The contents of this document fall under the 1984 data protection rules.</pdf:Div>
    </pdf:Div>
  </Content>
</pdf:Section>

 

BudgetReport.pdfx (Updated)

<?xml version="1.0" encoding="utf-8" ?>
<pdf:Document xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">
  <Styles>
    <style:Styles-Ref source="./Stylesheets/Budget.psfx" />
  </Styles>
  <Pages>
    <pdf:Page>
      <Content>
        <pdf:H1 style:class="report-title">Budget report</pdf:H1>
        <pdf:H2 style:class="report-company">Contoso Incorporated</pdf:H2>
        <pdf:H4 style:class="report-date"><pdf:Date /></pdf:H4>
      </Content>
    </pdf:Page>

    <!-- Content for the budget report -->


    <!-- Referenced legal page -->
    <pdf:Page-Ref source="./Pages/Legal.ppfx" />

  </Pages>
</pdf:Document>

 

And we can now see the content included as part of the document. Because our referenced page is actually a Section, we could overflow onto multiple pages.

 


 

Referencing a component

 

Along with pages we can include content within any page or section as a referenced component. This allows us to have standardised components as part a document to reduce complexity or re-use standard components. The components can also be part of the binding hierarchy, in this example using item bindings to a report title and company, setting the auto-bind to true on the document.

 

ReportTitle.pcfx

<?xml version="1.0" encoding="utf-8" ?>
<pdf:UserComponent id="LegalStatements" xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
			style:border-color="black" style:border-width="1pt" >
  <Content>
    <pdf:H1 style:class="report-title" text="{item:Title}"></pdf:H1>
    <pdf:H2 style:class="report-company" text="{item:Company}"></pdf:H2>
    <pdf:H4 style:class="report-date"><pdf:Date /></pdf:H4>
  </Content>
</pdf:UserComponent>

 

BudgetReport.pdfx (with referenced title component)

<?xml version="1.0" encoding="utf-8" ?>
<pdf:Document xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              auto-bind="true" >
  <Styles>
    <style:Styles-Ref source="./Stylesheets/Budget.psfx"/>
  </Styles>
  <Pages>
    <pdf:Page>
      <Content>
        <pdf:Component-Ref source="./Parts/ReportTitle.pcfx"/>
		<!-- Add other specific content to the title page -->
      </Content>
    </pdf:Page>

    <!-- Content for the budget report -->

    <!-- Referenced legal page -->
    <pdf:Page-Ref source="./Pages/Legal.ppfx"/>
  </Pages>
</pdf:Document>
The referenced component is a UserComponent in this case, but could be any known component (Panel, Div, Span, Label etc.)

 


 

Using select XPath expressions

 

Along with referencing paths with the Page-Ref and Component-Ref elements, scryber also supports the use of XPath selectors to dig into the content.

This allows us to group parts or pages together, and include specific elements within other documents.

The xPath expression must be executed in the context of the referenced document, and the selector must therefore be qualified with the xml namespaces within that document.

 

Legal.ppfx (multi page group of standard pages)

<?xml version="1.0" encoding="utf-8" ?>
<pdf:PageGroup id="LegalStatements" xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">
  <Pages>

    <!-- Legal statements -->

    <pdf:Section id="Statements" >
      <Header>
        <pdf:Component-Ref source="../Parts/StandardHeader.pcfx"/>
      </Header>
      <Content>
        <pdf:Div style:class="legal-statements" style:padding="20 20 20 20" style:font-size="12pt" style:fill-color="#333333">
          <pdf:H2 style:class="legal-title" >Confidentiality</pdf:H2>
          <pdf:Div style:class="legal-description">The contents of this report are confidential. Please do not distribute.</pdf:Div>
          <pdf:H2 style:class="legal-title" >Security</pdf:H2>
          <pdf:Div style:class="legal-description">The contents of this document are secure. Please do not tell anyone the password.</pdf:Div>
          <pdf:H2 style:class="legal-title" >Data Protection</pdf:H2>
          <pdf:Div style:class="legal-description">The contents of this document fall under the 1984 data protection rules.</pdf:Div>
        </pdf:Div>
      </Content>
    </pdf:Section>

    <!-- Terms and Conditions page -->
    <pdf:Section id="TsAndCs" >
      <Header>
        <pdf:Component-Ref source="../Parts/StandardHeader.pcfx"/>
      </Header>
      <Content>
        <pdf:Div style:class="terms-conditions" style:padding="20 20 20 20" style:font-size="12pt" style:fill-color="#333333">

          <pdf:H2 style:class="legal-title" >Terms and conditons</pdf:H2>
          <pdf:Div style:class="legal-description">These are the terms and conditions of sales.</pdf:Div>
        </pdf:Div>
      </Content>
    </pdf:Section>

  </Pages>
</pdf:PageGroup>

 

StandardHeader.pcfx

<?xml version="1.0" encoding="utf-8" ?>
<pdf:UserComponent id="StandardPageHeader" xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe">
  <Content>
    <pdf:Table style:full-width="true" style:padding="10pt" style:font-size="10pt" style:margins="0 0 10 0">
      <pdf:Row>
        <pdf:Cell style:h-align="Left">
          <pdf:Label text="{item:Title}" />
        </pdf:Cell>
        <pdf:Cell style:h-align="Center" style:font-bold="true">
          <pdf:Label text="{item:Company}" />
        </pdf:Cell>
        <pdf:Cell style:h-align="Right">
          <pdf:Date/>
        </pdf:Cell>
      </pdf:Row>
    </pdf:Table>
  </Content>
</pdf:UserComponent>

 

BudgetReport.pdfx

<?xml version="1.0" encoding="utf-8" ?>
<pdf:Document xmlns:pdf="Scryber.Components, Scryber.Components, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              xmlns:style="Scryber.Styles, Scryber.Styles, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"
              auto-bind="true">
  <Styles>
    <style:Styles-Ref source="./Stylesheets/Budget.psfx"/>
  </Styles>
  <Pages>
    <pdf:Page>
      <Content>
        <pdf:Component-Ref source="./Parts/ReportTitle.pcfx"/>
      </Content>
    </pdf:Page>

    <!-- Content for the budget report -->

    <!-- Referenced legal page -->
    <pdf:Page-Ref source="./Pages/Legal.ppfx" select="pdf:PageGroup/Pages/pdf:Section[@id='Statements']"/>
  </Pages>
</pdf:Document>

 

 

Building a hierarchy

 

We have now built up a hierarchy of documents, pages, components and styles that are reusable and discreet. If we make a change to a referenced file, then we know that those changes will be visible in all documents generated from now on, that use the referenced file.

We could add a new section file for our main budget content (BudgetDetails.ppfx) and reference this in our top level document. Our final document is still simple, and we have isolated core parts for updates.

 


 

See Also

 

 



  Rating
Rate This Page: Poor Great   |  Rate Content |
Average rating:  No Ratings Yet   
Number of Ratings : 0
  Comments
Add Comment
No Comments Yet