This project is a User Interface allowing to access the Impac!™ API provided by Maestrano.
The user has the ability to create dashboards, and to add widgets and KPIs to these dashboards. A widget displays data calculated by the Impac!™ API, based on the user's company data aggregated by Maestrano Connec!™, while a dashboard is a visual collection of widgets.
Any contribution is very welcome and will be considered with great attention by Maestrano's developers team. You can post issues, and submit pull requests directly to the #develop branch of this repository.
Impac!™ frontend library can be included in any project based on the Maestrano platform, just fork this repository, read below for information and guidelines on using this library!
For Developers looking to create Widgets, and modify the library, have a look at DEVELOPER.md, and start developing!
Install nodejs on Ubuntu:
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs npm
Install nodejs on Mac (with homebrew):
brew install node
Install the project's dependencies:
npm install
Install package via bower.
bower install --save impac-angular=git@github.com:maestrano/impac-angular.git
Add 'maestrano.impac' module as dependancy of your angular application.
angular.module('yourApp', ['maestrano.impac'])Embed angular-impac's wrapper directive 'impacDashboard'. You can use either Element or Attribute binding
<impac-dashboard></impac-dashboard>
<!-- or -->
<div impac-dashboard></div>Impac! Angular components appearance and functionalities can be customised by the parent application. The library achieves this by using Angular Provider Services.
The Angular Provider Service allows the parent app to pass data to impac-angular by using Angular module .config() and .run() methods, while also allowing impac-angular to define defaults for these customisable options.
The user and the user's organisations is required for impac-angular to run. This is configured via the ImpacLinkingProvider.
user
type: Function
return: Promise -> { sso_session: ssoSession, ... }
usage: Retrieving user details & sso_session key for authenticating querys to Impac! API, and displaying user data e.g name.
organizations
type: Function
return: Promise -> { organizations: [ userOrgs, ... ], currentOrgId: currentOrgId }
usage: Retrieving organizations and current organization id.
angular
.module 'yourApp'
.config (ImpacLinkingProvider, ImpacConfigProvider) ->
# Instantiate the service manually as we're
# in the .config phase.
impacConfig = ImpacConfigProvider.$get()
# ImpacConfig service (an example service) could
# be a service your app provides to retrieve user
# data and organizations from MNO HUB API.
data =
user: impacConfig.getUserData
organizations: impacConfig.getOrganizations
ImpacLinkingProvider.linkData(data)Impac! Angular provides some default assets. To use these assets there are some steps that need to be made.
Assets within bower_components are not publicly accessible by browsers, so for this you will need a JS build tool (e.g gulp/grunt) to build the provided assets into your application. The default assets can found in bower_components/impac-angular/dist/images.
Once you have built the provided images to an accessible location, the default location Impac! Angular will look for these assets in runtime is /images. To configure this location, see the ImpacAssetsProvider configuration below. Some common places for this would be: /public/images, or dist/images.
To provide custom image files, see Dashboard Assets and Widget Assets.
angular
.module 'yourApp'
.config (ImpacAssetsProvider) ->
options =
defaultImagesPath: '/your/path'
ImpacAssetsProvider.configure(options)Adjust Less styling by over-riding Less Variables in the parent application.
@mgreen: #dae173;
@morange: #d6782b;
@mdarkblue: #232528;
@mgrey: #cccccc;
@mlightgrey: #999999;
@mdarkbg: #16161B;
@mblue: #358fdc;
@darkerblue: #16252c;
@darkblue: #17262d;
@darkerblue: darken(@darkblue,4%);
@darkblue2: #25333a;
@mediumblue: #626d6d;
@lightblue: #abc4c6;
@pink: #ed1e79;
@red: #FF0000;
@fluroblue: #00e5f0;
@fluroorange: #ff7300;
@flureoyellow: #fbd925;
@flurogreen: #47ff00;
@fluropink: #e01f74;
@darkgreen: #33d375;
@green: #d1e55c;
@purple: #977bf0;
@lightgray: #e6edee;
@bluegray: #abc4c6;
@bluegray2: #35464c;
@brand-success: @fluroblue;
@brand-warning: @purple;
@brand-info: @fluroblue;
@brand-danger: @fluropink;
@brand-primary: @fluroblue;
@impac-positive: green;
@impac-negative: @pink;
@impac-positive2: #3fc4ff; // lighter colors used for payables-receivables
@impac-negative2: #1de9b6; // lighter colorsused for payables-receivables
Feature configuration with the ImpacTheming Provider
dhbConfig
type: Object
usage: General dashboard options.
dhbSelectorConfig
type: Object
usage: Options for the 'Dashboard Selector' component.
dhbErrorsConfig
type: Object
usage: Options for configuring the dhb error messages.
dhbSubMenuConfig
type: Object
usage: Special cases 'sub-menu' configuration options.
dhbSettings
type: Object
usage: Configurations for the Dashboard Settings components.
angular
.module 'yourApp'
.config (ImpacThemingProvider) ->
options =
dhbConfig:
showDhbHeading: false
dhbHeadingText: 'Impac!'
designerMode:
enabled: false
dhbLabelName: 'Template'
multiCompany: false
dhbSelectorConfig:
selectorType: 'dropdown'
customTmplPath: null
accessibilityEnabled: false
addWidgetEnabled: true
addDhbEnabled: true
deleteDhbEnabled: true
pdfModeEnabled: false
dhbErrorsConfig:
firstTimeCreated:
first: 'It\'s time to add a reporting dashboard!'
second: 'In 2 clicks, you\'ll be able to visualize how your business is performing.'
note: 'Note: dashboards you create will only be accessible by you. Dashboard sharing across users will be added soon.'
empty:
first: 'Now it\'s time to select the metrics you want to see!'
second: 'Add widgets to your dashboard to help make an Impac!™ to your business.'
failed:
first: 'Ooops! Something went wrong, can you please refresh your dashboard?'
second: 'Unable to load your dashboard, please contact support or try again later.'
dhbSubMenuConfig:
myobMessage:
show: true
appLink:
show: true
url: '#/marketplace'
text: '>> Check this app on our marketplace'
dhbSettings:
inWidgetsContainer: false
syncApps:
show: -> true
productDescriptor: 'Impac!'
currency:
locked: false
createFromTemplateEnabled: false
ImpacThemingProvider.configure(options)
Provide custom image files with the ImpacAssets Provider. If customising an svg, make sure to customise it with another svg.
To use or configure the default widget asset files provided, see Using Default Assets.
impacTitleLogo
type: String
default: '/images/impac-title-logo.png'
usage: Main branding logo for the dashboard.
impacDashboardBackground
type: String
default: '/images/impac-dashboard-background.png'
usage: Dashboard Background image displayed when when no widgets are added.
angular
.module 'yourApp'
.config (ImpacAssetsProvider) ->
options =
impacTitleLogo: '/images/impac-title-logo.png'
impacDashboardBackground: '/images/impac-dashboard-background.png'
ImpacAssetsProvider.configure(options)Adjust Less styling by over-riding Less Variables in the parent application.
@impac-dashboard-padding-top: 50px;
@impac-dashboard-sm-padding-top: @impac-dashboard-padding-top * 3;
@impac-dashboard-margin-left: 100px;
@impac-dashboard-borders-color: @lightblue;
// Title
@impac-dashboard-title-color: @purple;
@impac-dashboard-title-label-color: @darkblue;
@impac-dashboard-title-label-create-color: white;
@impac-dashboard-source-color: @impac-dashboard-title-label-color;
@impac-dashboard-buttons-border-radius: 4px;
//Info-text
@impac-dashboard-info-text-color: white;
@impac-dashboard-info-text-background-color: rgba(23,38,45, 0.7);
@impac-dashboard-info-text-font-size: 25px;
@impac-dashboard-info-text-font-weight: 300;
// Dashboard Selector
// Tabs
@impac-dashboard-selector-border: 1px solid @impac-dashboard-borders-color;
@impac-dashboard-selector-tabs-margin: 0 2px 0 0;
@impac-dashboard-selector-tabs-padding: 10px 8px 10px 15px;
@impac-dashboard-selector-tabs-background-color: transparent;
@impac-dashboard-selector-tabs-active-background-color: #ffffff;
@impac-dashboard-selector-tabs-color: black;
@impac-dashboard-selector-tabs-active-color: @purple;
// Widget selector
@impac-dashboard-widget-selector-bg: #233845;
@impac-dashboard-widget-selector-text-color: white;
@impac-dashboard-widget-selector-widget-item-min-height: 55px;
// Widgets container
@impac-placeholder-border: 2px dashed @impac-dashboard-borders-color;
@impac-widgets-container-side-padding: 0px;
@impac-padding-between-widgets: 12px;
@impac-minimum-widget-size: 250px;
@impac-big-widget-size: 565px;
// Buttons
@impac-btn-shadded-bg: @darkblue;
@impac-btn-shadded-color: @mediumblue;
// Dashboard Modals
@impac-dashboard-loading-spinner: white;Feature configuration with the ImpacTheming Provider
chartColors
type: Object
usage: Provide a colour palette for the widget charts
dataNotFoundConfig
type: Object
usage: Options for the "data not found" display panel message.
widgetSelectorConfig
type: Object
usage: Options for the "widgets selector".
widgetSettings
type: Object
usage: Options for configuring various widget settings components.
angular
.module 'yourApp'
.config (ImpacThemingProvider) ->
options =
chartColors:
positive: '#3FC4FF',
negative: '#1DE9B6',
array: [
"#1de9b6",
"#7c4dff",
"#ffc928",
"#3fc4ff",
"#ff8e01",
"#c6ff00",
"#d500fa",
"#ff6e41",
"#ffeb3c",
"#ff1844"
]
dataNotFoundConfig:
content:
mainMessage: 'You don\'t seem to have any data to display on this widget...'
linkMessage: 'Add an app'
title: 'Data not found'
seeExample: 'See an example'
demoData: 'Demo data'
linkUrl: '/apps'
linkTarget: '_blank'
linkUrlCallback: null
widgetSelectorConfig:
# path to a custom html template.
path: null
# Whitelist / Blacklist widget templates
# - whitelist takes precedence over blacklist
# - when both are empty, all templates are displayed
whitelist: []
blacklist: []
widgetSettings:
histModeChoser:
currentLabels:
bls: "Balance"
pnl: "Total period"
default: "Current"
# Prefixed onto the currentLabels when date is today for hist mode chooser
todayPrefixes:
bls: "Live"
pnl: ""
default: ""
timePeriod:
showSlider: true
ImpacThemingProvider.configure(options)Provide custom image files with the ImpacAssets Provider. If customising an svg, make sure to customise it with another svg.
To use the default widget asset files provided, see Using Default Assets.
currencyConversionsIcon
type: String
default: '/images/currency-icon.png'
usage: Icon displayed to trigger conversions rate tooltips on widgets.
cashFlowLegendIcon
type: String
default: '/images/cash-flow.png'
usage: Icon displayed for the chart series representing your cashflow in the Cash Projection widget.
payablesLegendIcon
type: String
default: '/images/payables.png'
usage: Icon displayed for the chart series representing payables in the Cash Projection widget.
receivablesLegendIcon
type: String
default: '/images/receivables.png'
usage: Icon displayed for the chart series representing receivables in the Cash Projection widget.
projectedCashLegendIcon
type: String
default: '/images/projected-cash.png'
usage: Icon displayed for the chart series representing projected cash in the Cash Projection widget.
plotLineLegendIcon
type: String
default: '/images/plot-line-icon.svg'
usage: Icon displayed for the chart series using a 'line' as a series type in the widgets (Highcharts only).
areaLegendIcon
type: String
default: '/images/area-icon.svg'
usage: Icon displayed for the chart series using a 'area' as a series type in the widgets (Highcharts only).
angular
.module 'yourApp'
.config (ImpacAssetsProvider) ->
options =
currencyConversionsIcon: '/images/currency-icon.png'
cashFlowLegendIcon: '/images/cash-flow.png'
payablesLegendIcon: '/images/payables.png'
receivablesLegendIcon: '/images/receivables.png'
projectedCashLegendIcon: '/images/projected-cash.png'
plotLineLegendIcon: '/images/plot-line-icon.svg'
areaLegendIcon: '/images/area-icon.svg'
ImpacAssetsProvider.configure(options)Adjust Less styling by over-riding Less Variables in the parent application.
// Widget selector
@impac-dashboard-widget-selector-bg: #233845;
@impac-dashboard-widget-selector-text-color: white;
// Global
@impac-widget-link-color: @purple;
@impac-widget-buttons-color: @impac-widget-link-color;
@impac-widget-tile-selected-color: @impac-widget-link-color;
@impac-widget-background-color: white;
@impac-widget-border: solid 1px darken(@lightgray,10%);
@impac-widget-text-color: #5B6667;
@impac-widget-text-color-medium: lighten(@impac-widget-text-color,25%);
@impac-widget-text-color-light: lighten(@impac-widget-text-color,40%); //#acb0b1
@impac-widget-borders-color: lighten(@impac-widget-text-color-light,10%); //#f3f4f4
@impac-widget-scrollbar-color: #233845;
@impac-widget-loading-spinner: #67BBE9;
@impac-widget-reverse-color: #1E303B;
// Title
@impac-widget-title-text-color: darken(@impac-widget-text-color,5%);
@impac-widget-title-bg: @impac-widget-background-color;
@impac-widget-title-border: solid 1px @impac-widget-borders-color;
@impac-widget-title-text-transform: uppercase;
@impac-widget-title-text-size: 12px;
@impac-widget-title-border-radius: 5px 5px 0px 0px;
@impac-widget-top-buttons-color: @impac-widget-text-color-light;
// Content
@impac-widget-content-border-radius: 0px 0px 5px 5px;
@impac-widget-lines-container-max-height: 200px;
// Settings
// Param selector
@impac-widget-param-selector-color: @impac-widget-link-color;
// Hist Mode Choser
@impac-widget-hist-text-transform: uppercase;
@impac-widget-hist-text-size: 12px;
@impac-widget-hist-text-color: @impac-widget-text-color-light;
// Params picker
@impac-widget-params-picker-bg: @impac-widget-reverse-color;
@impac-widget-params-picker-unchecked-bg: #c2c4c4;
// Limit entries
@impac-widget-limit-entries-color: @impac-widget-reverse-color;
// Globals and Mixins
@impac-widget-selectable-color: @impac-widget-link-color;
// Edit settings
@impac-widget-sub-bg-color: darken(@impac-widget-background-color,6%);
@impac-widget-sub-bg-color-light: lighten(@impac-widget-sub-bg-color,5%); //f3f4f4
// Accounts Comparison
@impac-widget-accounts-comparison-lines-container-max-height: 220px;
// Sales break-even
@impac-widget-sales-break-even-bg: rgb(25,40,49);
@impac-widget-sales-break-even-text-color: #1de9b6;Alerts use Pusher.com (an external service which handles the sending of web-socket notification from our server to the browser), which required the client (Impac! Angular) is configured with a Client Key for authentication. This configuration is provided through the ImpacLinking Provider.
pusher_key:
type: String
usage: Configure Impac! Angular with a Pusher client key.
angular
.module 'yourApp'
.run (ImpacLinkingProvider) ->
data =
pusher_key: 'my-pusher-key'
ImpacLinkingProvider.linkData(data)
# BELOW IS AN EXAMPLE OF A SECONDARY WAY TO CONFIGURE THE PUSHER KEY,
# SHOULD IT NEED TO BE CONFIGURED AT A LATER STAGE THE IN APP BOOTSTRAP.
ImpacLinkingProvider.linkOptionalData({ pusher_key: 'my-pusher-key' })
)
)
Feature configuration with the ImpacTheming Provider.
dhbKpisConfig
type: Object
usage: Options for the KPIs feature.
alertsConfig
type: Object
usage: Options for the Alerts feature.
angular
.module 'yourApp'
.config (ImpacThemingProvider) ->
options =
dhbKpisConfig:
enableKpis: true
enableDatesPicker: true
alertsConfig:
enableAlerts: true
ImpacThemingProvider.configure(options)Adjust Less styling by over-riding Less Variables in the parent application.
// Kpi bar
@kpis-bar-background-color: white;
@kpis-bar-box-shadow: 0px 1px 8px -4px;
// Kpi
@kpi-background-color: white;
@kpi-triggered-border-bottom: 4px solid @brand-danger;
@kpi-max-height: 95px;
@kpi-editing-max-height: 90px; // height to be added to the @kpi-max-height when in editing mode.
@kpi-content-editing-height-buffer: 5px; // height to be minused from the @kpi-editing-max-height to even the kpi height and the kpi content height.
// Kpi top-line
@kpi-top-line-background-color: grey;
@kpi-top-line-triggered-background-color: black;
@kpi-top-line-height: 7px;
@kpi-top-line-box-shadow: none;
// kpi content
@kpi-text-color: grey;
@kpi-text-triggered-color: black;
@kpi-icon-color: grey;
@kpi-icon-triggered-color: black;
// kpi settings
@kpi-settings-focus-color: @mblue;
@kpi-settings-error-color: @brand-danger;
@kpi-settings-remove-background: #4c4749;
@kpi-settings-remove-background-hover: darken(@brand-danger, 5%);
@kpi-settings-alert-config-background: #4c4749;
@kpi-settings-alert-config-background-hover: @mblue;
@kpi-negative-alert-label-background-color: lighten(#ff0000, 30%);-
HTML Templates must not use double-quotes for strings (I'm looking at you, Ruby devs). Only html attribute values may be wrapped in double qoutes.
- REASON: when gulp-angular-templatecache module works its build magic, having double quotes within double quotes breaks the escaping.
-
We have found this angular style guide to be an excellent reference which outlines good ways to write angular. I try to write CoffeeScript so it compiles in line with this style guide.
- Slug style file naming, e.g
this-is-slug-style. - Add filename extensions to basename describing the type of component it is.
// good
some-file.svc.coffee
some-file.modal.html
// bad
some-file-svc.coffee
some-file-modal.html **IMPORTANT:** Widget folder and file names must be the same as the widget's category that is stored in the back-end, for example:
// widget data returned from maestrano database
widget: {
category: "invoices/aged_payables_receivables",
...
}Component folder & file name should be:
components/invoices-aged-payables-receivables/invoices-aged-payables-receivables.directive.coffee
The goal is to be able to work on a specific component / piece of functionality and be able to quickly isolate the javascript and css without having to dig through a 1000 line + css / js file, and also preventing styles from bleeding.
Stylesheets should be kept within the components file structure, with styles concerning that component.
Only main stylesheets should be kept in the stylesheets folder, like variables.less, global.less, and mixins.less, etc.
Component specific styles should be wrapped in a containing ID to prevent bleeding.
With widgets, there is no need for creating an id for nesting styles within. There is some code in place which adds the class dynamically to the template from the Widget's template data retrieved from the API.
To view how this works, see files components/src/widget/widget.html and component/src/widget/widget.directive.coffee.
Below is an example of the correct less closure for your widgets components less files.
// impac-angular/src/components/widgets/sales-list/sales-list.less
.analytics .widget-item .content.sales-list {
ul {}
}With other components / widgets settings components, your less should be closured like below.
// components/your-component-category/your-component.less
.analytics .your-component-category.your-component {
/* styles that wont bleed and are easily identifiable as only within this component */
ul {}
}Template to match above:
<!-- components/your-component-category/your-component.tmpl.html -->
<div class"your-component-category your-component">
<!-- html template for component -->
</div>During the build process gulp will inject @import declarations from .less files in components/ into src/impac-angular.less, concatinate all less files into dist/impac-angular.less, and compile and minify all less files into dist/impac-angular.css and dist/impac-angular.min.css.
Test should be created within service or component folders. Just be sure to mark them with a .spec extension.
Example:
components/
some-component/
some-component.directive.coffee
some-component.spec.js
services/
some-service/
some-service.service.coffee
some-service.spec.js
To run tests, first build impac-angular with gulp build. Then run gulp test.
Running gulp build will build all /dist files.
Running gulp build:dist will run a gulp clean first, then build all /dist files, ensure only the current src files are included in dist (especially relevant for images).
Copyright 2015 Maestrano Pty Ltd