Slim Image Cropper

<div class="slim"
     data-service="async.php"
     data-fetcher="fetch.php"
     data-ratio="3:2"
     data-size="600,400"
     data-max-file-size="2">
    <img src="./media/stars.jpg" alt=""/>
    <input type="file" name="slim[]"/>
</div>

Upload now!

Actual post is disabled for privacy reasons

<form action="post.php" method="post" enctype="multipart/form-data" class="avatar">

    <div class="slim"
         data-label="Drop your avatar here"
         data-fetcher="fetch.php"
         data-size="240,240"
         data-ratio="1:1">
        <input type="file" name="slim[]" required />
    </div>

    <button type="submit">Upload now!</button>

</form>

<input type="file" id="myCropper"/>

new Slim(document.getElementById('myCropper'));

$('#myCropper').slim();

An example code snippet passing custom options in JavaScript.

new Slim(element, {
    ratio: '4:3',
    minSize: {
        width: 640,
        height: 480,
    },
    crop: {
        x: 0,
        y: 0,
        width: 100,
        height: 100
    },
    service: 'upload-async.php',
    download: false,
    willSave: function(data, ready) {
        alert('saving!');
        ready(data);
    },
    label: 'Drop your image here.',
    buttonConfirmLabel: 'Ok',
    meta: {
        userId:'1234'
    }
});

The options object is identical.

$(selector).slim({
    ratio: '4:3',
    minSize: {
        width: 640,
        height: 480,
    },
    crop: {
        x: 0,
        y: 0,
        width: 100,
        height: 100
    },
    service: 'upload-async.php',
    download: false,
    willSave: function(data, ready) {
        alert('saving!');
        ready(data);
    },
    label: 'Drop your image here.',
    buttonConfirmLabel: 'Ok',
    meta: {
        userId:'1234'
    }
});

<div id="my-snippet">

    <!-- my first cropper -->
    <input type="file" class="slim"/>

    <!-- my second cropper -->
    <input type="file" class="slim"/>

</div>

Using JavaScript with we select the parent element using the getElementById method.

Slim.parse(document.getElementById('my-snippet'));

In jQuery we can just pass the parent selector to the jQuery method.

$('#my-snippet').slim('parse');

The API exposes a destroy method.

// Create a new cropper
var cropper = new Slim(document.getElementById('my-cropper'));

// Destroy the cropper
cropper.destroy();

If you want to destroy a cropper that was initialised automatically (or by using the parse method) you can use the destroy method on the Slim Class itself.

// Destroy cropper on element
Slim.destroy(document.getElementById('my-cropper'));

If you're using jQuery creating and destroying croppers can be done with a single destroy call.

// Create cropper(s)
var croppers = $('#my-cropper').slim(options);

// Destroy cropper(s)
croppers.slim('destroy');

// Create a new cropper
var cropper = new Slim(document.getElementById('my-cropper'));

// Load image by url or pass a File object
// - The error parameter contains error messages
cropper.load('path/to/image.jpg', function(error, data){

    // Done loading the image!

    // Upload a selected image to the server
    cropper.upload(function(error, data, response){

        // Done uploading!

    });

});

Create a new Slim Cropper.

var cropper = new Slim(document.getElementById('my-cropper'));

Test if Slim is bound to given element.

var state = cropper.isAttachedTo(element);

Test if Slim is still bound to DOM.

var state = cropper.isDetached();

Upload an image by url or data-uri.

// basic implementation
cropper.load(src);

// if you need to know when the image has loaded, pass a function
// as the second parameter
cropper.load(src, function(error, data) {
    // image load done!
});

// you can also pass an options object
// this options object also accepts a rotation and crop parameter
// these options reflect the functionality of the rotation and
// crop options on the slim options object
cropper.load(src, { rotation:90, crop: {} }, function(error, data) {
    // image load done!
});

// if 'push' is set to true, you can pass the blockPush
// property to prevent immediate upload on image load
cropper.load(src, { blockPush:true }, function(error, data) {
    // image load done!
});

Upload currently loaded image

cropper.upload(function(error, data, response) {
// upload done!
});

Download currently loaded image as file

cropper.download();

Request current output data

cropper.requestOutput(function(fileData, formData) {
    // fileData files
    // formData files wrapped in FormData object ready for submit
});

Remove currently loaded image

var data = cropper.remove();

Destroy the cropper

cropper.destroy();

Get current data object

var data = cropper.data;

