Setting up Pintura Image Editor with jQuery
For a quick start use the jQuery example project as a guideline. It includes a normal, modal, and overlay editor example.
Default implementation example
In the default example below we'll use the pinturaDefault
function to quickly add an image editor to another HTML element.
This creates a "default" editor that has all available plugins loaded and comes preset with all plugin default options and English locale. Each of these settings can be adjusted freely.
<!DOCTYPE html>
<link rel="stylesheet" href="pintura/pintura.css" />
<style>
.my-editor {
height: 600px;
}
</style>
<div class="my-editor"></div>
<script src="pintura/pintura-iife.js"></script>
<script src="jquery-pintura/useEditorWithJQuery-iife.js"></script>
<script src="jquery.js"></script>
<script>
// load Pintura with jQuery
useEditorWithJQuery(jQuery, pintura);
$('.my-editor').pinturaDefault({
// The source image to load
src: 'image.jpeg',
// This will set a square crop aspect ratio
imageCropAspectRatio: 1,
});
</script>
Events and methods
When using the jQuery methods $(selector).pintura()
or $(selector).pinturaDefault()
the returned object is a jQuery result not an instance of the editor.
To handle events fired by the editor we have to prepend each event we want to listen to with pintura:
$('.my-editor').on('pintura:load', (e) => {
// Handle event
console.log('Image loaded', e.detail);
});
To run editor methods we have to do it the jQuery way, this means we use the pintura
scope and then we pass the method name as a string and next the parameters.
// Creating an editor without jQuery
const editor = createDefaultEditor();
// Run loadImage method
editor.loadImage('image.jpeg').then((res) => {
console.log('Image loaded', res);
});
// Creating an editor with jQuery
$('.my-editor').pinturaDefault();
// Run loadImage method
$('.my-editor')
.pintura('loadImage', 'image.jpeg')
.then((res) => {
console.log('Image loaded', res);
});
When we create a modal or overlay editor the factory method returns a normal editor instance. We can interact with this instance without having to convert method names to a string or prepend events with pintura:
, see below.
Modal and overlay editor
The jQuery API also allows creation of modal and overlay editors. Instead of the $(selector).pintura
syntax we can use the methods exported by the editor API as these are available on the $.fn.pintura
property. See the exports section for an overview of the available methods and properties.
This will open the editor in a modal. Note that this is not a default editor, to open a default editor use openDefaultEditor
instead of openEditor
.
const editor = $.fn.pintura.openDefaultEditor({
src: 'image.jpeg',
// This will set a square crop aspect ratio
imageCropAspectRatio: 1,
});
// Remove the image
editor.removeImage();
Listening for events on the editor modal can be done like shown below.
const editor = $.fn.pintura.openDefaultEditor({
src: 'image.jpeg',
// This will set a square crop aspect ratio
imageCropAspectRatio: 1,
});
editor.on('load', (e) => {
// Handle event
console.log('Image loaded', e.detail);
});
Advanced implementation example
If we want to create a custom editor, using a custom set of plugins, locale, and available options, then we can opt to use the $.fn.pintura
method.
We now have to set the available plugins, load the correct locale objects, and set the default plugin options. While a lot more verbose this does allow us to create a more optimal editor package as we're omitting unneeded logic.
<!DOCTYPE html>
<link rel="stylesheet" href="pintura/pintura.css" />
<style>
.my-editor {
height: 600px;
}
</style>
<div class="my-editor"></div>
<script src="pintura/pintura-iife.js"></script>
<script src="jquery-pintura/useEditorWithJQuery-iife.js"></script>
<script src="jquery.js"></script>
<script>
// load Pintura with jQuery
useEditorWithJQuery(jQuery, pintura);
const {
// Get the default image reader and writer
createDefaultImageReader,
createDefaultImageWriter,
// The method used to register the plugins
setPlugins,
// The plugins we want to use
plugin_crop,
plugin_finetune,
plugin_annotate,
// The user interface and plugin locale objects
locale_en_gb,
plugin_crop_locale_en_gb,
plugin_finetune_locale_en_gb,
plugin_annotate_locale_en_gb,
// Because we use the annotate plugin we also need
// to import the markup editor locale and the shape preprocessor
markup_editor_locale_en_gb,
createDefaultShapePreprocessor,
// Import the default configuration for the markup editor and finetune plugins
markup_editor_defaults,
plugin_finetune_defaults,
} = $.fn.pintura;
// This registers the plugins with Pintura Image Editor
setPlugins(plugin_crop, plugin_finetune, plugin_annotate);
// Append the editor
$('.my-editor').pintura({
// The source image to load
src: 'image.jpeg',
// This will read the image data (required)
imageReader: createDefaultImageReader(),
// This will write the output image
imageWriter: createDefaultImageWriter(),
// The markup editor default options, tools, shape style controls
...markup_editor_defaults,
// The finetune util controls
...plugin_finetune_defaults,
// This handles complex shapes like arrows / frames
shapePreprocessor: createDefaultShapePreprocessor(),
// This will set a square crop aspect ratio
imageCropAspectRatio: 1,
// The icons and labels to use in the user interface (required)
locale: {
...locale_en_gb,
...plugin_crop_locale_en_gb,
...plugin_finetune_locale_en_gb,
...plugin_annotate_locale_en_gb,
...markup_editor_locale_en_gb,
},
});
</script>
Next steps
With the editor set up, we can continue to configure the editor to our liking by adjusting the available options exposed by the editor API