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

Scryber Configuration

Not Rated Yet

Scryber comes working as default without any required configuration, but if you want to change the way it works, or add capabilities deep within the heart of the library, then most things can be configured

configSections

In order to add custom configuration to your application or web config file, you will need to declare the sections, that all reside within a single section group.

The use of multiple sections within a group allows the separation of configuration, reducing the library dependancies.

The sections are scryber/tracing, scryber/fonts, scryber/imaging and scryber/generation.

<configuration>
  <configSections>
    
    <!-- Other section declarations -->
    
    <sectionGroup name="scryber">
      <section name="tracing" type="Scryber.Configuration.TracingConfigurationSection, 
                                  Scryber.Configuration, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"/>
      <section name="fonts" type="Scryber.Configuration.FontsConfigurationSection, 
                                 Scryber.Configuration, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"/>
      <section name="imaging" type="Scryber.Configuration.ImagingConfigurationSection, 
                                 Scryber.Drawing, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"/>
      <section name="generation" type="Scryber.Configuration.GenerationConfigurationSection, 
                                 Scryber.Configuration, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe"/>
    </sectionGroup>
  </configSections>
  .
  .
  .
  <scryber xmlns="Scryber.Configuration, Version=1.0.0.0">
    <fonts font-substitution="true" >
    </fonts>
    <imaging allow-missing-images="true">
    </imaging>
    <generation missing-reference-action="RaiseException">
      <schemaMappings></schemaMappings>
    </generation>
    <tracing trace-level="Verbose">
      <clear />
      <log name="WebTraceLog" factory-type="Scryber.Logging.PDFWebTraceLogFactory, Scryber.Common, Version=1.0.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe" />
    </tracing>
  </scryber>
  .
  .
  .
</configuration>

 

There are currently 4 sections available for out of the box components, and although they only need to be declared when they are used, if they are not used, but declared, then no error is raised.

Each section and the options it offers are detailed below

 

scryber/tracing

Scryber has a significant level of diagnostic reporting available within the code. Normally it is not used, and simply disregarded after processing. But sometimes you just need to know what's going on, and this section will help unlock this trace information

Understand the Tracing and Reporting output here
    <tracing trace-level="Messages">
      <clear/>
      <log name="DiagnoticsTraceLog" factory-type="Scryber.Logging.PDFDiagnoticsTraceLogFactory,
                        Scryber.Common, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe" />
      <log name="WebTraceLog" factory-type="Scryber.Logging.PDFWebTraceLogFactory,
                       Scryber.Common, Version=0.8.0.0, Culture=neutral, PublicKeyToken=872cbeb81db952fe" />
      
      <!-- Creating your own is easy, simply define a class with a paramerterless constructor and implement the IPDFTraceLogFactory interface-->
      <log name="MyLogName" factory-type="[qualified type name]" />
    </tracing>

 

The first option is the @trace-level attribute.
This controls the amount of content that is output on the trace-log by the library (or your own code). The options are as follows

Off
Switches off all recording of entries to the trace log. Nothing will be output at all
Errors
Only errors will be recorded. By default unknown parser elements, missing images and missing fonts all cause the system to generate exceptions. These are also recoded as errors in the log, so that it can be captured and mitigation action taken when required.A good setting for a released application
Warnings
Warnings can happen if some of these errors are set to be ignored - The parser includes a switch to pass over unknown elements, the image library can ignore not found exceptions and continue on rendering, and fonts can be missing from the system. In this case the Warnings will be raised rather than an error, and these can be logged.
A good setting for a production web system
Messages
This is the default value for all OOB implementations. There are not many travelog entries output as message, but the main document lifecylce events are output as message, such as Init, Load, Databind, image Download etc.
This allows the identification of key performance issues, actions within a document generation without being inundated with information. It is also a good level to report custom messages, so they can be captured and identified easily
A good setting for a testing / development platform or application
All
Outputs all the debugging and positioning trace messages. Internally this is used regularly to check for defects, and ensure the layout engine is working correctly, but is not recommended for general use. If it really is required, then it can be useful to temporarily identify defects, but it does seriously degrade the application performance.

