loading

Documentation

Initialization

Add the following code to your application to initialize Pixo:

<img id="myimage" src="myimage.png" />
<script src="https://pixoeditor.com:8443/editor/scripts/bridge.m.js"></script>
<script>
   var image = document.getElementById('myimage');
   var constructor_options ={apikey: 'abc123xyz000'};
   image.onload = function(){
      var editor = new Pixo.Bridge(constructor_options);
      editor.edit(image);
   }
</script>

 

Constructor options

The constructor accepts options parameter. Here’s a list with all options, possible values and defaults:

  • apikey (String) Required. This is your personal API key with which you can use Pixo editor. Register and get your API key
  • type (String) Editor window type. Accepted values:
    • “window” Pixo opens in new browser window (default)
    • “modal” Pixo opens in a modal window overlaying the page
    • “child” Pixo opens nested in provided DOM element, as a child; requires parent parameter
  • parent (DOM element) Parent DOM element in which to inject Pixo; applicable only when mode=”child”
  • width (String) Editor’s width Default “100%”
  • height (String) Editor’s height Default “100%”
  • overlay (Object) Whether to show overlay below the editor or not, useful when dimensions are not full-size. Can contain the color property. Default null
    • color (String) The CSS color of the property. All CSS color values are valid. Default “rgba( 0, 0, 0, .3 )”
  • styles (Object) Let’s you define your own look & feel of the editor. Default null
    • logosrc (String) URL to your custom logo, or “none”
    • canvasbgcolor (String) CSS color for the canvas background
    • editmenubgcolor (String) CSS color for the edit menu background
    • actionsmenubgcolor (String) CSS color for the actions menu background
    • propertiespanelbgcolor (String) CSS color for the properties panel background
    • textcolor (String) CSS color for all text
  • language (String) The language in which to translate all labels and captions into, according to IETF standardDefault “en-US” (see list with all supported languages)
  • features (Array|Object) List of features (by ID) to include (when array) or exclude (when object) (see list with available feature IDs)
    • excluded (Array) List of features to exclude
  • propertypanel (Object) Configuration for property panel, with the following properties:
    • collapsible (Boolean) Should the property panel be collapsible or not. If collapsible, collapsing it will add more space for the canvas and the edited image. Default false
    • collapsed (Boolean) The initial state of the property panel – expanded or collapsed. Default false
  • filterStickers Filters stock stickers by executing the passed callback function (see examples)
  • filterFrames Filters stock image frames by executing the passed callback function (see examples and also check frame image guidelines)
  • onSave (Function) Callback, executed when the user finishes editing and clicks Save. See details
  • onCancel (Function) Callback, executed when the user cancels editing
  • onClose (Function) Callback, executed when the editor window is closed

 

Instance methods

  • edit Opens the editor with the passed image to edit as argument (check examples). The image can be of the following types:
    • Image
    • String (URL or Base64)
    • File
  • cancelEditing Closes the editor
  • destroy Destroys the instance
  • filterStickers Filters stock stickers by executing the passed callback function (see examples)

 

Supported languages

  • en-US (English, United States)
  • fr-FR (French, France)

Help us translate Pixo in multiple languages

  1. Download sample JSON translation file
  2. Rename the file according to IETF standard
  3. Add the translations
  4. Send us the translated file to admin (at) pixoeditor.com

 

Features

Editor has the following features to be included or excluded:

  • adjustments (Color adjustments)
  • filters (Pre-defined image filters)
  • draw (Free drawing)
  • crop (Crop incl. pre-defined crop sizes)
  • stickers (Image stickers)
  • text (Text manipulations)
  • transform (Flip, rotate)
  • frame (Image frame)

See examples

 

onSave callback

onSave callback accepts the edited image as argument. This argument is object with the following methods:

  • toImage returns (Object) new Image element
  • toDataURL returns (String) base64 encoded string of the image data
  • toBlob returns (Blob) image data suitable for upload via FormData element

 