// format of data object
{
    // server response object after async upload
    server: null,

    // meta data set with data-meta-*
    meta: {},

    // the source file
    input:{
        // input field id
        field: null,

        // name of file
        name: null,

        // mime type of image
        type: null,

        // file loaded
        file: null,

        // file size in bytes
        size: null,

        // image base64 data or canvas
        image: null,

        // original dimensions of image
        width: 0,
        height: 0
    },

    // the result of the crop
    output:{

        // name of file
        name: null,

        // mime type of image
        type: null,

        // image base64 data or canvas
        image: null,

        // output image dimensions
        width: 0,
        height: 0
    },

    // user actions
    actions:{
        // angle of rotation in degrees
        rotation: null,

        // crop coordinates and type
        crop: {
            // coordinates
            x: 0,
            y: 0,
            width: 0,
            height: 0,

            // type of crop
            // - 'auto'
            // - 'initial'
            // - 'manual'
            type: null
        },

        // output size
        size: {
            width: 0,
            height: 0
        },

        // applied filters
        filters: {
            sharpen: 0
        }
    }
}

Get current data object in base64 format

var data = cropper.dataBase64;

Get root element

var element = cropper.element;

Do manual crop, please keep in mind that this method does not check if the input matches the required ratio or image size.

cropper.crop({x:0, y:0, width:100, height:100}, function(result) {
// crop done!
});

Open the editor

cropper.edit();

Set new output size

cropper.size = { width:640, height:480 };

// directly apply with set method
cropper.setSize({ width:640, height:480 }, function(data) {
    // done!
});

set new forced size

cropper.forceSize = { width:640, height:480 };

// directly apply with set method
cropper.setForceSize({ width:640, height:480 }, function(data) {
    // done!
});

Set new ratio

cropper.ratio = '3:2';

// directly apply with set method
cropper.setRatio('3:2', function(data) {
    // done!
});

Set new rotation

cropper.rotation = 90;

// directly apply with set method
cropper.setRotation(90, function(data) {
    // done!
});

Summary of Static API methods

Tests if slims can be used on this browser.

var supported = Slim.supported;

Parses the given DOM context for Slim croppers.

var croppers = Slim.parse(context);

Finds a previously initialised cropper by element.

var cropper = Slim.find(context);

Creates a cropper on the given element.

var cropper = Slim.create(element, options);

Destroys cropper attached to element

var success = Slim.destroy(element);

Create a new Slim Cropper.

var $cropper = $('#my-cropper').slim();

Test if Slim is bound to given element.

var state = $(selector).slim('isAttachedTo', element);

Test if Slim is still bound to DOM.

var state = $(selector).slim('isDetached');

Upload an image by url or data-uri.

// basic implementation
$(selector).slim('load', src);

// if you need to know when the image has loaded, pass a function
// as the second parameter
$(selector).slim('load', src, function(error, data) {
    // image load done!
});

// you can also pass an options object
// this options object also accepts a rotation and crop parameter
// these options reflect the functionality of the rotation and
// crop options on the slim options object
$(selector).slim('load', src, { rotation:90, crop: {} }, function(error, data) {
// image load done!
});

// if 'push' is set to true, you can pass the blockPush
// property to prevent immediate upload on image load
$(selector).slim('load', src, { blockPush:true }, function(error, data) {
// image load done!
});

Upload currently loaded image

$(selector).slim('upload', function(error, data, response) {
    // upload done!
});

Download currently loaded image as file

$(selector).slim('download');

Remove currently loaded image

$(selector).slim('remove');

Destroy the cropper

$(selector).slim('destroy');

Get current data object

$(selector).slim('data');


// format of data object
{
    // server response object after async upload
    server: null,

    // meta data set with data-meta-*
    meta: {},

    // the source file
    input:{
        // input field id
        field: null,

        // name of file
        name: null,

        // mime type of image
        type: null,

        // file loaded
        file: null,

        // file size in bytes
        size: null,

        // image base64 data or canvas
        image: null,

        // original dimensions of image
        width: 0,
        height: 0
    },

    // the result of the crop
    output:{

        // name of file
        name: null,

        // mime type of image
        type: null,

        // image base64 data or canvas
        image: null,

        // output image dimensions
        width: 0,
        height: 0
    },

    // user actions
    actions:{
        // angle of rotation in degrees
        rotation: null,

        // crop coordinates and type
        crop: {
            // coordinates
            x: 0,
            y: 0,
            width: 0,
            height: 0,

            // type of crop
            // - 'auto'
            // - 'initial'
            // - 'manual'
            type: null
        },

        // output size
        size: {
            width: 0,
            height: 0
        },

        // applied filters
        filters: {
            sharpen: 0
        }
    }
}

