Bolt Layouts and Impac! Angular 2 Templates

Owned by Cesar Tonnoir (Unlicensed)
Last updated: Dec 08, 2017 by Xaun Lopez (Unlicensed)
3 min read

Context

With the new Bolt architecture, Impac! widgets API is able to render unified responses, sharing common pivot-formats called "layouts".

While writing the new Impac! Angular v2 library, the goal is to make the most of this capability: instead of using one custom front-end component per widget endpoint (as per the v1), we want to define generic templates, each of them based on one or several layouts.

Benefits

  • Widgets faster to develop. Creating a new widget will require only back-end development, regardless of the source Bolt or the kind of data displayed.
  • Front-end easier to maintain. Fixing or improving one template in the front-end will automatically apply the changes to all the widgets compatible with it. The code of the library will also be a lot lighter.
  • Scalable reporting Framework. Any developer (enterprise customer) could easily create new templates for their existing widgets. On the other hand, any third-party creating a new Bolt would automatically have the possibility to visualize the output on Impac! Angular.
  • Better usability. Given the flexibility or the layouts / templates couple, it is way easier for us to let the user choose what template he wishes to use when adding a widget to his dashboard.

Porting

Generic Layouts

Each widget will support one or several layouts. After the widget has computed its metrics, it is going to "fill" the supported layouts required by the user (as specified in the request to the API), and render all the layouts with the response.

Each layout will have its own structure, regardless of the widget using it. Each widget has to advertise what are its supported layouts. This information can be retrieved by calling the INDEX endpoint of the widgets API (no authentication required).

Here are the potential layouts identified so far:

  • highstocks
    • Returns a highstocks object (eg: line chart with time series)
  • highcharts
    • Returns a highcharts object (eg: pie chart) - to be grouped with highstocks?
  • plain_chart
    • Similar to highstocks, excluding HighCharts API specific options (colors, zones, etc.)
  • figure
    • Returns one or two computed metrics (with currencies, legend, etc.)
  • table
    • Returns a list of records (columns + rows)
  • grouped_table
    • Returns a nested list of records (columns + collapsible rows)

Generic Templates

A "template" is an angular component that takes one or several layouts as a data source to render a widget.

For example, the widget endpoint "balance_sheet" may specify it supports the layout "grouped_table", in which case when a user tries to add a Balance Sheet widget to his dashboard, Impac! Angular will fetch the widget content (structured in a grouped_table layout), and inject it to the grouped-table template component.

Some templates will be made of combinations of layouts. For example, the template ratio needs a widget compatible with the layouts "grouped_table" and "highstocks" to render.

Here are the potential templates identified so far, with the corresponding existing widgets (A=Accounting, I=Invoicing, H=HR, S=Sales):

  • highstocks
    • A - Cash Balance
    • A - Cash Projection (custos: simulation mode, set threshold, click on bar)
    • S - Aged Sales
    • S - Growth per product (custo: ability to select a product)
  • highcharts
    • A - Assets / Liabilities summary (custo: ability to select an account)
    • A - Accounts Comparison (custo: ability to select several accounts)
    • I - Top Customers Summary
    • S - Sales Cycle
    • S - New vs Existing Customers
    • S - Sales summary (custo: ability to select a filter)
  • highcharts-plus-highstocks
    • A - Expense to Total Expenses 
    • A - Expense to Turnover 
    • A - Expenses / Revenue
  • figure
    • H - Leave Balance
    • H - Superannuation Balance
  • figure-plus-highstocks
    • A - EBITDA
    • A - Overall Turnover
    • A - Account Balance (custo: ability to select an account)
    • A - Payables / Receivables
    • H - Payroll Taxes
    • S - Gross margin
  • ratio (other template using figure + highstocks layouts)
    • A - Current Ratio
    • A - Debt Service Ratio
  • collapsable-figure-plus-highstocks (other template using figure + highstocks layouts)
    • H - Salaries Summary
    • H - Workforce Summary
  • grouped_table-plus-highstocks
    • A - Profit and Loss
    • A - Aged Payables and Receivables
    • H - Payroll Summary
    • S - Sales Comparison
    • S - Sales Forecast
    • S - Team Performance
  • grouped_table
    • A - Balance Sheet
    • A - Detailed accounts classes
    • H - Timesheets
  • funnel (other template using the grouped_table layout) / existing template should be reworked completely
    • S - Leads Funnel
    • S - Opportunities Funnel
  • table
    • I - Invoices List
    • I - Bills List
    • H - Employees List
    • S - Top Customers by Sales
    • S - Leads List
    • S - Sales List
  • details (other template using the table layout)
    • H - Employee Details
    • S - Customer Details
  • ? (very specific templates)
    • A - Custom Calculation
    • S - Break-even
    • S - Net Sales
    • S - Number of Leads
    • S - Sales by price range
    • S - Top opportunities