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!™ functional documentation
• Impac!™ API technical documentation

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:

  curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
  sudo apt-get install -y nodejs npm

Install the project's dependencies:

  npm install

Install package via bower.

  bower install --save [email protected]: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>

Note: This section is a work-in-progress, not all services and providers that can be used to configure impac-angular are documented.

Docs on an Angular Provider Service: https://docs.angularjs.org/guide/providers

The 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.

Provides impac-angular with core data that it needs to run. This providers configuration is required and an error with be thrown if the below configurations have not been given.

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', [])
    .run( (ImpacLinkingProvider, ImpacConfigProvider) ->
    
      # 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)

    )
  )

Provides impac-angular with paths for static assets hosted by the parent application.

dataNotFound
type: String
default: null
usage: Relative path to a directive containing screenshots that are displayed as a background-image for widgets when the "data not found" case is met. The files in this directory need to be organised & named to match the widget engine path. See Impac! API docs, go to a widget and look at the engine value (e.g accounts/accounting_values/turnover).

impacTitleLogo
type: String
default: null
usage: Relative image path to the title logo

impacDashboardBackground
type: String
default: null
usage: Relative image path to default dashboard background

noWarning
type: Boolean
default: false
usage: Whether to log a warning message or not if an asset is not found

angular
  .module('yourApp', [])
  .config( (ImpacAssetsProvider) ->

    paths =
      dataNotFound: 'images/impac/data_not_found',
      noWarning: true

    ImpacAssetsProvider.configure(paths)
  )
)

Provides impac-angular with options for customising its colour theme, layout, labels, descriptions, and even enabling(showing/hiding) features.

View the theming.svc.coffee (within impac-angular) source file options object for available options.

TODO: add docs for these options.

angular
  .module('yourApp', [])
  .config( (ImpacThemingProvider) ->

    options =
      dhbConfig:
        showDhbHeading: true
        dhbHeadingText: 'Epic Reports'
      dataNotFoundConfig: 
        linkUrl: '/marketplace'

    ImpacThemingProvider.configure(options)
  )
)

• 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  

  // 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.

Copyright 2015 Maestrano Pty Ltd