Get current data object in base64 format

$(selector).slim('dataBase64');

Get root element

$(selector).slim('element');

Do manual crop, please keep in mind that this method does not check if the input matches the required ratio or image size.

$(selector).slim('crop', {x:0, y:0, width:100, height:100}, function(result) {
// crop done!
});

Open the editor

$(selector).slim('edit');

Set new output size

// only set the size
$(selector).slim('size', { width:640, height:480 });

// directly apply, callback method is called on completion
$(selector).slim('setSize', { width:640, height:480 }, function(data) {

});

Set new ratio

// only set a new ratio
$(selector).slim('ratio', '3:2');

// directly apply the ratio
$(selector).slim('setRatio', '3:2', function(data) {

});

Set new ratio

// only set a new rotation
$(selector).slim('rotation', 90);

// directly apply the rotation
$(selector).slim('setRotation', 90, function(data) {

});

Summary of Static API methods

Tests if slims can be used on this browser.

var supported = $().slim('supported');

Parses the given DOM context for Slim croppers.

// Return value is not croppers but nodes parsed as
// it's possible to supply multiple nodes using a
// single selector.
var $elements = $(selector).slim('parse');

Creates a cropper on the given element.

var cropper = $(selector).slim(options);

Destroys cropper attached to element

var success = $(selector).slim('destroy');

$images = Slim::getImages();

$images = Slim::getImages('myFieldName');

$images = Slim::getImages();
$image = $images[0];

// let's create some shortcuts
$name = $image['output']['name'];
$data = $image['output']['data'];

// store the file
$file = Slim::saveFile($data, $name);

$file = Slim::saveFile($data, $name, 'myFolder/');

$file = Slim::saveFile($data, $name);
echo $file['name'];
// 573f60ddd630f_imagename.jpg

echo $file['path'];
// tmp/573f60ddd630f_imagename.jpg

$file = Slim::saveFile($data, $name, 'myFolder/', false);

{
    "meta":{
        "userId":"1234"
    }
}

// get the image data
$images = Slim::getImages();
$image = $images[0];

// print metadata
echo $image['meta']->userId; // "1234"

<script>
function addTime(data, ready) {

    // add additional data
    data.meta.now = Date.now();

    // continue saving the data
    ready(data);

}
</script>

<form action="post.php" method="post" enctype="multipart/form-data">

    <div class="slim"
         data-meta-user-id="1234"
         data-ratio="16:9"
         data-size="600,300"
         data-will-save="addTime">
        <input type="file" name="slim[]">
    </div>

    <button type="submit">Send!</button>

</form>

Send!

React

React has a custom component syntax. We use the Slim element instead of a class and instead of the data attributes we pass the JavaScript options directly like shown in the example below.

import React, { Component } from 'react';
import Slim from './slim/slim.react';

class App extends Component {

    // called when slim has initialized
    slimInit(data, slim) {
        // slim instance reference
        console.log(slim);

        // current slim data object and slim reference
        console.log(data);
    }

    // called when upload button is pressed or automatically if push is enabled
    slimService(formdata, progress, success, failure, slim) {
        // slim instance reference
        console.log(slim)

        // form data to post to server
        // set serviceFormat to "file" to receive an array of files
        console.log(formdata)

        // call these methods to handle upload state
        console.log(progress, success, failure)
    }

    render() {
        return (
            <div className="App">
                <Slim ratio="1:1"
                      initialImage="test.jpg"
                      minSize={ { width:600, height:400 } }
                      service={ this.slimService.bind(this) }
                      didInit={ this.slimInit.bind(this) }>
                    <input type="file" name="foo"/>
                </Slim>
            </div>
        );
    }
}

Angular 1.x

The Slim directive binds on the "slim" tag, you can add the exact same HTML attributes as in the other code examples.

<div ng-app="myApp" ng-controller="AppController">
    <slim data-size="200,200"
          data-download="true"
          data-initial-image="test.jpg"
          data-service="slim.service"
          data-did-init="slim.init">
        <input type="file" name="slim[]"/>
    </slim>
</div>

An example controller with callback method.

