Image Editor Addon

The Image Editor can be used in web-based applications by embedding the provided javascript. It can also be used in native applications using WebView interface.

🚧
Note: This is a beta release available for select customers. Please contact us to get access.

Features

Annotate images with text, shapes, and drawings
Crop and resize images
Add background images, border and other graphics
Apply Scenes that combine background, borders and graphics in one go
Supports text annotation through scenes
Apply filters and fine-tune image properties
Customizable sidebar for selecting background images, graphics, and scenes

Usage

You can easily embed the FileSpin Image Editor into your HTML page by including the main.js file and using the example HTML provided below.


<!DOCTYPE html>
<html>

<head>
  <meta charset="utf-8" />
  <title>FileSpin Image Editor</title>
</head>

<body>
  <div id="inline-editor" style="width: 1000px; height: 500px"></div>
  <script src="main.js"></script>
  <script>

    // Note: This will change to:
    // const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', config)

    var editor = {}

    fileSpinImageEditor.createAndInjectEditor('inline-editor', {
      // Configuration options
    }).then((callbacks) => {
      editor.callbacks = callbacks
    });
  </script>
</body>

</html>

Configuration Options

The createAndInjectEditor function accepts two parameters:

The ID of the HTML element where the editor should be injected.
An object containing the configuration options for the editor.

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // Configuration options
});

Here's a detailed explanation of the configuration options:

foreground

The foreground image is the image that will be edited. This field is required.

To crop foreground image "Foreground" menu option should be selected and Edit on the menu that appears for foreground image should be used.

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // ...
  foreground: 'images/foreground.png',
  // ... 
});

foregroundPosition

The foregroundPosition parameter can have two possible values: fit or center.

When set to fit, the height of the foreground image is adjusted to match the height of the canvas, while maintaining the original aspect ratio. The image is centered horizontally within the canvas.
When set to center, the foreground image is centered within the canvas along both the horizontal and vertical axes.

The foregroundPosition parameter is optional, and if not provided, it defaults to center.

Example usage in JavaScript:

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // ...
  foregroundPosition: 'fit',
  // ...
});

In the example above, the foregroundPosition parameter is set to fit, ensuring that the foreground image fills the canvas vertically while maintaining its aspect ratio.

background

The background image is the image that will be used as the background for the foreground image. It is the initial background image. This field is required.

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // ...
  background: 'images/background1.png',
  // ... 
});

onsave

The onsave key holds the callback that is executed when the image editor finishes processing the image. To save the image you need to implement the onsave method.

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // ...
  onsave: (finalImage) => console.log(finalImage)
  // ... 
});

imageViewSize

This is the size of the view to which the images will be resized to. Aspect ratio is always preserved and therefore, no distortion is introduced.

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
// ...
  imageViewSize: {
    width: 1254,
    height: 836
  },
  // ... 
});

Text Annotation ( Scene )

In addition to supporting graphical elements, the scene can also accommodate text annotations. The method for incorporating text annotations into a scene is outlined below:

{
  "scenes": [
    {
      "name": "Scene 1",
      "thumbnail": "images/thumbnail1.jpg",
      "background": "images/bg1.jpg",
      "border": "images/border1.png",
      "graphics": [
        {
          "x": 0,
          "y": 0,
          "width": 100,
          "height": 100,
          "backgroundImage": "images/graphic1.png"
        },
        {
          "x": 128,
          "y": 128,
          "fontSize": 96,
          "fontWeight": 'bold',
          "color": [1, 1, 1], 
          "text": 'Hello {name}',
          "fontFamily": 'Helvetica',
        }
      ]
    }
  ]
}

The text annotation has the following parameters:

x & y : These parameters define the horizontal and vertical positions of the text within the canvas, measured in pixels from the top-left edge of the scene.
fontSize : This parameter specifies the size of the font on the canvas, measured in pixels.
fontWeight : This parameter determines the weight or thickness of the font, such as normal or bold.
color : This parameter defines the color of the text using the unit RGB color model, where each value is a fraction between 0 and 1 (derived by dividing the standard RGB value by 255).
text : This parameter contains the actual text to be displayed (e.g., 'Hello !').
fontFamily : This parameter specifies the font family to be used, the fontFamily specified should be available to the Browser/WebView within which the Image Editor is used.

