Alinex Report: Readme

GitHub watchers GitHub stars GitHub forks

npm package latest version Travis status Coveralls status Gemnasium status GitHub issues

This report module should help you create complex reports in an easy way. You create a new object and append different text objects step by step. At last you may access the markdown text or get it converted to HTML.

The key features are:

  • easy markdown writing
  • feature rich markdown
  • export as text, console, html (also optimized for email), pdf, png or jpg
  • convert text to visual representation like qr, chart or UML
  • optimized interactive tables

See example output within the different element descriptions below.

Internally this works with a markdown syntax which has a limited number of possibilities but is easy to transform in nearly any other format. If you know markdown you will find the possibilities here enormous. And you may also directly load markdown and process it using this package.

The html export can also be optimized for email using ìnlineCss option. With this setting the styles from the head section will moved into the document because webmail client will remove the head section completely. Only for javascript there is no possible replacement.

The Documentation of this module itself uses the alinex-report module to generate the html pages.

It is one of the modules of the Alinex Namespace following the code standards defined in the General Docs.

Install

NPM Downloads

The easiest way is to let npm add the module directly to your modules (from within you node modules directory):

Shell Script
npm install alinex-report --save

And update it to the latest version later:

Shell Script
npm update alinex-report --save

This package will install a lot of subpackages to ensure the full functionality but only the ones really needed are loaded on demand.

Always have a look at the latest changes.

Usage

The first step is to load the module and setup it:

CoffeeScript Code
Report = require 'alinex-report'
Report.setup ->
  # go on

And now you create a new object:

CoffeeScript Code
report = new Report()

You may also give one of the following options:

  • source - markdown text to preload
  • log - a function called each time something is added with the added text
  • width - the width for line breaks (default: 80)

Report builder

The report builder is a collection of methods used to easily create the needed markup. They often are handy to convert your objects into formatted text:

CoffeeScript Code
report.h1 "My Test"
report.p "This is a short demonstrative test with:"
report.list [
  "headings"
  "text blocks"
  "unnumbered lists"
]

Format output

And finally get the complete result:

CoffeeScript Code
console.log report # same as report.toString()
text = report.toString() # markdown syntax
html = report.toHtml()   # html
log = report.toConsole() # text with ansi colors

Convert to Markdown

Instead of creating a report to collect everything, you can also let this module convert single elements on the fly:

CoffeeScript Code
console.log Report.ul ['one', 'two', 'three']
console.log Report.p "This text contains a #{Result.b 'bold'} word."

Markdown as Base

If you want to only convert existing markdown into html do this like:

CoffeeScript Code
html = new Report({source: markdownText}).toHtml()

Mask characters

To mask some characters to be not interpreted as markdown, you may use \ before

the special markdown signs or automatically mask them using Report.mask text if you didn’t want to interpret them as markdown.

Differences to Other Markdown

This class is based on the CommonMark Spec but it extends it with higher level and more complex transformations like boxes, graph, diagram or interactive tables.

That’s the cause for not displaying completely in other markdown implementations like Github.

Output

You have multiple possibilities to output the created markdown object.

Before you look at each of them you can also specify some parts of the content specifically for an output type:

CoffeeScript Code
html = new Report
  source: "This is<!-- begin no-html --> not<!-- end no-html --> html
  <!-- begin html -->= the best format<!-- end html -->".toHtml()

This shows the possibilities to specify a part of the content for a specific output format or exclude it from one.

The possible output formats to select are:

  • text
  • console
  • html (including pdf and image)

For html you may also exclude something using the .hidden class through styles.

Markdown

Example: markdown

To get this native output you can directly convert the object to a string:

CoffeeScript Code
report.toString()

Text Output

Example: text

CoffeeScript Code
report.toText()

Here all non presentable elements are removed to get a clean plain text output. This means the table of contents, decorator rules and backslashes at the end of line are removed as well as image sources.

Console Output

CoffeeScript Code
report.toConsole()

This is targeted to output on the console. Therefore the plain text from above will be marked with ascii escape sequences to add color highlighting. All markup which is possible in console like bold, strikethrough, italic… will be used.

Tables will be drawn using ASCII art grid lines.

HTML Document

Example: html

CoffeeScript Code
report.toHtml() # deprectaed syntax without inline css support

report.toHtml options, (err, html) ->
  # use the html

Options are:

  • title (string) - to be used instead of h1 content
  • style (string) - reference to the used theme under ‘template/report’
  • locale (string) - language to use like ‘de’
  • inlineCss (boolean) - move css from head to the tags as styles (useful for mails)
  • noJS (boolean) - make everything static
  • context (object) - additional elements for handlebars template

This is the most powerful output method. In which all markdown elements will be supported and interpreted. It will create one HTML file to be used in emails…

Only links to internet resources like images and css are kept as they are. local links in the format ‘file:///…’ will be replaced with their content included as data uri in the document. This makes the document larger but helps to keep everything in one file. In emails you may extract these again and replace them with cid uri to the now attached resource.

To change the style and make your own theme seeThemes / Styles.

PDF Document

Example: PDF

CoffeeScript Code
report.toPdf (err, data) ->
  # [](you may store this to a file)

You can also give some options:

CoffeeScript Code
report.toPdf options, (err, data) ->
  # you may store this to a file

Possible options are:

  • format - A3, A4, A5, Legal, Letter or Tabloid
  • height - like “10.5in” allowed units: mm, cm, in, px
  • width - like “8in” allowed units: mm, cm, in, px
  • orientation - portrait or landscape
  • border - like “0” allowed units: mm, cm, in, px
    or as an object with top, right, bottom nad left settings

Image

Example: PNG

CoffeeScript Code
report.toImage (err, data) ->
  # you may store this to a file

File

Also you may let the report be written directly to a file.

CoffeeScript Code
report.toFile filename, options, (err) ->
  # you may store this to a file

The format will be autodetected from the filename’s extension.

License

© Copyright 2016 Alexander Schilling

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.