(function(angular){

    var app;
    app = angular.module('myApp', ['slim']);
    app.controller('AppController', function($scope) {

        $scope.slim = {

            // called when slim has initialized
            init: function (data, slim) {
                // slim instance reference
                console.log(slim);

                // current slim data object and slim reference
                console.log(data);
            },

            // called when upload button is pressed or automatically if push is enabled
            service: function (formdata, progress, success, failure, slim) {
                // form data to post to server
                // set data-service-format to "file" to receive an array of files
                console.log(formdata);

                // call these methods to handle upload state
                console.log(progress, success, failure);

                // reference to Slim instance
                console.log(slim);
            }
        }

    });

}(angular));

Angular

Angular is a tiny bit different. Options are passed to the Slim module as an object.

This code is compatible with Angular 2 and up.

When using Angular CLI you'll have to make some changes to the configuration files.

add to /tconfig.js

• "allowJs": true,
• "allowUnreachableCode": true,

add to /.angular-cli.json "styles" array

• "app/slim/slim.css"

For Angular version 7 and lower:

You need the slim.angular2.ts file and the slim.commonjs.js file.

/**
 * app.module.ts
 */
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { Slim } from './slim/slim.angular2'; // import from slim.angular2 file

@NgModule({
    imports: [ BrowserModule ],
    declarations: [ AppComponent, Slim ], // add declaration
    bootstrap: [ AppComponent ]
})

export class AppModule { }

For Angular version 8 and up:

You need the slim.angular.component.ts, slim.angular.module.ts and the slim.commonjs.js file.

/**
 * app.module.ts
 */
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';
import { SlimModule } from './slim/slim.module'; // import from slim.module file

@NgModule({
    declarations: [AppComponent],
    imports: [BrowserModule, SlimModule], // add imports
    providers: [],
    bootstrap: [AppComponent]
})

export class AppModule { }

Usage is the same for all modern Angular versions.

/**
 * app.component.ts
 */
import { Component } from '@angular/core';

@Component({
    selector: 'my-app',
    template: `
        <slim [options]="slimOptions">
            <input type="file" name="foo">
        </slim>
    `
})

export class AppComponent {

    slimOptions = {
        ratio: '1:1',
        download: true,
        initialImage: './test.jpg',
        service: this.slimService.bind(this),
        didInit: this.slimInit.bind(this)
    };

    // called when slim has initialized
    slimInit(data:any, slim:any) {
        // slim instance reference
        console.log(slim);

        // current slim data object and slim reference
        console.log(data);
    };

    // called when upload button is pressed or automatically if push is enabled
    slimService(formdata:any, progress:any, success:any, failure:any, slim:any) {
        // form data to post to server
        // set serviceFormat to "file" to receive an array of files
        console.log(formdata);

        // call these methods to handle upload state
        console.log(progress, success, failure);

        // reference to Slim instance
        console.log(slim);
    };

}

Vue

Options are passed to the Slim module as an object and we use the `slim-cropper` tag.

<template>
    <div>
        <slim-cropper :options="slimOptions">
            <input type="file" name="slim"/>
        </slim-cropper>
    </div>
</template>

<script>
import Slim from './slim/slim.vue'

// called when slim has initialized
function slimInit (data, slim) {
    // slim instance reference
    console.log(slim)

    // current slim data object and slim reference
    console.log(data)
}

// called when upload button is pressed or automatically if push is enabled
function slimService (formdata, progress, success, failure, slim) {
    // slim instance reference
    console.log(slim)

    // form data to post to server
    // set serviceFormat to "file" to receive an array of files
    console.log(formdata)

    // call these methods to handle upload state
    console.log(progress, success, failure)
}

export default {
    name: 'hello',
    components: {
        'slim-cropper': Slim
    },
    data () {
        return {
            slimOptions: {
                ratio: '1:1',
                initialImage: require('../assets/test.jpg'),
                service: slimService,
                didInit: slimInit
            }
        }
    }
}
</script>

A snippet showing how to use Slim with Bootstrap.

<form>

    <fieldset class="form-group">
        <label for="email">E-mail</label>
        <input type="email" class="form-control" id="email">
    </fieldset>

    <fieldset class="form-group">
        <label for="avatar">Avatar</label>
        <input type="file"
               class="form-control slim"
               data-ratio="1:1"
               id="avatar">
    </fieldset>

</form>

An example of Slim being used in a Foundation form.

<form>

    <label>E-mail
        <input type="email">
    </label>

    <label>Avatar
        <input type="file" class="slim" data-ratio="1:1">
    </label>

</form>