Markdown-based Reporting - Your Vote Counts

14 February 2019

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:

Sample Report

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 Inc

The result rendered by this definition would look like this:

Mail Merging Report Sample

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:

19 comment(s)
Steve Sharkey

Off topic I know but it is about reports...

Whilst I really like the DevExpress report I have found over the years that most of the users of my systems use Microsoft SSRS to satisfy their reporting requirements. The server side of SSRS is very competent BUT the tool to build them is pretty quirky. Since their tool is so far behind the competition and yet the server side is pretty solid I've often wondered how involved it might be to get a tool (such as the DevExpress report builder) to export RDL that could be used in SSRS...

14 February, 2019
Jonatas Hudler

For traditional reports (XtraReports) I'm a little skeptical of markdown real world feasibility. Perhaps - who knows. On the other hand, this feature in Snap (RichEditControl) documents could be indeed a great addition, adding a more "public domain" alternative to the current notation. Anyway, Is always good to see these experimentations popping out from your labs.

14 February, 2019
SistemasCaltic

I think similar to jonatas hudle I believe that could be hard to create complex reports that need formulas between data or grouping and nested report or vertical reports or pivot reports but if you have ideas about how create for example a pivot report more interactive or charts could be great I have a doubt of how define the data and relations and grouping with markdown, how export the data to pdf or excel,  I believe that with mark down could be easier generate more mail - merge reports that complex reports.  

14 February, 2019
Karel Král Scia

Great idea for very simple reports... For complex reports i don't think it is sufficient.

14 February, 2019
Vladislav Kiselev

Shut up and take my money right now!!!111

If seriously, this sounds very useful. In many cases we don't need heavy and powerful reports, but we still need reports. From the first point of view, we may need this for typescript and for dotnet. This engine should accept DevExtreme data sources layer (typescript) or IEnumerable / IQueryable (dotnet) as a source for table data.

What is about preprocessor? I mean we may need to combine report template from smallest parts and then build a report from combined template.

14 February, 2019
TimH

I love the idea of it, with regards to

\report{data=weeklyeval, table=customers, paperkind=letter} and its kind

i presume \report is a special keyword approach, i wonder if you could use a more generic comment style like discussed here

stackoverflow.com/.../comments-in-markdown so its more compatible with other markdown renderers

also why {data=weeklyeval, table=customers, paperkind=letter} instead of proper JSON so it could easily be extended and parsed

14 February, 2019
Alain Bismark

what about markdown to create forms....or to define xaf bo classess...

14 February, 2019
Birger Jansen

When I think about it, wouldn't it be better to have the RTF Editor Mailmerge functionality ported from WIN to WEB and add master-detail to that?

14 February, 2019
Uros Rovtar

wish also markdown to POS printers

15 February, 2019
Bert Stomphorst

As with others, I don't yet see this as a potential replacement of XtraReports. Where it could be a useful solution is for things like generating (e-mail)messages (hence the mailmerge), not for creating reports to attach as pdf.

15 February, 2019
Marcel van der Gragt

It may be a great replacement for the web based report designer. I use it to allow customers to change existing reports, but most find it too complex.

Markdown may be a better solution for them.

15 February, 2019
Habib Salim

This sounds fantastic!  I will start looking into playing this in our application.

Can't want for it to come true.

Thanks!

15 February, 2019
Alain Bismark

I would like side by side development, in Markdown and in Snap...

that is, two panels, in the left, the markdown source code, in the right the result render..., synchronized all time, like www.livexaml.com/index.html

17 February, 2019
S. Hartmann

A markdown report would be nice,

but a MarkDownEdit and an according Preview component  as a first step,

would have much more value for us.

17 February, 2019
Oliver Sturm (DevExpress)

Everybody - thank you very much for your comments, and for the survey submissions! The reaction to our idea has been largely positive and we will now go back and think about the concept some more before making any implementation plans. Please rest assured that we will take your suggestions into consideration. I can't promise anything specific at this point, as I'm sure you understand - we will post again about our plans in the future. Please keep the comments coming if you have additional ideas!

19 February, 2019
José Enrique

It would be really useful, but previous to that, why not implement a MarkDown editor as S. Hartmann says. I've been asking for that from years. If you write with the focus on quality contents for internet, html is not the way. You need to normalize the styles and avoid user design error when writing a post os something like that. With MarkDown the contents are preserved and you can change publish style with no risk.

20 February, 2019
Juan Antonio Trujillo Montenegro

Will be nice to if it comes with a previewer. :)

21 February, 2019
ima_aa

Richedit support would be great. But i dont think we need reporting

10 March, 2019
Andrew Greene

I have been updating and creating DevExpress Reporting for about a year in a desktop .Net application. Recently I started looking for a web framework to utilize a new API with the business logic of the desktop app. I don't know if the current reports will be available to the web API.

I also don't know yet what reports will be needed. The preliminary plans are for providing 'reporting' only functionality, either initially or as the only option. This markdown layout format look like a quick way to provide data, either as a "what data does the report need?", or "here is the data you requested."

I do not put formulas in the report definition, I create them in the data source, hopefully the API is providing the correct formulas. That way I don't have to write in multiple reports in multiple ways and update them all. The report only needs to provide the number, currency and date format. I think a markdown approach to reports will work for most, if not all, of the data we are interested in providing.

11 March, 2019

Please login or register to post comments.