Pixie - Integration Mode

Pixie is a photo editing & manipulation application. It is perfect for integration into other projects or personal use. Unlike other similar products it is built with html5 and javascript and not outdated technologies like flash. This makes Pixie future-proof, allows for much better performance and cross-device compatibility. You also get full source code so you can modify it if needed and host it yourself instead of relying on 3rd party service.

Basic Usage

Since version 1.5 most of the options and callbacks listed here can be used in regular mode as well, by specifying them in global PixieParams variable.

First upload pixie folder to your server so it is accessible from your existing project.

Include JS

<!-- Ideally before closing body tag -->
<script data-preload="true" data-path="pixie" src="pixie/pixie-integrate.js"></script>

data-preload="true" is optional. Use it to preload all the pixie assets with the initial page load. Without this attribute assets will be loaded when the editor is first shown. It will take slightly longer for editor to appear withtout it, but the initial page load will be faster.

Use data-path="yourPathHere" to specify the path to pixie folder on your server. It's optional and will default to pixie.

Initiate and Open Pixie

Click image on the left for a demo of the code below.

<img id="edit-me" src="photos/1.jpg"/>

<script>
    var myPixie = Pixie.setOptions({
        replaceOriginal: true,
        appendTo: 'body'
    });

    $('#edit-me').on('click', function(e) {
        myPixie.open({
            url: e.target.src,
            image: e.target
        });
    });
</script>

Check the bottom of this page for a detailed documention on all the options, callbacks and methods available to you.

Example for saving modified image server-side with PHP

Javascript


var myPixie = Pixie.setOptions({
    onSave: function(data, img) {
        $.ajax({
            type: 'POST',
            url: '/save-image.php',
            data: { imgData: data },
        }).success(function(response) {
            alert('image saved successfully!');
        });
    }
});

PHP

//save-image.php

<?php

    $data = file_get_contents($_REQUEST['imgData']);

    file_put_contents('image.jpg', $data);

?>
                

It is the same for every server-side language. Esentially you just send image base64 encoded data via onSave callback (or by specifying saveUrl) to your server and then simply put that data in a file.

Interactive Mode

Interactive mode will automatically open images in specified container when they are clicked and replace them with edited ones once user saves.

<script>
    var myPixie = Pixie.setOptions({
        replaceOriginal: true,
        appendTo: 'body'
    });

    myPixie.enableInteractiveMode({
        selector: '.img-responsive',
        container: '#images',
        preventDefault: true
    });
</script>

Options, Callbacks, Methods

Options

Name Default Description
url false Url of image to load into editor. Can be relative or absolute.
blankCanvasSize false Blank canvas dimensions. Will only be used if url parameter is not present. Example: { width: 500, height: 200 }
hideOpenButton false When set to true, Open button in the top panel will be hidden.
enableCORS false Whether or not pixie should assume that image is cross-domain enabled. With set to false pixie will use image laundering service to fetch image trough domains which will be slower (no laundering will occur if image is hosted on the same domain as pixie).
forceLaundering false Setting this to true will force image laundering even if image is hosted on the same domain.
path pixie Path to or the name of pixie folder on your server.
saveUrl false Edited image data will be sent to this url via ajax post request on save.
replaceOriginal false Whether or not passed in (or clicked on in interactive mode) image DOM node should be replace with modified one after saving.
appendTo body What element pixie container should be appended to in the DOM. Should be a string that is acceptable by document.querySelector()
noManualClose false When this is set to true editor will not be automatically closed when clicking on backdrop and the close button will not be visible.
openDelay 400 Fade In delay in milliseconds when opening the editor.
closeDelay 400 Fade out delay in milliseconds when closing the editor.

Callbacks

Name Description
onSave

Called after image is fully processed and ready to be saved.


var myPixie = Pixie.setOptions({
    appendTo: 'body',
    onSave: function(data, img) {
        data //base64 encoded image data
        img  //img element with src set to image data
    }
});
onLoad

Called after all editor assets are fully loaded and it's ready to be shown.


var myPixie = Pixie.setOptions({
    appendTo: 'body',
    onLoad: function(container, rootScope, window) {
        container //Top-most DOM node of the editor
        rootScope  //You should get familiarized with angular.js and pixie source code before using this.
        window //pixie iframe window element
    }
});
onError

Called after all an error occurs in the editor. Will log error object to console by default.


var myPixie = Pixie.setOptions({
    onError: function(err) {
        err //error object
    }
});
onSaveButtonClick

Called after save button is clicked in the editor. If you pass in this callback the dialog window with image quality, name etc will not be shown and you will need to save it manualy.


var myPixie = Pixie.setOptions({
    onSaveButtonClick: function() {
        myPixie.save(format, quality);
        //format - png or jpeg
        //quality - 1 to 10
    }
});
onClose

Called after editor is closed. No parameters are passed in.

Methods

All methods should be called on the instance that is ruturned from Pixie.setOptions({})

Name Description
.open(options) Open image editor. Can pass in all options described above.
.close() Close the editor.
.enableInteractiveMode(options) Enable interactive mode. Look for example above.
.getParams(options) Get current pixie parameters.
.setOptions(options) Set options. Can do it via open(options) as will, but it will open the editor.
.save(format, quality) Manually save image currently open in the editor. Will trigger all callbacks normal save would.
.getService(name) Get an angular.js service instance. Familiarity with angular.js recommended.