npm:media-api-client

README

Media-API Client

This is the browser client to upload files to the TCS Media-API.

You can use it with general js loading or require.js.

Installation

To install the client just place the script build/mediaapiclient.js or build/mediaapiclient.min.js to your client code.

JS Init

Then init it by calling:

new window.MediaApiClient( dragSelector, resultsSelector, options );

Examples

With internal GUI

new window.MediaApiClient( "#clientEl", "#results", { host: "@@host", domain: "@@domain", accesskey: "@@accesskey" } );

No File Object GUI

new window.MediaApiClient( "#clientEl", { host: "@@host", domain: "@@domain", accesskey: "@@accesskey" } );

Predefine the defaults

window.MediaApiClient.defaults( { host: "@@host", domain: "@@domain", accesskey: "@@accesskey" } )
    
new window.MediaApiClient( "#clientEl", "#results" )
new window.MediaApiClient( "#clientEl2" )

Note: You have to replace the placeholders prefixed with @@

Arguments

Options can be used as JS options or data attributes. Expect the function options

dragSelector ( String|DOM|jQuery-Obj, required ): A selector, dom-element or jQuery object containing the drag space. Within this element a file input element ( optional selector options.inputclass ) needs to be found.
resultsSelector ( null|String|DOM|jQuery-Obj ): Optional selector to show a file rendering with status bar. But you can also do this your own by listening to the events. If you set this to null the client acts in non-GUI mode and you have to listen to the events.
options.host ( String, required ): The media Api host
options.domain ( String, required ): The domain to upload to
options.accesskey ( String, required ): The domains access key
options.maxsize ( Number, default 0 ): Maximum size of a file in kb. 0 means no restriction.
options.maxcount ( Number, default 0 ): Maximum count of files. 0 means no restriction.
options.ttl ( Number, default 0 ): File ttl to invalidate file after n seconds. 0 means forever.
options.width ( Number, default 0 ): Recalc a image to this width. If you define width and height the image could be disorted. If you only define width > 0 the resizing will preserve the aspect ratio.
options.height ( Number, default 0 ): Recalc a image to this height. If you define width and height the image could be disorted. If you only define height > 0 the resizing will preserve the aspect ratio.
options.tags ( Array ): File tags to add to the media-api object.
options.properties ( Object, default { filename: "{FileApi.name}" } ): Property object to add to the media-api object
options.content-disposition ( String ): the content disposition e.g. attachment; filename=friendly_filename.pdf
options.acl ( String, default public-read; enum:( public-read, authenticated-read ) ): The S3 access control.
options.inputclass ( String ): Optional css class to find the file input
options.accept ( String ): Mimetyps to accept (See: HTML file accept).
options.keyprefix ( String default clientupload ): Key prefix
options.autostart ( Boolean, default true ): Start upload on drop/change
options.requestSignFn ( Function ): Function to generate the signature. This Method should be redefined by you, because the standard Media-API signing will be IP filtered. So you have to tunnel it trough your own server or generate a valid signature within your server. For details see the Signing section.
options.resultTemplateFn ( Function ): Template function to display the File state.
options.cssfileelement ( String default file col-sm-6 col-md-4 ): Css class added to a new file element
options.cssdroppable ( String default dropable ): Css class added to dragSelector on successful drag'n'drop init
options.csshover ( String default hover ): Css class added to dragSelector on hover with a file drag
options.cssprocess ( String default process ): Css class added to dragSelector during a active upload
options.cssdisabled ( String default disabled ): Css class added to dragSelector if the maxcount has exceeded

HTML Structure

complete:

With internal File object rendering.

<label id="clientEl" class="mediaapiclient" for="clientElselect">
    <b class="dropactive"><span>click to select or drop files here</span></b>
    <b class="dropfallback"><span>Your Browser is not supported. Please use a modern Browser.</span></b>
    <input type="file" id="clientElselect" name="clientEl" multiple="multiple" />
    <div class="results"></div>
</label>

minimal:

<label id="clientEl"for="clientElselect">
    <input type="file" id="clientElselect" name="clientEl" />
</label>

Defaults

It's possible to predefine all options by using the MediaApiClient.defaults() method.

Usually you would use it to store the options host, domain and accesskey for all client instances. But it's possible to overwrite it with the options or html-data-attributes for every instance.

Components

You can write your own sub components like:

MediaApiClient.EventEmitter: Internal event emitter.
MediaApiClient.Base: Basic class with general error handling.
MediaApiClient.File: Handling of a single file upload.
MediaApiClient.FileView: File rendering to show the process.

by replacing and/or extend them.

Signing

