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!

Make sure you have nodejs installed, and then:

  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.

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 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 image path to the "data not found" screenshots.

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)
  )
)

• 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