README.md 4.02 KB
Newer Older
1 2 3 4 5
# MigraDocXML

[Lessons available here](Lessons.md)

## Introduction
James Coyle's avatar
James Coyle committed
6
From having to do a fair amount of work producing PDFs, I found MigraDoc is currently the only really viable open source .NET option available. It includes some excellent features that give a lot of control over creating PDFs, while still staying high level enough to be easy to understand.
7

James Coyle's avatar
James Coyle committed
8
However, the way document designs are written does also present some major drawbacks:
9

James Coyle's avatar
James Coyle committed
10
- Languages like C#/VB.NET just aren't well suited to the hierarchical nature of building up a display object model, and creating anything beyond a simple layout can quickly become a real challenge to remain readable. Other XML based languages such as HTML & XAML have proven that XML is far better suited to this sort of work.
11
- Document designs are stuck within your project assembly. This prevents quick design changes without recompiling your code, also making it much harder to have a product that ships to multiple customers, where each customer has their own requirements for PDF exports.
James Coyle's avatar
James Coyle committed
12
- Your programmers shouldn't be creating PDF reports. As a programmer, writing PDF designs is just plain boring, most of what you're writing is very boilerplate stuff, often plugging in slightly different numbers and recompiling to see if things finally line up right. MigraDocXML has been designed to be usable by people who don't come from a programming background but are willing to learn a few basic concepts.
13

James Coyle's avatar
James Coyle committed
14
MigraDocXML aims to solve these problems, while still keeping as much flexibility as possible. Below are some of its features:
15

James Coyle's avatar
James Coyle committed
16
- Supports inserting data from JSON, CSV or XML files, as well as directly from .NET objects
17
- MigraDoc's styling has been completely redesigned, with MigraDocXML offering a full cascading style system
James Coyle's avatar
James Coyle committed
18
- Designs can define their own variables, conditional and iterative logic, also includes EvalScript, a lightweight expression evaluator which provides a lot of advanced language features. These combine to allow the easy writing of flexible designs that can adapt to your data
19
- Resources (stored either internally or externally) support code reuse
James Coyle's avatar
James Coyle committed
20 21
- Bridges the gap between MigraDoc & PDFSharp, allowing for the addition of custom drawings to your designs
- Includes an extension library that makes use of ZXing.NET to support inserting barcodes
22

23
## Example
24
Below is a demonstration of a layout file which takes in a json file to produce [this](Samples/sample.pdf).
25 26 27 28

json:
```
{
James Coyle's avatar
James Coyle committed
29
    "Name": "MigraDocXML",
James Coyle's avatar
James Coyle committed
30 31 32 33 34 35 36 37 38 39
    "Positives": [
        "Simple to learn",
        "Easily readable design layouts",
        "Full cascading style system",
        "Support for PDFSharp graphics",
        "Includes a powerful lightweight expression evaluator",
        "Regular updates"
    ],
    "Negatives": [
    ]
40 41 42 43 44 45 46
}
```

xml:
```
<?xml version="1.0"?>
<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
James Coyle's avatar
James Coyle committed
47
          xsi:noNamespaceSchemaLocation="https://gitlab.com/jamescoyle/MigraDocXML/raw/master/MigraDocXML/schema.xsd">
48

James Coyle's avatar
James Coyle committed
49
    <Style Target="p">
50 51 52
        <Setters Format.Font.Name="Calibri" Format.SpaceBefore="2mm" Format.SpaceAfter="2mm"/>
    </Style>

James Coyle's avatar
James Coyle committed
53 54 55
    <Style Target="p" Name="Heading">
        <Setters Format.Font.Bold="true" Format.Font.Underline="Single"/>
    </Style>
56

James Coyle's avatar
James Coyle committed
57
    <Section>
James Coyle's avatar
James Coyle committed
58
        <p Style="Heading" Format.Font.Size="15" Format.Alignment="Center">Reasons you should use {Model.Name}</p>
James Coyle's avatar
James Coyle committed
59

James Coyle's avatar
James Coyle committed
60 61 62 63
        <p Style="Heading">Positives:</p>
        <ForEach Var="positive" In="Model.Positives.OrderByDesc(x => x.Length)">
            <p>{positive}</p>
        </ForEach>
64

James Coyle's avatar
James Coyle committed
65 66 67 68
        <p Style="Heading">Negatives:</p>
        <ForEach Var="negative" In="Model.Negatives">
            <p>{negative}</p>
        </ForEach>
69 70 71 72 73 74 75
    </Section>
</Document>
```

MigraDocXML also includes a small WPF app for easily previewing the effect of changes to the layout or data on your output PDF. You can use the incredibly basic text editors included in the app, or, use whichever one you normally do. Either way, each time you save changes to your documents, the PDF will automatically get rerendered.

![alt text](Samples/Preview_app.jpg)