You have to do the signing your own, because the sign endpoint of the media-api will be restricted to a list of ip's. The upload itself will be done directly to the Media-API.

To realize this you have to overwrite the function option.requestSignFn and add some server side code.

Clientside

You have to redefine the option.requestSignFn to request your own server to be abele to create the signature within your own server.

The following example shows a possible solution with a call to the server that generates the signature itself:

    myRequestSignFn = function( domain, accesskey, madiaapiurl, key, json, cb ){
        var mySignUrl, postData, postReq;
        var mySignUrl = "http://www.myservice.com/sign-media-api";

        var postData = {
            url: madiaapiurl,
            key: key,
            json: JSON.stringify( json )
        };

        var postReq = jQuery.post( mySignUrl, postData, null, "text" );
        
        postReq.done( function( signature ){
            cb( null, signature )
        } );

        postReq.error( function( error ){
            cb( error )
        } );
    }

Serverside

There are two variants to do the signing.

Use the Media-API Sign Endpoint

After your server has been added to the secure ip list, you can use the media-api sign ( /mediaapi/{domain}/sign/{accesskey} ) endpoint.

POST /mediaapi/{domain}/sign/{accesskey}

URL-Parameter

domain ( String ): Your target domain ( passed to option.requestSignFn function )
url ( String ): The domain/bucket accesskey ( passed to option.requestSignFn function )

Form-Parameter

json ( String ): A stringified JSON of the relevant media-api parameters ( passed to option.requestSignFn function )
key ( String ): The media-api object key ( passed to option.requestSignFn function )
url ( String ): The media-api request url you want to call ( passed to option.requestSignFn function )

You will get a simple text response with the signature

Example:

Request:

POST /mediaapi/mydomain/sign/123456789
Content-Type: application/x-www-form-urlencoded

json = {"blob":true,"acl":"public-read","content_type":"image/jpeg"}
key = clientupload_rxv450jpg_1402487116_1	
url	= http://192.168.1.8:8005/mediaapi/mediaapitest/clientupload_rxv450jpg_1402487116_1

Response:

123456789ABCEFGHIJo9ZFeQ6ds=

Generate the signature yourself

To generate the signature your own you have to send the json and madiaapiurl passed to the option.requestSignFn function to your server. Therefor you have to know the domain/bucket secret within your server.

The signature itself has to be generated like the following js-code example:

    generateSignature = function( domainSecretKey, url, stringifiedJSON ){
        var stringToHash, shasum;
        
        // add the stringified JSON to the url if exsitend
        if( stringifiedJSON != undefined and stringifiedJSON.length >= 0 ){
            stringToHash = url + stringifiedJSON;
        } else {
            stringToHash = url;
        }
        
        // create a SHA1 hash with the domain/bucket secret
        shasum = crypto.createHmac( "sha1", domainSecretKey );
        shasum.update( stringToHash );
        
        // create the base64 encoded signature 
        return shasum.digest('base64');
    };

Client Object `ClientInstance = new MediaApiClient()`

The Client to start and init uploads

You cann get the current instance of the MediaApiClient by reading the dom-elements jQuery data attribute mediaapiclient.

Example

myClient = jQuery( "#clientEl" ).data( "mediaapiclient" )

Methods

`ClientInstance.upload( files )`

Start the upload manually.

Arguments

files : ( FileAPI-Object[] ): An array of file API objects.

`ClientInstance.deleteFile( key, revision, cb )`

Delete a file out of the media-api directly from the client.

Arguments

key : ( String ): The file key
rev : ( String ): The file's revision
cb : ( Function ): the callback. You'll receive a possible error and, on success, the deleted entity like { rows:[ { ... the deleted entity ... } ] }

`ClientInstance.sign( opt, cb )`

Delete a file out of the media-api directly from the client.

Arguments

opt : ( Object ): The file key
- url: ( String; required ): The complete url to sign
- key: ( String; required ): The file key to sign
- domain: ( String; default = {options.domain} ): the domain for the signature
- accesskey: ( String; default = {options.accesskey} ): the accesskey for the signature
- json: ( Object; optional ): Additional data for siging
cb : ( Function ): the callback. You'll receive a possible error and, on success, the signed url and the signature itself ( err, surl, signature )

`ClientInstance.disable()`

Disable the client. This will stop the Client from accepting new files

`ClientInstance.enable()`

Enable the client.

`ClientInstance.abortAll()`

Abort all file uploads

CSS

The drag element will offer it's current state by some css classes added or removed.

hover: Detected a Fiel Drag'n'Drop hover over the dragSelector element.
process: Files are currently uploading.
disabled: The Client is currently disabled

