Noncollinear Perpendicular Microcrystalline
    Wondering what’s next for npm?Check out our public roadmap! »

    js-template-builder

    1.0.5 • Public • Published

    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.

    Install

    npm i js-template-builder

    DownloadsWeekly Downloads

    9

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    71 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar