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
```
2. Include
```html
<script src="node_modules/angular-evaporate/lib/angular-evaporate.min.js"></script>
```
3. Depend
```javascript
angular.module('yourApp', ['angular-evaporate']);
```
Use
- Inject
```javascript
yourApp.controller('yourCtrl', ['$scope', 'AngularEvaporate',
function ($scope, AngularEvaporate) {...}
]);
```
2. Init
```javascript
$scope.ae = new AngularEvaporate(...);
```
`AngularEvaporate` extends [`Evaporate`](https://github.com/TTLabs/EvaporateJS), so its constructor accepts the same arguments.
3. 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
```
3. Check
```
http://localhost:8080/example
```
4. 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, ...) |