A component is the name used for a discreet element in the xml template file
Examples of components are a page, a panel, a label, or even a block of text.
Each of these components refer to a specific class within a library, and the XML Parser looks for these classes based on the declared name
Almost all Scryber components inherit from the PDFVisualComponent class (rather than directly from PDFComponent) as this includes a number of capabilities required by the components.
The container component adds interface support for children, and the visual component adds support for style information.
This means that even the label can in theory contain other child components, although in practice this is behind an explicit interface, and may not be used or rendered on the final output.
To understand how the attributes and elements in an XML file are converted to the object instances you should read
An Introduction to the XML Parser
Standard Component Attributes
Because of this hierarchy the concrete classes of Panel, Page, Label etc. support standard attributes
- The id tag is a way to refer to the component in a document, it should be unique within the current Documemt, Page, UserComponent, or template - and will be built into a full UniqueID based on it's hierarchy of parent INamingContainers. You can get access to a specific component using the GetComponentByID(string name) method, which will search down that hierarchy for a matching component. If an id is not specified, then one will be assigned based on the object type.
Id's can also be used with styling information to explicitly apply a style to a component with a specific id.
- Component names can be thought of as the same as the name attribute in an HTML anchor. It should be unique within the whole document to have predictable behaviour, and can be used for linking
- Scryber supports outlines directly on components and will generate the outline tree for the final PDF Output. All components support an Outline element which has a number of attributes, but the outline-title is surfaced for convenience at the top level of the component.
- Each component can either be included in the output or not. If the visible attribute is set to false then the component will not take any part in layout or rendering, nor will any child component
Style Component Attributes
Each PDFVisualComponent surfaces properties from the style that can be set as attributes on that component declaration. They are all direct references to attributes within the style items of a component.
The only other attribute that affects styles is the styles:class attribute, which is declared on the component and does not alter the style until the component is laid out
The style:class attribute accepts one or more names of styles and will have any definitions declared against that name applied to the component
The use and declaration of styles is discussed as part of the Understanding Styles section.
Component child elements
Every component supports at least 2 child elements - Outline and Style.
- The outline element supports the Bookmarks / Table of Contents view available within PDF readers. The main attribute is the title (surfaced as outline-title on the parent element) that specifies the textual content of the outline. The other attributes are style based and support the appearance of the entry in the bookmark panel of the reader.
This can be specified individually as colour, font-bold, font-italic for the text and open for the status when the PDF document is first read. As with all style attributes these can also be based on a style definition - Understanding Styles.
- The Style element allows access to a complete set of style options. The surfaced attributes are on the parent component, but only covers standard (frequently used) options. The Style element allows for a complete set of Style Item definitions
There are a growing number of components available within the Scryber library.
A complete description of all of them is available in Available Components