Events

start ():
One or more uploades started.

finish ( count ):
All currently running uploads are done.

count ( Number ): The count of finished uploads since the last .finish` event

progress ( precent, states, fileCount ):
The progress over all files

precent ( Number ): The precentage of the currently uploads over all active uploads ( 0-100 )
states ( Number[] ): A Array of file states
- states[0]: Count of started but waiting file uploads
- states[1]: Count of files currently uploading
- states[2]: Count of files done
- states[3]: Count of file failed to upload. Details see error or file.error event
fileCount ( Number ): The count of files in the queue. It's the same as a sum of all states

file.new ( file ):
New file dropped/selected.

file ( File ): The file object

file.content ( file, key, json ):
Event to hook a data manipulation. So you are able to change the object's key and JSON data before signing and uploading

file ( File ): The file object
key ( String ): The generated key
json ( Object ): The media-api json data
- json.blob ( Boolean ): Do not manipulate this! Flag to define a regular file upload
- json.acl *( String, default public-read; enum:( public-read, authenticated-read ): The S3 access control.
- json.ttl *( Number, default 0): File ttl to invalidate file after n seconds. 0 means forever.
- json.width *( Number, default 0): Recalc a image to this width. If you define width and height the image could be disorted. If you only define width > 0 the resizing will preserve the aspect ratio.
- json.height *( Number, default 0): Recalc a image to this height. If you define width and height the image could be disorted. If you only define height > 0 the resizing will preserve the aspect ratio.
- json.properties ( Object ): Optional properties object
- json.tags ( Array ): An Array of Strings to set object tags. The Media-API can query by this tags.
- json.content_type ( String ): The files content type read by the browser file API
- json.content-disposition ( String ): the content disposition e.g. attachment; filename=friendly_filename.pdf

file.upload ( file ):
File upload started

file ( File ): The file object

file.progress ( file, progress ):
File progress status

file ( File ): The file object
percent ( Number ):The uploaded progress in precent of the file

file.done ( file ):
File upload done

file ( File ): The file object

file.aborted ( file ):
File upload aborted

file ( File ): The file object

file.invalid ( file, validation ):
File upload invalid

file ( File ): The file object
validation ( Array ): Array of invalid keys ( maxsize: File too big; accept: invalid type )

file.error ( file, error ):
File error

file ( File ): The file object
error ( Error ): the error object

file.hover ():
User hovered with a file

File Object `FileInstance = new File()`

For every dropped/selected File a FileObject is generated witch initializes the signing and upload.

Methods

`FileInstance.start()`

Start the upload of a file. Only relevant ist options.autostart is set to false

Returns

( File-Obj ): Itself

`FileInstance.abort()`

Abort the signing/upload of a file

Returns

( File-Obj ): Itself

`FileInstance.getState()`

Returns the current state ( new, start, signed, upload, progress, done, aborted, invalid, error )

Returns

( String ): Current State

`FileInstance.getResult()`

The the Fileresult or null until it's not done.

Returns

( null|Object ): Returns null if file not done yet. Otherwise it returned a result object ( url: The Url to the final file; hash: The filehash; key: The generated file key; type: The file mimetype ).

`FileInstance.getProgress( asFactor )`

Returns the current file progress state.

Arguments

asFactor : ( Boolean default = false ): Return the progress as factor from 0 to 1. Otherwise it will return a percentage from 0 to 100

Returns

( Number ): The factor or percentage

`FileInstance.getName()`

Returns the file name.

Returns

( String ): The file name

`FileInstance.getType()`

Returns the file type.

Returns

( String ): The file type

`FileInstance.getData()`

Returns a object of all current data ( e.g. for rendering ).

Returns

( Object ):

name ( String ): The input field name
file ( String ): The return of getName()
idx ( Number ): The index number. A running number for all files of this client instance.
state ( String ): The return of getResult()
result ( null|Object ): The return of getResult( false )
options ( Object ): The client options
invalid_reason ( null|Array ): The invalid reasons for state invalid ( maxsize: File too big; accept: invalid type )
error ( null|Error ): The errro details for state error

Events

start ():
File upload started

state ( state ):
New file dropped/selected.

state ( String ): The current file state ( new, start, signed, upload, progress, done, invalid, error )

content ( key, json ):
Event to hook a data manipulation. So you are able to change the object's key and JSON data before signing and uploading

key ( String ): The generated key
json ( Object ): The media-api json data
- json.blob ( Boolean ): Do not manipulate this! Flag to define a regular file upload
- json.acl *( String, default public-read; enum:( public-read, authenticated-read ): The S3 access control.
- json.ttl *( Number, default 0): File ttl to invalidate file after n seconds. 0 means forever.
- json.width *( Number, default 0): Recalc a image to this width. If you define width and height the image could be disorted. If you only define width > 0 the resizing will preserve the aspect ratio.
- json.height *( Number, default 0): Recalc a image to this height. If you define width and height the image could be disorted. If you only define height > 0 the resizing will preserve the aspect ratio.
- json.properties ( Object ): Optional properties object
- json.tags ( Array ): An Array of Strings to set object tags. The Media-API can query by this tags.
- json.content_type ( String ): The files content type read by the browser file API
- json.content-disposition ( String ): the content disposition e.g. attachment; filename=friendly_filename.pdf

signed ():
File has been signed

progress ( percent, event ):
File error

percent ( Number ):The uploaded progress in precent ( 0-100 )
event ( Event ):Xhr Event

done ():
File upload done

aborted ():
File upload aborted

invalid ( validation ):
File upload invalid

validation ( Array ):Array of invalid keys ( maxsize: File too big; accept: invalid type )

error ( error ):
File error

error ( Error ):the error object

OPEN Features

currently no features are planed. Please create a issue if you need a new feature.

Release History

Version	Date	Description
v1.3.4	2016-10-24	Move peerDependencies to explicit dependencies and updated deps
v1.3.3	2016-07-14	Fixed #8 and optimized accepts handling
v1.3.2	2016-06-27	Fixed error handling for failed signature requests
v1.3.1	2016-03-29	Fixed an issue when dropping with non file elements
v1.3.0	2016-02-24	Added `quality` option ( see #4 )
v1.2.0	2016-02-23	Added `start` event and `count` argument for `finish` event ( see #5 ); Added client `progress` event to be able to show a cumulated progressbar ( see #6 ); Optimized error handling
v1.1.2	2015-10-02	fixed is function call
v1.1.1	2015-10-02	added automatic release
v1.1.0	2015-10-02	optimized singing; added `deleteFile( key, rev, cb )` method to delete a file directly from the client.
v1.0.4	2015-09-21	small changes to set file object class and added `file.hover` event
v1.0.3	2015-09-17	made module public
v1.0.1	2015-09-17	optimized common js usage to not bundle peer dependencies
v1.0.0	2015-09-17	modern development env, by using browserify. Removed jQuery dependency by using `domel` and `xhr`
v0.4.4	2014-09-23	added options to change the internal css classes
v0.4.3	2014-09-23	some small fixes and options plus optimized read me.
v0.4.2	2014-09-16	fixed multiple upload of same file.
v0.4.1	2014-06-13	Optimized readme
v0.4.0	2014-06-13	Added file `abort`; client `abortAll`; Added event hook `content` and `file.content` to manipulate the key and JSON data
v0.3.0	2014-06-11	Added media api arguments like `ttl`, `tags`, `properties`, `acl` and `content-disposition`; Added details docs and some code optimisations
v0.2.0	2014-06-10	Gui less version
v0.1.0	2014-06-09	Initial version
v0.0.0	2014-06-09	Dev version

Related Projects

Name	Description
media-api	The media api server

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Usage no npm install needed!

README

Media-API Client

Installation

JS Init

Examples

Arguments

HTML Structure

Defaults

Components

Signing

Clientside

Serverside

Use the Media-API Sign Endpoint

Generate the signature yourself

Client Object ClientInstance = new MediaApiClient()

Methods

ClientInstance.upload( files )

ClientInstance.deleteFile( key, revision, cb )

ClientInstance.sign( opt, cb )

ClientInstance.disable()

ClientInstance.enable()

ClientInstance.abortAll()

CSS

Events

File Object FileInstance = new File()

Methods

FileInstance.start()

FileInstance.abort()

FileInstance.getState()

FileInstance.getResult()

FileInstance.getProgress( asFactor )

FileInstance.getName()

FileInstance.getType()

FileInstance.getData()

Events

OPEN Features

Release History

Related Projects

The MIT License (MIT)

Client Object `ClientInstance = new MediaApiClient()`

`ClientInstance.upload( files )`

`ClientInstance.deleteFile( key, revision, cb )`

`ClientInstance.sign( opt, cb )`

`ClientInstance.disable()`

`ClientInstance.enable()`

`ClientInstance.abortAll()`

File Object `FileInstance = new File()`

`FileInstance.start()`

`FileInstance.abort()`

`FileInstance.getState()`

`FileInstance.getResult()`

`FileInstance.getProgress( asFactor )`

`FileInstance.getName()`

`FileInstance.getType()`

`FileInstance.getData()`