README.md

File-library (Test version)

A simple javascript library for uploading, cropping, deleting files. Multiuploads.

Table of contents

• Use
• Requirements
• Features
• Main
• Getting started
• Methods
• Events
• Visual example
• Browser support
• Support
• License

Use

• jQuery v1.9.1+
• Font awesome
• Cropper
• Bootstrap

Requirements

• jQuery v1.9.1+
• Font awesome
• Cropper

Main

dist/
├── file-library.css     ( 9 KB)
├── file-library.min.css ( 7 KB)
├── file-library.js      (47 KB)
└── file-library.min.js  (31 KB)

Getting started

Quick start

For quick start options are available:

• Download the latest release
• Clone the repository: git clone Download the latest release
• Install: bower install File-library

Installation

Include files:

<link rel="stylesheet" href="/font-awesome/css/font-awesome.min.css"><!--Font-awesome is required-->
<link rel="stylesheet" href="/path/to/cropper.min.css"><!-- Cropper is required -->
<link rel="stylesheet" href="/path/to/file-library.min.css">
<script src="/path/to/jquery.js"></script><!-- jQuery is required -->
<script src="/path/to/cropper.min.js"></script><!-- Cropper is required -->
<script src="/path/to/file-library.min.js"></script>

Usage

Activation File Library

var FL = new FileLibrary(library_settings, actions, types_of_files, links, data_file_options);

Where:

library_settings - object with library settings (maxUploadSize, ln allowed)

actions - array with allowed actions ('upload', 'crop', 'remove', 'library')

types_of_files - array with allowed mimes

links - object with backend links (library, upload, crop, remove, language)

data_file_options - object with file options (aspectRatio and any other parametr)

var FL = new FileLibrary(
	{
		maxUploadSize: 1000000,
		ln: 'EN'
	},
	['upload', 'crop', 'remove', 'library'], 
	['image/*'],
	{
		library: '/api/library.json',
		upload: '/api/upload.json',
		multi_upload: '/api/multi_upload_link.json',
		crop: '/api/crop.json',
		remove: '/api/remove.json',
		language: '/js/media-library/ln/'
	},
	{
		aspectRatio: "4:3",
		groupID: 5
	}
);

Library settings - object

• maxUploadSize - maximum upload size
• ln - language of file library

You can translate ln/EN.json, create needed language and add it to ln folder.

Actions - array

You can choose needed actions from 'upload', 'crop', 'remove', 'library'.

Mime type of files - array

For example, 'image/*' or 'audio/x-aac'

Links - object of backend links:

---

Library (key='library')

Url, gets data from database and return json to show on the File library

Params: -

Returns:

Success:

{
	"img_arr": [
		{
			"ID":1,
			"src": "http://test.local/images/Chrysanthemum.jpg",
			"thumb": "http://test.local/images/Chrysanthemum-150x200.jpg",
			"alt": "Chrysanthemum",
			"width": 500,
			"height": 375
		},
		{
			"ID":2,
			"src": "http://test.local/images/Remax Bay Street logo.jpg",
			"thumb": "http://test.local/images/Remax Bay Street logo-150x200.jpg",
			"alt": "Remax Bay Street",
			"width": 500,
			"height": 221
		}
	],
	"pagination": pagination html
}

Error:

[]

---

Upload (key='upload')

Url for uploading files

Params: -

Returns:

Success:

{
	"type": "Success",
	"text": "Files was uploaded successfull.",
	"src": "http://test.local/images/Chrysanthemum.jpg",
	"thumb": "http://fl.local:8081/images/Chrysanthemum-150x200.jpg",
	"width": 300,
	"height": 400,
	"id": 1,
	"file_type": "image"
}

Error:

{
	"type": "Error",
	"text": "Error of uploading"
}

---

Multi upload (key='multi_upload')

Url for uploading files

Params: -

Returns:

Success:

[{
	"type": "Success",
	"text": "Files was uploaded successfull.",
	"src": "http://test.local/images/Chrysanthemum.jpg",
	"thumb": "http://fl.local:8081/images/Chrysanthemum-150x200.jpg",
	"width": 300,
	"height": 400,
	"id": 1,
	"file_type": "image"
}]

Error:

[{
	"type": "Error",
	"text": "Error of uploading"
}]

---

Crop (key='crop')

Url for cropping images. Backend function saves file to folder, removes old file and replaces changes in the database. Notice, names of old file and new file have to be different.

Params:

POST:

dataURL - base64 images

id - id image from Database

Returns:

Success:

{
	"type":"Success",
	"text": "Files was cropped successfull.",
	"id": 1,
	"src": "http://test.local/images/Chrysanthemum.jpg",
	"thumb": "http://test.local/images/Chrysanthemum-150x200.jpg",
	"width": 500,
	"height": 375
}

Error:

{
	"type": "Error",
	"text": "Error of cropping"
}

---

Remove (key='remove')

Url for removing files.

Params:

POST:

id - id file from Database

Returns:

Success:

{
	"type":"Success",
	"text": "Files was removed successfull."
}

Error:

{
	"type": "Error",
	"text": "Error of removing"
}

---

Language (key='language')

Url for translations folder.

Params: -

Returns: -

---

Data file options - object:

• aspectRatio: (string) You can use this parametr if you want to crop files only on specific aspectRatio. You can change this parametr in any time
• groupID: (any) You can use this parament to pass groupID to your app when any event is occured You can use any parametrs here, they will be passed to your app when any event is occured