Frame images guidelines

  1. Frames must be transparent images (PNG or GIF). The visible part of the image must be transparent.
  2. Frames must be landscape oriented, or squares.
  3. The larger the images, the better. Design them in HD resolution at least (1920×1080).
  4. Optimize file size as much as possible. TinyPNG is a good optimizer.
  5. You need to provide both outer and inner dimensions to the configuration:
  6. Try to keep inner ratio (inner width divided by inner height) between 1 and 1.5 .
  7. The simpler and monochromatic the frame is, the larger treshold you can set. The treshold determines whether the frame will be rescaled to fully fit along the image, or parts of the image will be cropped (horizontally or vertically, depending on the difference between the image and frame aspect ratios. The larger the treshold, the more adaptive the frame will be. Below you can see examples for simpler and monochromatic frame (that accepts larger treshold (0.8-1) and complex frame that accepts smaller treshold (0.1-0.2):

    Very simple & monochromatic frame, may accept large treshold (0.8-1)

    Complex frame, requires small treshold (0.1-0.2)

See code example.

 

Examples

Edit image from the page

<img id="myimage" src="myimage.png" />
<script src="https://pixoeditor.com:8443/editor/scripts/bridge.m.js"></script>
<script>
   var image = document.getElementById('myimage');
   image.onload = function(){
      //create new Pixo instance
      var editor = new Pixo.Bridge({
         apikey: 'abc123xyz000',
         type: 'modal',
         onSave: function(arg){
            //replace image src with the new image data
            image.src = arg.toDataURL();
            //...or replace the entire image
            image.parentNode.insertBefore(arg.toImage(), image);
            image.parentNode.removeChild(image);
         }
      });
      editor.edit(image);
   }
</script>

 

Upload edited image

<script src="https://pixoeditor.com:8443/editor/scripts/bridge.m.js"></script>
<script>
   //create new Pixo instance
   new Pixo.Bridge({
      apikey: 'abc123xyz000',
      onSave: function(arg){
         //create FormData object and append the image to it
         var data = new FormData();
         //assuming that your backend accepts "image" POST parameter
         data.append('image', arg.toBlob());
         //create new XMLHttpRequest
         var request = new XMLHttpRequest();
         request.open('POST', 'http://yourdomain.com/path/to/upload.php');
         request.send(data);
      }
   }).edit('http://yourdomain.com/path/to/imagetoedit.jpg');
</script>

 

Modify or completely replace stock stickers

Pixo allows you to extend the default stickers pack, or to completely replace it with your own collection.

You can do that by passing a constructor callback option called filterStickers. This function accepts default stickers collection as array and must return the updated collection. Each item in the array must be an object with the following properties:

  • src (String) Required. URL to the sticker image that will be inserted
  • thumb (String) URL to the preview image that will be shown in the property panel; if not provided, src property will be used
  • caption (String) Caption that will be displayed below the sticker, also used for filtering results
<script>
var my_stickers = [
  {
     // This is the PNG image that will be inserted. The larger size the better.
     // Required. The URL must be publicly accessible or CORS-friendly.
     src: 'https://yourdomain.com/path/to/large-image.png',
     
     // This is the thumbnail image that will be shown in the property panel.
     // Optional. If missing "src" will be used. The URL may not be CORS-friendly
     // or publicly accessible.
     thumb: 'https://yourdomain.com/path/to/thumbnail-100x100.png',
     
     // Sticker caption that will be printed in the property panel below the image.
     // Required.
     caption: 'My Cool Sticker',
  },
  {
     src: 'https://yourdomain.com/path/to/large-image.png',
     thumb: 'https://yourdomain.com/path/to/thumbnail-100x100.png',
     caption: 'My Cool Sticker',
  },
];

var pixo_instance = new Pixo.Bridge({
  apikey: 'abc123xyz000',
  filterStickers: function(stock_stickers){
     // replace stock stickers with your own
     return my_stickers;
     // or, merge them and place your at the top
     return my_stickers.concat(stock_stickers);
     // or, merge them and place your at the bottom
     return stock_stickers.concat(my_stickers);
     // or, mix them randomly
     return stock_stickers.concat(my_stickers).sort(function(){
        return Math.random() - 0.5;
     });
     // or mix them and filter stock stickers
     return my_stickers.concat(
        stock_stickers.filter(function(sticker){
           // show only stock stickers with cats
           return sticker.name.toLowerCase().indexOf('cat') > -1;
        })
     ).sort(function(a, b){
        // sort all stickers by name
        return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
     });
  },
});
</script>

You can later filter stickers by calling the appropriate instance method, like this:

pixo_instance.filterStickers(function(stock_stickers){
   // ...
   return my_stickers;
});

 

Modify or completely replace stock image frames

Pixo allows you to extend the default image frames pack, or to completely replace it with your own collection.

You can do that by passing a constructor callback option called filterFrames. This function accepts default frames collection as array and must return the updated collection. Each item in the array must be an object with the following properties:

  • src (String) Required. URL to the frame image that will be inserted
  • thumb (String) Recommended. URL to the preview image that will be shown in the property panel; if not provided, src property will be used (not recommended)
  • dimensions (Object) Contains outer and inner dimensions of the frame as properties:
    • outer (Array) Outer dimensions (or in other words the real frame image dimensions) e.g. [ width, height ]
    • inner (Array) Inner dimensions (or in other words the dimensions of the visible part) e.g. [ width, height ]
  • treshold (Number) Value between 0 and 1 determining the % tolerance in difference between frame inner dimensions ratio and edited image ratio. Default 0.7 . When the difference between image and frame ratio is below the treshold the frame will be rescaled to fully fit the image inside; otherwise, image will be a little cropped horizontally or vertically, depending on the image orientation and the ratio difference.

Please check also the image frames guidelines.

<script>
var my_frames = [
  {
     // This is the PNG image that will be used as frame. The larger size the better.
     // Required. The URL must be publicly accessible or CORS-friendly.
     src: 'https://yourdomain.com/path/to/image-frame.png',
     
     // This is the thumbnail image that will be shown in the property panel.
     // Optional. If missing "src" will be used.
     thumb: 'https://yourdomain.com/path/to/thumbnail-100x100.png',
     
     // Outer and inner dimensions.
     // Required.
     dimensions: {
        outer: [1920, 1080],
        inner: [1660, 880],
     },

     treshold: .3,
  },
  {
     src: 'https://yourdomain.com/path/to/large-image.png',
     thumb: 'https://yourdomain.com/path/to/thumbnail-100x100.png',
     dimensions: {
        outer: [1920, 1080],
        inner: [1660, 880],
     },
  },
]; 

var pixo_instance = new Pixo.Bridge({
  apikey: 'abc123xyz000',
  filterFrames: function(stock_frames){
     // replace stock frames with your own
     return my_frames;
     // or, merge them and place your at the top
     return my_frames.concat(stock_frames);
     // or, merge them and place your at the bottom
     return stock_frames.concat(my_frames);
     // or, mix them randomly
     return stock_frames.concat(my_frames).sort(function(){
        return Math.random() - 0.5;
     });
  },
});
</script>

You can later filter frames again by calling the appropriate instance method, like this:

pixo_instance.filterFrames(function(stock_frames){
   // ...
   return my_frames;
});

 

Include specific features

new Pixo.Bridge({
   // This will include only Filters and Stickers and nothing more
   // The order you define in the array will affect the order of 
   // display in the Edit menu
   features: ['filters', 'stickers'],
});

 

Exclude specific feature

new Pixo.Bridge({
   // This will exclude only Filters and Stickers and will include
   // all other available features
   features: {
      excluded: ['filters', 'stickers'],
   },
});