From 5ab8dde63f34e15cbf1e7ba0f9779ddabe278fdf Mon Sep 17 00:00:00 2001 From: Barak Date: Tue, 28 Apr 2015 20:23:49 +0100 Subject: [PATCH] updated documentation and project page --- index.html | 414 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 414 insertions(+) create mode 100644 index.html diff --git a/index.html b/index.html new file mode 100644 index 0000000..0110e3a --- /dev/null +++ b/index.html @@ -0,0 +1,414 @@ + + + + + ngPromiseStatus by Barak Chamo + + + + + + + + + + + Fork me on GitHub + +
+
+

ngPromiseStatus promise-aware UI elements.

+
+

A collection of Angular.js promise-aware directives and UI elements for your project

+

by Barak Chamo

+
+
+ +
+
+
+
+

ngPromiseStatus is a collection (starting with statusButton) of promise-aware Angular directives that make it easy to bind UI elements to the progress and eventual outcome of a promise.

+ + +

Examples

+ +

statusButton

+

Simple usage

+

This is a simplest use of the directive with only a promise (or array of) passed (and some default styles).

+
+
+
+
+ + Success + +
+
+ + Error + +
+
+ + Value (immediate) + +
+
+
+ +

+ +

Custom Status Classes

+

You can pass custom classes to be applied for each stage of the promise (progress, succcess and error). It plays nicely with Bootstrap btn classes

+
+
+
+
+ + Success + +
+
+ + Error + +
+
+ + Error + Delay + +
+
+
+ +

+ +

Promise Values

+

The directive exposes several scope properties to the button's content (see docs). You can use them to give extra info on the promise's status.

+
+
+
+
+ + Success {{$value}} + +

Resolved with value 'Done!'

+
+
+ + Error {{$value}} + +

Rejected with error 'Error!'

+
+
+ + Error + Delay {{$value}} + +

Rejected with error 'error!'

+
+
+
+ + + +

+

Documentation

+ + +

Installation

+

You can install through bower:

+ 
bower install ng-promise-status
+

or through npm:

+ 
npm install ng-promise-status
+

or download the latest version from GitHub

+ + +

Setup

+

To get started include ngPromiseStatus as a dependency in your angular app:

+ 
var app = angular.module('myApp', ['ngPromiseStatus']);
+

and you're good to go!

+ + +

statusButton

+

Basic Use

+

The statusButton directive can be used by simply using the directive as a tag or attribute and passing a promise (or array of).

+

When the button is clicked an internal handler is fired and assigns a promise handler to the assigned promise. Note that for that reason + new promises are only detected on click.

+

Any ng-click handler assigned to the element will be called before the internal handler so you can easily use the same 'click' event to both assign a promise in your controller and for it to be detected by the button.

+ + +

Here's an example:

+
+
+
+

Result:

+
+ + Success + +
+
+
+

Template:

+ 
+<status-button 
+  ng-click="setSuccessPromise()" 
+  promise="successPromise">
+  <span>Success</span> 
+</status-button>
+
+

Controller:

+ 
+// Create a new promise that will succeed in 3 seconds
+$scope.setSuccessPromise = function(){
+  // Set $scope.promise with a new promise
+  $scope.successPromise = $q.defer();
+
+  // React to promise in controller
+  $scope.successPromise
+    .promise
+    .then(function(){
+      console.log('Done from controller');
+    });
+
+  // Set a timeout for 3 seconds and resolve
+  $timeout(function(){
+    $scope.successPromise.resolve('Done!');
+  }, 3000);
+};
+
+
+
+
+ + +
+ + +

Multiple Promises (and other valid inputs)

+

The directive is built to work with multiple type of inputs:

+
+
promises
+
The promise from a $q.defer().
+
deffers
+
The deffered itself, saves the need of saving multiple references on scope.
+
promise arrays
+
An array of promises or deffereds.
+
other values
+
Any other value will not break but rather resolve immediately (implements $q.when).
+
+ + +
+ + +

CSS Classes

+

By default, the directive applies 4 classes to the button depending on the state of the promise:

+
+
idle
+
There is no current promise in progress.
+
+
inprogress
+
There promise is still in progress, inprogress is used instead of progress so that it doesn't clash with Bootstrap progress bars.
+
+
success
+
The promise was resolved.
+
+
error
+
The promise was rejected.
+
+ +

ngPromiseStatus intentionally doesn't rely on any additional CSS files or required styling. It provides an easy interface in the form of class management that allows you to easy interact with promises using your existing styles and with no additional bloat to your project.

+ +
+ + +

Custom Configuration

+

You can configure a few key features of statusButton - classes applied on promise stages, delay and disable:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedefaultdetails
idle_classstringidleThe initial class applied to the button and will applied after completion if a delay is specified.
progress_classstringinprogressThe class that will be applied to the button whenever a promise is in progress.
success_classstringsuccessThe class that will be applied to the button when a promise is resolved (completed successfully).
error_classstringerrorThe class that will be applied to the button when a promise is rejected (resulted in an error).
progress_disablebooleantrueA toggle that determines if the button will be disabled when a promise is in progress.
delaynumber0The time (in milliseconds) it takes for the button to return to idle state upon promise completion (either success or error). 0 will not return to idle.
+ + +

Here's an example for custom configuration using Bootstrap classes and a 2s delay:

+
+
+
+

Result:

+
+ + Custom + Delay + +
+
+
+

Template:

+ 
+<status-button 
+  ng-click="setButtonPromise()" 
+  promise="buttonPromise">
+  options="buttonPromise">
+  <span>Success</span> 
+</status-button>
+
+

Controller:

+ 
+// Define your custom configuration
+$scope.buttonConfig = {
+  success_class:  'btn-success',
+  error_class:    'btn-danger',
+  progress_class: 'btn-warning',
+  idle_class:     'btn-default',
+  delay:          2000
+};
+
+// Create a new promise that will succeed in 3 seconds
+$scope.setButtonPromise = function(){
+  // Set $scope.promise with a new promise
+  $scope.buttonPromise = $q.defer();
+
+  // React to promise in controller
+  $scope.buttonPromise
+    .promise
+    .then(function(){
+      console.log('Done from controller');
+    });
+
+  // Set a timeout for 3 seconds and reject
+  $timeout(function(){
+    $scope.buttonPromise.reject();
+  }, 3000);
+};
+
+
+
+
+ + +
+ + +

Scope Properties

+

The directive exposes special scope properties to the button's content that allow you to customize the button's content and interact with the promise's values and state.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedetails
$statusstringThe status of the promise, same as the default class names: idle, inprogress, success and error
$valueanyWhatever value is passed upon resolution or rejection of the promise. If an array of promises is used, $value will be an ordered array of said whatevers.
$donebooleanA convenience boolean that indicates if a promise is in progress.
$classstringThe class that is currently applied, overwritten with your custom configuration if provided.
+ + +

Here's an example of using scope properties inside the button (promise is rejected with 'Error!'):

+
+
+
+

Result:

+
+ + What's up? {{$value}} + +
+
+
+

Template:

+ 
+<status-button 
+  ng-click="setButtonPromise()" 
+  promise="buttonPromise" 
+  options="bootstrapConfig">
+  <span>Success {{$value}}</span>
+</status-button>
+
+
+
+
+ + + + +
+
+
+
+ + + + + + + \ No newline at end of file