Activation File Library

Using jQuery create arrays of action buttons:

Library buttons:

var library_buttons = [];
$('.library').each(function(i, item){
	library_buttons.push({
		'el': $(this)
	});
});

Where: el - jQuery DOM element (required)

Upload buttons:

var upload_buttons = [];
$('.upload').each(function(i, item){
	upload_buttons.push({
		'el': $(this),
		'aspectRatio': 21 / 9
	});
});

Where: el - jQuery DOM element (required) aspectRatio - aspect Ratio (optional)

Multiupload buttons:

var multi_upload_buttons = [];
$('.multi_upload').each(function(i, item){
	multi_upload_buttons.push({
		'el': $(this),
		'aspectRatio': 21 / 9
	});
});

Where: el - jQuery DOM element (required) aspectRatio - aspect Ratio (optional)

Crop buttons:

var crop_buttons = [];
$('.crop').each(function(i, item){
	crop_buttons.push({
		'el': $(this),
	});
});

Where:

el - jQuery DOM element (required)

Remove buttons:

var remove_buttons = [];
$('.remove').each(function(i, item){
	remove_buttons.push({
		'el': $(this),
	});
});

Where:

el - jQuery DOM element (required)

Activate buttons:

FL.init(
	{
		library_buttons: library_buttons,
		upload_buttons: upload_buttons,
		crop_buttons: crop_buttons,
		remove_buttons: remove_buttons
	}
);

Methods

dataFileOptionInit(options)

In order to change options use dataFileOptions. @params: options - object

var options = {
	aspectRatio: 4/3,
	/*any other parametr*/
}
FL.dataFileOptionInit(options);

To set aspectRatio for cropping images use this function. Other parametrs are used to pass them to your app when any event is occured. Example:

	var FL = new FileLibrary()...

	$('#library').on('click', function(){
		FL.dataFileOptionInit({type: 'bg_img'});
	});

	$('#thumb_library').on('click', function(){
		FL.dataFileOptionInit({type: 'thumb'});
	});


	$( document ).on( "libraryActiveFileChanged", function(event, activeImage, options){
		if(options.type == 'bg_img'){
			...
		}
		else {
			...
		}
	});

Events

libraryActiveFileChanged

This event fires when file in library is choosen

$( document ).on( "libraryActiveImageChanged", function(event, activeImage, dataFileOptions){
	console.log(activeImage);
	console.log(dataFileOptions);
});

fileUploaded

This event fires when file is uploaded

$( document ).on( "fileUploaded", function(event, uploadedFile, dataFileOptions){
	console.log(uploadedFile);
	console.log(dataFileOptions);
});

fileCropped

This event fires when file is uploaded

$( document ).on( "fileCropped", function(event, croppedImage, dataFileOptions){
	console.log(croppedImage);
	console.log(dataFileOptions);
})

fileRemoved

This event fires when file is removed

$( document ).on( "fileRemoved", function(event, removedfile, dataFileOptions){
	console.log(removedfile);
	console.log(dataFileOptions);
});

Visual example

1. Create your library page

<div class="dir_wrap">
	<a href="#" class="upload">Upload image</a>
	<a href="#" class="library">Library</a>
</div>
<div class="img_wrap">
	<img src="http://fl.local:8081/images/Chrysanthemum.jpg" alt />
	<div class="capture">
		<a href="#" class="crop" data-file-id="1" data-file-src="http://fl.local:8081/images/Chrysanthemum.jpg">Crop</a>
		<a href="#" class="remove" data-file-id="1">Remove</a>
	</div>
</div>

2. Activate file library

/*create new library object*/
var FL = new FileLibrary(
	{
		maxUploadSize: 1000000,
		ln: 'EN'
	},
	['upload', 'crop', 'remove', 'library'], 
	['image/*'],
	{
		library: 'http://test.local/api/library.json',
		upload: 'http://test.local/api/upload.json',
		multi_upload: 'http://test.local/api/multi_upload.json',
	    crop: 'http://test.local/api/crop.json',
		remove: 'http://test.local/api/remove.json',
		language: 'http://test.local/js/media-library/ln/'
	}
);

3. Init buttons

var library_buttons = [];
$('.library').each(function(i, item){
	library_buttons.push({
		'el': $(this)
	});
});

var upload_buttons = [];
$('.upload').each(function(i, item){
	upload_buttons.push({
		'el': $(this),
		'aspectRatio': 21 / 9
	});
});

var multi_upload_buttons = [];
$('.multi_upload').each(function(i, item){
	multi_upload_buttons.push({
		'el': $(this),
		'aspectRatio': 21 / 9
	});
});

var crop_buttons = [];
$('.crop').each(function(i, item){
	crop_buttons.push({
		'el': $(this),
	});
});

var remove_buttons = [];
$('.remove').each(function(i, item){
	remove_buttons.push({
		'el': $(this),
	});
});

FL.init(
	{
		library_buttons: library_buttons,
		upload_buttons: upload_buttons,
		multi_upload_buttons: multi_upload_buttons,
		crop_buttons: crop_buttons,
		remove_buttons: remove_buttons
	}
);

4. Library window

You can crop, remove, upload files. "Use file" button triggers libraryActiveFileChanged event.

Browser support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)
• Edge (latest)
• Internet Explorer 9+

Support

If you found a bug or have a feature suggestion, please submit it in the Issues tracker.

License

The plugin is available under the MIT licens.