angular-evaporate
Reinforces the Evaporate
library to allow Angular
-specific usage along with all the native functionality plus additional features. Available injectables:
-
Evaporate
- native lib.
-
AngularEvaporateException
- dedicated exception handler.
-
AngularEvaporateUpload
- file upload handler:
+ calculates name, url, content type for a new upload,
+ calculates progress percent, speed and estimated time,
+ saves status updates with timestamps,
+ saves info, warning and error messages,
+ binds Evaporate
's API to the upload id,
+ updates $scope
on Evaporate
's callbacks,
+ manages dependent states (e.g. pausing, paused, resumed - only one can be true),
+ adds meta states (e.g. stopped is when either completed, canceled or failed).
-
AngularEvaporate
- uploads queue handler (extends Evaporate
):
+ manages uploads queue with an ability for every upload to be started later,
+ allows to specify a default config, which will be merged with every consequent upload's one,
+ allows to specify a custom naming function, where current instances of AngularEvaporateUpload
and AngularEvaporate
are available.
-
angular-evaporate
- directive:
+ lazy mode option - explicit uploading start,
+ same files uploading option - clean file input after every select.
Get
- Install
```bash
npm install --save angular-evaporate
```
- Include
```html
<script src="node_modules/angular-evaporate/lib/angular-evaporate.min.js"></script>
```
- Depend
```javascript
angular.module('yourApp', ['angular-evaporate']);
```
Use
- Inject
```javascript
yourApp.controller('yourCtrl', ['$scope', 'AngularEvaporate',
function ($scope, AngularEvaporate) {...}
]);
```
- Init
```javascript
$scope.ae = new AngularEvaporate(...);
```
`AngularEvaporate` extends [`Evaporate`](https://github.com/TTLabs/EvaporateJS), so its constructor accepts the same arguments.
- Directive
```html
<div ng-controller="yourCtrl">
<input type="file" multiple angular-evaporate="ae"/>
</div>
```
Test
npm install && npm test
Example
- Configure
Follow the [Evaporate](https://github.com/TTLabs/EvaporateJS)'s instructions to set up an `S3` bucket, then accordingly update `AngularEvaporate`'s constructor parameters in the `example/index.js` file and `AWS_SECRET_KEY` value in the `example/server.js` file.
- Run
```bash
npm install && npm start
```
- Check
```
http://localhost:8080/example
```
- Hint
Always use server-side validation for incoming requests to the signerUrl
, because in this simple example anyone could send you anything he wanted and just get it signed with your secret key.
AngularEvaporate
class
Extends Evaporate
, therefore accepts the same constructor arguments and provides the same functionality, but also introduces additional features. To not interfere with possible future versions, all added object keys start from the $
symbol.
Properties
Property |
Type |
Usage |
Description |
$uploads |
Array |
essential |
instances of AngularEvaporateUpload |
$apply |
Function |
recommended |
set this to your $scope.$apply.bind($scope) to update UI when needed |
$config |
Object |
optional |
default config for an upload (explicitly specified properties on a consequent call of $enqueue() or $add() will have higher priority) |
$namer |
Function |
optional |
custom upload naming function (instance of AngularEvaporateUpload as an input argument, instance of AngularEvaporate as this), default one just returns a filename |
$speeder |
Function |
optional |
custom speedometer function (input: current speed in bytes/second, output: string in readable format, like '1.23 MB/s') |
$url |
String |
cautious |
custom url of the bucket's root directory |
$slothmode |
Boolean |
optional |
(directive) lazy mode option - explicit uploading start |
$rinserepeat |
Boolean |
optional |
(directive) same files uploading option - clean file input after every select |
API
Function |
Arguments |
Result |
Description |
$enqueue |
same as for Evaporate.add() |
AngularEvaporateUpload |
create an upload and append it to the queue |
$dequeue |
AngularEvaporateUpload |
Number - index in $uploads |
remove an upload from the queue |
$start |
AngularEvaporateUpload |
same as from Evaporate.add() |
start uploading an already queued upload |
$add |
same as for Evaporate.add() |
same as from Evaporate.add() |
enqueue and start uploading immediately |
Function |
Arguments |
Result |
$startAll ,
$cancelAll ,
$dequeueAll |
- |
- |
$pauseAll ,
$resumeAll |
same as for Evaporate[fn](undefined, ...) , where fn is pause or resume |
same as from Evaporate[fn](undefined, ...) |
AngularEvaporateUpload
class
Properties
Property |
Type |
Usage |
Description |
name |
String |
optional |
desired path from bucket's root directory |
contentType |
String |
optional |
MIME type |
$id |
Number |
read only |
result of the Evaporate.add() |
$url |
String |
read only |
full url of the file when it's uploaded |
$started ,
$paused ,
$resumed ,
$pausing ,
$cancelled ,
$complete ,
$info ,
$warn ,
$error ,
$progress |
Number |
optional |
Date.now() of every Evaporate 's callback fired |
$stopped |
Number |
optional |
value of either $complete , $cancelled or $error |
$infoMsg ,
$warnMsg ,
$errorMsg |
String |
optional |
input parameter of the corresponding callback |
$percent |
Number |
optional |
current uploading progress |
$seconds |
Number |
optional |
estimated elapsed time |
$speed |
String |
optional |
average upload speed |
API
Function |
Arguments |
Result |
$start |
- |
same as from Evaporate.add() |
$pause ,
$resume ,
$cancel |
same as for the corresponding Evaporate[fn](id, ...) |
same as from the corresponding Evaporate[fn](id, ...) |