You know Markdown? Of course you do, everybody does these days. If you’re not familiar with Markdown, here’s the original description from 2004. In a nutshell, it’s a simple text-based format that can be translated easily to HTML or other output formats. It has become ubiquitous and there are many extensions that utilize the basic syntax for advanced purposes. I’m writing this blog post in Markdown right now!
Recently some of us had an idea. We were looking at a document with a Markdown table, similar to this:
# Orders | Product | Unit Price | Quantity | Discount | Subtotal | | :-------- | -----------: | ---------: | ---------: | ---------: | | `Product` | `Unit Price` | `Quantity` | `Discount` | `SubTotal` |
The following came to mind: What if this table could be used as a report definition?
We followed up on this idea and worked out some of the details. Here is a summary, including some answers to the obvious questions you might have.
Simplicity as a goal
Our idea is to use Markdown as a simple syntax to define simple reports. These reports will likely never support every formatting option of the full Designer, or every possible layout idea. However, there are several powerful advantages:
Reports can be created and edited anywhere. The definition format is text-based, so you can use any editor on any platform. A simple text editing widget will do, perhaps including basic highlighting features. That widget can be part of a web application, a mobile application, an Admin frontend. Of course TextMate or Sublime on the Mac work equally well, and so does vi in your Linux-based cloud environment. The format is readable and suitable for manual editing.
Since the report definition format is a document, it can be used very easily for flowing text with data elements – much like a mail merging document, but with advanced features. Arguably such reports are represented better by a document format than by a banded report structure.
You can easily automate the process of creating report definitions. This can be done in any language, on any platform, as long as you can output some basic text to a file or stream it over the network. The format is compact, so it transfers through service interfaces quickly and easily.
Since we focus on Markdown, you can utilize existing tools. Of course this applies to editors, but also to automated processing or transformation, for instance using remark or other parts of the unified ecosystem.
Finally, we don’t plan to lock you in - Markdown report definitions can be converted into our standard REPX format. Reports generated from Markdown will be fully compatible with our existing viewer components and our export mechanisms.
How does Markdown work for reports?
Here is an example of a report definition:
\report{data=NWind, table=Orders, paperkind=letter}
|:---|---:|
|# Invoice|![BarCode]{Code128,OrderID}|
|:---|---:|
|`CompanyName`|Order ID: `OrderId`|
|`ContactName`|Order Date: `OrderDate!M/d/yyyy`|
|`ShipAddress`| |
|`ShipCity`| |
|`ShipCountry`| |
\sreport{table=OrdersOrderDetails}
|Pos. |Quantity |Product Name | Unit Price| Discount| Net Price|
|:--- |:--- |:--- | ---:| ---:| ---:|
|1. |`Quantity`|`ProductName`|`UnitPrice`|`Discount`|`NetPrice`|
|:~~~ |~~~:|
| |
|Item count: `sumCount(ProductName)`|Grand Total: `SumUnitPrice`|
| |Discount Total: `DiscountTotal`|
| |**Amount Paid: `AmountPaid`**|
\newpage
\pagefooter
|:---|---:|
|`CurrentDate!dddd, MMMM d, yyyy|Page `PageNumber` of `PageCount`|This definition is meant to generate a report that looks much like the following image, one of our demo reports:
As you can see, we use a table to arrange report elements on the page. The table occupies the whole page width and column widths are calculated automatically based on the widths they occupy in the Markdown definition.
All standard Markdown syntax works as expected in report definitions. For Reporting purposes, we plan to add several additional elements. Here are some examples:
Declarations
| Syntax | Description |
|---|---|
\report{data=NWind, table=Orders, paperkind=letter} | Declares a report and specifies some properties (data source, table name, paper kind) |
\sreport{table=OrdersOrderDetail} | Begins a detail report and specifies some properties (table name) |
\newpage | Inserts a page break |
\pagefooter | Defines a page footer area |
Elements
| Syntax | Description |
|---|---|
| Pos. | Quantity | Product Name | | Defines a table header and column widths. We are considering the use of a “spacer character” for width definitions, since whitespace is not significant in Markdown. |
| :--- | :--- | ---: | | Separates the table header from the data rows and specifies horizontal alignment. This is a standard Markdown syntax. |
1. | Used in a data table, this generates an enumeration that spans table rows |
`Quantity` | A data-bound field |
| :~~~ | ~~~: | | Declares a table footer with two columns and column alignment |
`sumCount(ProductName)` | An expression with a summary function |
A mail-merging example
Here is an example report with a letter structure:
\report{data=weeklyeval, table=customers, paperkind=letter}
| :--- | :--- |
| `companyname` | Marketplace Inc |
| c/o `contact` | The Place |
| `address1` | Silicon Valley 65738 |
| `address2` | |
| `address3` | |
| `zipcode` | |
| `country` | |
Dear `contact_firstname`,
This is your weekly summary for the timeframe
`weekstart!M/d/yyyy`-`weekend!M/d/yyyy`. These
were your three top customers by total sales:
\sreport{table=topthreecustomers}
| Company Name | Orders | Total Sales |
| :------------ | -----------: | -----------: |
| `companyname` | `ordercount` | `totalsales` |
The following table shows the top three products by total sales:
\sreport{table=topthreeproducts}
| Product Name | Count | Total Sales |
| :------------ | ------: | -----------: |
| `productname` | `count` | `totalsales` |
Thank you very much for your business.
Best regards,
Your team at Marketplace IncThe result rendered by this definition would look like this:
Where does the data come from?
Of course it is possible to generate Markdown reports from application code where a data layer is already in place – just like reports defined in the REPX format or even in code. However, we also plan to enable data source definitions using configuration files, probably based on YAML. This approach makes it possible to create reports entirely from command line environments, or more generally to implement workflows that don’t involve UI of any kind. Optionally we can allow YAML “front matter” to the Markdown report definition, to combine a report with its data source in one file.
How are reports styled?
A core idea of Markdown is that you don’t think about styles when you write your text. For our Reporting concept, we follow the same approach. Default styles will be provided for all format elements: headers, table structures with headers, footers, odd and even rows, and so on. These styles can be overridden separately, independently of the report definition.
Please Let Us Know Your Thoughts
At this point, the plans described above are just an idea. We need your feedback to decide whether to commit to these plans! What do you think? Please feel free to leave a comment below, open a ticket in Support Center for discussion or contact us at reportingteam@devexpress.com. Additionally, it would be very helpful if you could submit your responses to this short survey:
