Package: js-template-builder

Provide a set of tools to build a report with a customizable reporting language. Similar to Excel or Microsoft SQL Report Builder. Provided a XML/HTML Template and a Model Definition (The structure of the input data) and the Model (the input data), the package outputs a compiled XML/HTML file.

Purpose

This is meant to be used as a support for the end user who wants to modify the reports or views generated through the package. For example this is useful with CKEditor that provide an HTML Editor (see also ckeditor5-template-builder).

Install

npm i report-builder

Usage

Let's see a pratical example :

const { Renderer, ModelDefinition, DataType } = require('report-builder');

// This is the model definition or structure
const modelDefinition = ModelDefinition.parseFromRawObject({
    type: DataType.Object,
    props: [
      {
        name: 'reportData',
        type: DataType.Object,
        props: [
          {
            name: 'sellings',
            type: DataType.Array,
            props: [
              {
                name: 'id',
                type: DataType.Primitive,
              },
              {
                name: 'product',
                type: DataType.Object,
                props: [
                  {
                    name: 'id',
                    type: DataType.Primitive,
                  },
                  {
                    name: 'price',
                    type: DataType.Primitive,
                  },
                ],
              },
              {
                name: 'quantity',
                type: DataType.Primitive,
              },
            ],
          },
        ],
      },
    ],
  }),

// The data itself
const model = {
    reportData: {
      sellings: [
        {
          id: 0,
          quantity: 0,
          product: {
            id: 1,
            price: 20.5,
          },
        },
        {
          id: 1,
          quantity: 2,
          product: {
            id: 2,
            price: 50,
          },
        },
        {
          id: 2,
          quantity: 11,
          product: {
            id: 4,
            price: 5,
          },
        },
      ],
    },
  };

const template = /*html*/`
  <any>
    <any class="data-declaration">sellings = Array.filterByProperty(reportData.sellings, "quantity", ">", 0)</any>
    <any class="data-context">
      <any class="data-control-expression">
          @foreach selling of sellings
      </any>
      <any class="data-content">
        <any class="data-context">
          <any class="data-control-expression">
          </any>
          <any class="data-content">
            <any>
              Id:
              <any class="data-expression">
                selling.id
              </any>,

              Quantity:
              <any class="data-expression">
                selling.quantity
              </any>,

              Price:
              <any class="data-expression">
                selling.product.price
              </any>,

              Total:
              <any class="data-expression">
                mul(selling.product.price, selling.quantity)
              </any>
            </any>
          </any>
        </any>
      </any>
    </any>
    <any>
      Report resum:
      <any>
        Total Quantity:
        <any class="data-expression">Array.sum(Array.mapByProperty(sellings, "quantity"))</any>
      </any>
      <any>
        Total Income:
        <any class="data-expression">Array.weightedSum(Array.mapByProperty(sellings, "quantity"), Array.mapByProperty(sellings, "product.price"))</any>
      </any>
    </any>
  </any>`;

// Execute
Renderer.parseFromXml(modelDefinition, model, html).then((result) => console.log(result));

The output will be the following

// Will print the following
<any>
  <any> Id: 1, Quantity: 2, Price: 50, Total: 100 </any>
  <any> Id: 2, Quantity: 11, Price: 5, Total: 55 </any>
  <any>
    Report resum:
    <any> Total Quantity: 13 </any>
    <any> Total Income: 155 </any>
  </any>
</any>

Model Definition

There are three different kind of nodes for model definition: Primitive, Object, Array. Every model node definition has different properties:

| Property Type | Purpose | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | the name of the property | | type | value between Primitive, Object, Array | | props | defined only if type is Object or Array. Every prop is a model node definition. In the case of an Array if this property is not defined then it is an Array of Primitives |

Language for templating

Expressions

The language defined for reporting is based on Expressions of two types: Expression and Control Expression.

The first one is used for returning a value while the second one to alter the flow control of the rendering.

Expression

This returns a value. This is achieved throught the attribute class data-expression:

In the example before :

<any class="data-expression example-class"
  >Array.weightedSum(Array.mapByProperty(sellings, "quantity"), Array.mapByProperty(sellings,
  "product.price"))</any
>

You can apply the class on any element and the result will be the following once executed:

<any class="example-class">Executed value converted to string</any>

The format of the expression inside can be :

1. a function call with parameters. << functionName(param1.prop.x, param2, "staticValue", 0.2) >> or << functionName(functionName2(...), ...) >>. There are some functions included by default inside the package ( watch the next sections ).
2. a variable property path << variableName >> or << variableName.property >> or << variableName.property.a >>
3. a static value (string or number) << "string" >> or << 55 >> or << 0.2333 >>

There is an additional expression type of this class, that is used for declaring variables: In the example before ( was used for filtering the reportData.sellings array by the property quantity greater than 0 ) :

<any class="data-declaration">
  sellings = Array.filterByProperty(reportData.sellings, "quantity", ">", 0)
</any>

It won't render anything. Add the variable sellings in the current context and will be accessible to sub contexts.

Control Expression

This is control the flow of execution, one maximum for context is allowed:

<any>
  <any class="data-context">
    <any class="data-control-expression"> ... The expression goes here ... </any>
    <any class="data-content"> ... The content we want to control ... </any>
  </any>
</any>

At the moment two types of control expressions are allowed:

| Type | Usage | Purpose | | ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | If | @if variablePropertyPath | Conditionally render the data-content block. If variablePropertyPath is true (this mean if it is not null, undefined or false), renders it | | Foreach |  @foreach element of variablePropertyPathArray | Repeat the data-content block for each element of the array and add the variable 'element' to be accessible to sub contexts |

Functions

The following are the built-in functions :

Comparation

| Name | Description | Usage | | ---- | ------------------------------------------------------------------------------------------ | -------- | | > | Compare two numbers. Returns true if first argument is greater than second one | >(a,b) | | < | Compare two numbers. Returns true if first argument is smaller than second one | <(a,b) | | <= | Compare two numbers. Returns true if first argument is greater or equals to the second one | >=(a,b) | | >= | Compare two numbers. Returns true if first argument is smaller or equals to the second one | <=(a,b) | | == | Compare two primitives. Returns true if they are equal | ==(a,b) | | === | Compare two primitives. Returns true if they are strict equal | ===(a,b) | | != | Compare two primitives. Returns true if they are not equal | !=(a,b) | | !== | Compare two primitives. Returns true if they are not strict equal | !==(a,b) |

Arithmetic

| Name | Description | Usage | | ---- | ------------------------------------------------- | ----------------- | | sum | Returns the sum of the numeric parameters | sum(a,b,c,d,....) | | sub | Returns the subtraction of the numeric parameters | sum(a,b,c,d,....) | | mul | Returns the product of the numeric parameters | mul(a,b,c,d,....) | | div | Returns the division of the numeric parameters | div(a,b,c,d,....) |

Array

| Name | Description | Usage | | ---------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | Array.sum | Sum the elements of an array | Array.sum(array) | | Array.sub | Sub the elements of an array | Array.sub(array) | | Array.mul | Multiply the elements of an array | Array.mul(array) | | Array.div | Divide the elements of an array | Array.div(array) | | Array.weightedSum | Execute weighted sum of arrays | Array.weightedSum(array1,array2,...) | | Array.mapByProperty | From an array of objects, returns an array of its own element properties. | Array.mapByProperty(array, "property") | | Array.filterByProperty | Filter an array by its own element properties. Compare the property of the element through a function. | Array.filterByProperty(array, "property", functionName, functionParam2, functionParam3, ...) |

Custom

You can add a custom function through the following API:

const { Functions, DataType } = require('report-builder');

// Function that returns primitives
Functions.add('operation', {
  function: (param1, param2, param3) => (param1 * param2) % param3,
  returns: DataType.Primitive,
});

// Function that returns complexs
// Ex: Merge two objects
Functions.add('merge', {
  function: (param1, param2) => {
    const obj = {};
    for (const prop in param1) obj[prop] = param1[prop];
    for (const prop in param2) obj[prop] = param2[prop];
    return obj;
  },
  returns: ([dataTypeParam1, valueParam1], [dataTypeParam2, valueParam2]) => {
    return {
      type: DataType.Object,
      props: [...dataTypeParam1.props, ...dataTypeParam2.props],
    };
  },
});

Support

If you would like to support my work, please buy me a coffe ☕. Thanks in advice.