Note: use the fontFamily property to set a single fontFamily, a font-stack is not supported

plugins

The list of plugins to be used. The order of the plugins in the list will be the order in which they will be displayed in the editor. This field is optional. Not specifying this field will result in all the plugins.

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
// ...
  plugins: ['annotate', 'crop', 'resize', 'filter', 'finetune', 'sticker'],
  // ... 
});

The sidebar configuration. This field is optional. Not specifying this field will result in the absence of a sidebar. The order of the keys (backgrounds, graphics, borders) will be the order in which they will be displayed in the sidebar.

const editor = fileSpinImageEditor.createAndInjectEditor('inline-editor', {
// ...
  sidebar: {
    backgrounds: [
      'images/background1.png',
      'images/background2.png',
      'images/background3.png',
      'images/background4.png',
      'images/background5.jpeg',
    ],
    graphics: [
      'images/background3.png',
      'images/background4.png',
      'images/background1.png',
      'images/background5.jpeg',
      'images/background2.png',
    ],
    borders: [
      'images/border1.png',
    ],
    scenes: [
        {
            'name': 'Scene 1',
            'thumbnail': 'images/thumbnail1.jpg',
            'background': 'images/bg1.jpg',
            'border': 'images/border1.png',
            'graphics': [
                {
                    'x': 0,
                    'y': 0,
                    'width': 100,
                    'height': 100,
                    'backgroundImage': 'images/graphic1.png'
                },
            ]
        }
    ]
  }
  // ... 
});

Using the callbacks.actions.save Method

The callbacks.actions.save method allows you to save the current state of the image that is being edited.

Syntax

The syntax for using the callbacks.actions.save method is:

callbacks.actions.save();

Usage

In the given code snippet, the callbacks.actions.save method is added to an event listener

fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // Configuration options...
}).then((callbacks) => {
  document.getElementById('save-image-button').addEventListener('click', callbacks.actions.save);
});

When the save-image-button is clicked, it will then trigger the processing of the image with all the edits made up to that point. When it is done, the result will be passed to the onsave method as a javascript file object.

Example

Here is a more detailed example of using the callbacks.actions.save method:

Create an HTML file with the following structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Image Editor</title>
  <!-- Add CSS and JS dependencies here -->
</head>
<body>
  <div id="inline-editor"></div>
  <button id="save-image-button">Save</button>

  <!-- Add JavaScript code to initialize the image editor here -->
</body>
</html>

Add the required CSS and JS dependencies for the fileSpinImageEditor object.

Initialize the image editor with the configuration options provided in the code snippet, and use the callbacks.actions.save method to trigger the image processing phase:

fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // Configuration options...
}).then((callbacks) => {
  document.getElementById('save-image-button').addEventListener('click', callbacks.actions.save);
});

Now, when the user clicks the 'Save' button, the image will be processed and the results will be passed to the onsave function.

Using the callbacks.actions.substituteForeground Method

The callbacks.actions.substituteForeground method allows you to replace the current foreground image with a new one. It can be useful in scenarios where you want to give users the ability to change the image they are editing.

Syntax

The syntax for using the callbacks.actions.substituteForeground method is:

callbacks.actions.substituteForeground(newForegroundImageUrl);

Where newForegroundImageUrl is a string containing the URL of the new foreground image.

Usage

In the given code snippet, the callbacks.actions.substituteForeground method is used to change the foreground image when the user clicks an HTML element with the ID 'change-foreground':

fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // Configuration options...
}).then((callbacks) => {
  document.getElementById('change-foreground').addEventListener('click', () => {
    callbacks.actions.substituteForeground('images/graphic1.png');
  });
});

In this example, when the user clicks the element with the ID 'change-foreground', the current foreground image will be replaced with the image located at 'images/graphic1.png'.

Example

Here is a more detailed example of using the callbacks.actions.substituteForeground method:

Create an HTML file with the following structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Image Editor</title>
  <!-- Add CSS and JS dependencies here -->