The inner elements of the tracing section are log, remove and clear. Where remove will simply remove a log with the specified @name, and clear will remove all entries - a good way to ensure that there are no duplicate log with the same name (as this will cause a fatal exception that will break the entire executing process

It is then that specific logs are added to the list so that entries are recored as required. The log entry attributes are as follows

@name
A unique name for the logging entry in the config file hierarchy
@factory-type
The fully qualified type name to a class that implements the IPDFTraceLogFactory method.
These factories must have a parameterless constructor so they can be instantiated by the configuration section. Once instantiated they will be requested to create a new PDFTraceLog instance every time a new PDFDocument is generated (with the currently configured trace level

If more than one tracing log is defined then they will each be called in turn with the same message. If you think that scryber has started running slowly, then do check the tracing logs first

 

scryber/fonts

Scryber supports dynamic loading of true type fonts from the system fonts directory, or a pre-defined location, or specific inclusion based on name to file mapping. And it can also use font substitution if used fonts are not found.

<fonts   use-system-fonts="true" font-substitution="false" 
                      default-directory="[path to std fonts directory]" default-font="[name of the default font to use]" >
      <clear/>
      <add family-name="Bauhaus 93" font-style="Bold" font-file="[path to file]" />
      <!-- or @rsrc-name='[resource name]' and @rsrc-base='[manager assembly name]' -->
</fonts>

 

The first options within the fonts section define default settings

@use-system-fonts
This is by default true, and scryber will look in the system fonts directory of the computer hosting the process. There is an initial over head for loading all the font references from the system fonts directory, and there are also security requirements that the currently running process be able to access the fonts directory (which is a fairly common scenario - not considered risky). If this is configured to false, then no system fonts will be loaded.
@font-substitution
When rendering a PDF file the font is loaded and read so that the glyph widths can be read and used for measuring strings for layout. If the library cannot find the font file then it has no option to abort the rendering. On a production system this could cause failures without warning, so it is possible to support font substitution - if a font is not found then the standard Courier font is used which has standard width characters and does not need to be included within the final PDF Output.
@default-directory
When this attribute is specified, a new / different path to true type fonts can be loaded (that may or may not be available within the current system).
By using a specific directory and ensuring fonts are loaded then it is a known and bounded repository. Websites can be sure they have the correct resources, and applications can be distributed with the fonts that they require.
@default-font
scryber will render any text using the Arial font by default, and include that font within the PDF document. Obviously it's easy to change this default font with styles, but it may be appropriate to specify a different default font, and this can be done by application of the @default-font attribute in this section.

 

scryber/imaging

Scryber can work with all the image types supported by the .NET framework including JPEG, TIFF, PNG, BMP, GIF and also supports transparency (in all the formats that support transparency), but sometimes images are just not available in files, but are dynamically loaded / generated. Scryber has a special way of dealing with this out of the box, and also dealing with images that cannot be found (or no longer exist).

<imaging allow-missing-images="true">
      <clear/>
      <imageFactory match-path=".myextn" factory-type="MyImageDataFactory, My.Scryber.Assembly" />
</imaging>

 

The @allow-missing-images is by default 'false', if an image cannot be found or cannot be loaded, then we are in an error condition as all PDF Files expect image data to be included directly within the document (not a reference), so the document would be invalid and incomplete.
However by setting the configuration attribute to 'true' then all missing images with be replaced with the not-found image (using all style info just as if this was the actual image).
The generated PDF is therefore still valid and complete, and can be used

For custom / dynamic images getting these images into a PDF file can be tricky. It can involve hand cranking the code and loading images outside of the standard document lifecycle
Scryber supports a different mechanism for loading dynamic images. By specifying a new <imageFactory> entry in the configuration it will invoke any instance of an IPDFImageDataFactory based on a regular expression match. Each of the expressions will be searched in order top to bottom and the first match will return an activated instance of the factory.
And path and form can then be used on the src attribute of an image component, and custom code can handle the creation and returning of the required data.

 

scryber/generation

Scryber document templates are dynamically parsed, You can find out more about the parser and how it works here, but it also has (a limited) ability to customise where it looks for assemblies and classes.

<generation>
      <clear />
      <register xml-namespace="http://schemas.other.scryber.co.uk" runtime-namespace="[Other.Namespace]" runtime-assembly="[Other Assembly Name]" />
</generation>

 

Similar to the other sections the scryber/generation section allows a list of inner elements (that can be modified with the <remove @xml-namespace=' ' />, or reset with the <clear /> entry).

<register ... /> adds a new custom / altered namespace to the collection that will be used to look up assembly and namespace information for dynamic type retrieval.

@xml-namespace
This is the namespace that is declared within the pdfx document template. The format of the namespace can be anything, and is not restricted to url's or assembly full names
@runtime-namespace
This must be a valid namespace that can be found in the assembly specified in the next attribute
@runtime-assembly
This must be a reference to a unique assembly that can be found by the running process containing the types that should be parsed in the identified namespace

By utilising this mechanism it is possible to produce shorthand assemblies, or replace entire versions with new assemblies, without altering the code



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