# Jcrop Instances

stage /stāj/ a raised floor or platform, typically in a theater, on which actors, entertainers, or speakers perform

Jcrop is totally object-oriented. If you have a complete understanding of Javascript, object-oriented programming, and web development/debugging techniques, this documentation may be superfluous.

In object-oriented programming, an important distinction exists between the object definition (usually a class) and instances of that object. Javascript has historically had an unusual inheritance method based on prototypes, but the concept of instances is still the same. Frequently, object instances are created using the new keyword.

# Creating an Instance

You're probably already familliar with creating a Jcrop instance:

const jcrop = Jcrop.attach('target');

To use an instance, you will most likely want to store it in a variable as shown here. To avoid confusion, this documentation uses the variable jcrop to indicate a Jcrop instance.

# Attaching to any element

Jcrop attaches to any DOM element easily. The element can be passed as a Javascript object or a string that matches the ID of an element already in the DOM.

<img src="picture.jpg" id="target">

<script>
  Jcrop.attach('target');
</script>

• Element must exist in the DOM
• Element should be an image or block element
• An HTMLElement object may be passed
• If a string is passed, document.getElementById() is used

# Attaching to images

Images get slightly special treatment when you attach a Jcrop instance.

• Container element created and CSS classes assigned to it
• Container element inserted where the image tag exists in the DOM
• Image element is moved inside the container element

The effect of this is that the image is wrapped in a container which allows Jcrop to position its UI elements on top of the image. Please inspect the structure of the elements and how CSS is applied to them if you are having layout issues using Jcrop with your current CSS.

Because of these positioning needs, the container is position: relative and the image is made position: absolute. The container element is then sized to the size of the image element in the DOM. Also note that an onload handler is attached to the image, so that the container size can be updated when/if an image becomes loaded.

# Preloading Images

The most common use case for Jcrop is cropping an image. For Jcrop to properly initialize in such a case, the image must already be loaded in the DOM (at least enough to have width and height available). Jcrop provides a convenient static method to ensure that an image is pre-loaded before Jcrop is attached:

<img src="https://d3o1694hluedf9.cloudfront.net/sierra-750.jpg" id="target">

Jcrop.load('target').then(img => Jcrop.attach(img,options));

Of course, the Jcrop.load() static method can take an element as well. If you wanted to create the Image element programatically, just make sure you add it to the DOM.

const myImage = new Image();
myImage.src = 'https://d3o1694hluedf9.cloudfront.net/sierra-750.jpg';
document.getElementById('container').appendChild(myImage);
Jcrop.load(myImage).then(img => Jcrop.attach(img,options));

# Instance Methods

# setOptions(options)

Jcrop options can be changed on-the-fly using the setOptions() method. The instance will react to any changed options immediately.

jcrop.setOptions({ shade: false });

# addWidget(widget)

Add an existing cropping widget to the Jcrop instance. To use this method, you'll need to create the cropping widget first. This method is called internally when newWidget() is used (see below).

const widget = Jcrop.Widget.create();
jcrop.addWidget(widget);

Note that this code would create a widget and attach it to the Jcrop stage instance, but it will probably require some positioning and other configuration. It's recommended to use a Rect with the newWidget() method instead.

# newWidget(rect,options)

Add a new cropping widget using a Rect object. Rect objects define a rectangular region.

const rect = Jcrop.Rect.fromPoints([100,100],[200,200]);
jcrop.newCropper(rect,{ aspectRatio: rect.aspect });

# CSS class management

• addClass(classname)
• removeClass(classname)
• hasClass(classname)

As a class extended from DomObj, the methods addClass(), removeClass() and hasClass() are available to manage CSS classes on the container element. There are some useful classes that can be added to the container (or a parent element) to affect the UI/UX of the instance.

# Instance Properties

# active

Contains a reference to the most recently selected or active widget. Once any widget is attached to the instance, the active property will always contain a value, unless all widgets are removed from the instance.

# crops

A Set that contains any crop widgets currently attached to this Jcrop instance. The last widget in the Set is the active widget.

# el

Contains a reference to the DOM element that this Jcrop instance is attached to. This is almost always a div or block element of some type.

# options

The options object for the Jcrop instance. While you may read from this object, it's recommended that you do not update it directly. Use the setOptions() method described above if you want to modify the options after the instance has been created.

# srcEl

This property is only defined if the ImageStage is being used. It contains a reference to the original source image after wrapping.

# Removing an Instance

Jcrop instances provide a destroy() method to remove the instance.

jcrop.destroy();

This feature is not well defined currently. No guarantees are made. 😃