</head>
<body>
  <div id="inline-editor"></div>
  <button id="change-foreground">Change Foreground</button>

  <!-- Add JavaScript code to initialize the image editor here -->
</body>
</html>

Add the required CSS and JS dependencies for the fileSpinImageEditor object.

Initialize the image editor with the configuration options provided in the code snippet, and use the callbacks.actions.substituteForeground method to change the foreground image when the 'Change Foreground' button is clicked:

fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // Configuration options...
}).then((callbacks) => {
  document.getElementById('change-foreground').addEventListener('click', () => {
    callbacks.actions.substituteForeground('images/graphic1.png');
  });
});

Now, when the user clicks the 'Change Foreground' button, the foreground image will be replaced with the new image specified in the substituteForeground method.

Important Note on callbacks.actions.substituteForeground Method

When using the callbacks.actions.substituteForeground method, please be aware that the edit history of the current foreground image will be lost. This means that users will not be able to undo or redo any previous edits made to the original foreground image once it has been replaced with a new one.

To maintain a good user experience, you may want to consider providing a warning or confirmation message before executing this method, so users are aware that they will lose the edit history of the current foreground image. This can be done using JavaScript window.confirm() function or a custom modal dialog.

Here's an example using window.confirm():

fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // Configuration options...
}).then((callbacks) => {
  document.getElementById('change-foreground').addEventListener('click', () => {
    if (window.confirm('Changing the foreground will result in the loss of edit history. Do you want to proceed?')) {
      callbacks.actions.substituteForeground('images/graphic1.png');
    }
  });
});

In this example, when the user clicks the 'Change Foreground' button, they will be presented with a confirmation dialog warning them about the loss of edit history. If the user chooses to proceed, the foreground image will be replaced with the new image specified in the substituteForeground method, and the edit history will be lost.

Using callbacks.actions.substituteForeground with API Calls

This section explains how to use the callbacks.actions.substituteForeground method in conjunction with API calls to fetch a new foreground image and replace the current one in the fileSpinImageEditor object.

In the provided code snippet, an event listener is added to an HTML element with the ID 'change-foreground'. When this element is clicked, an API call is made to fetch a new image, which is then used to replace the current foreground image in the editor.

fileSpinImageEditor.createAndInjectEditor('inline-editor', {
  // Configuration options...
}).then((callbacks) => {
  document.getElementById('change-foreground').addEventListener('click', async () => {
    const url = 'https://cdn.filespin.io/api/v1/assets/e05fa98119ab44cab4264befa6b7b730/conversions?resize=800,600';
    const response = await fetch(url);
    const blob = await response.blob();
    const blobUrl = URL.createObjectURL(blob);
    callbacks.actions.substituteForeground(blobUrl);
  });
});

Here's a step-by-step explanation of the code:

The fileSpinImageEditor.createAndInjectEditor function is called with the required configuration options.
The returned Promise resolves with a callbacks object, which includes the actions.substituteForeground method.
An event listener is added to the element with the ID change-foreground. This listener is triggered when the user clicks on the element.
Inside the event listener, an async function is used to fetch a new image from the specified API endpoint.
The fetched image is converted into a Blob object.
A temporary URL is created for the Blob object using the URL.createObjectURL() method.
The callbacks.actions.substituteForeground method is called with the temporary URL, replacing the current foreground image with the fetched image.

When using this approach, make sure that the API endpoint returns a valid image. Additionally, note that the edit history of the current foreground image will be lost when using the substituteForeground method, as previously mentioned. Consider providing a warning or confirmation message to the user before making the change.

🚧Note: This is a beta release available for select customers. Please contact us to get access.

Features

Usage

Configuration Options

foreground

foregroundPosition

background

onsave

imageViewSize

Text Annotation ( Scene )

plugins

Using the callbacks.actions.save Method

Syntax

Usage

Example

Using the callbacks.actions.substituteForeground Method

Syntax

Usage

Example

Important Note on callbacks.actions.substituteForeground Method

Using callbacks.actions.substituteForeground with API Calls

🚧
Note: This is a beta release available for select customers. Please contact us to get access.