Images

Making images editable using MagicEdit is just about as easy as it gets. Just stick a magicedit attribute inside an IMG tag and it will become editable. You can also use me_name and me_repeat just like on a magicedit tag.

<img magicedit src="images/myImage.jpg" alt="My Image" />

The site content manager can log in, click on the edit button that appears after the image, and then upload a new image. Just like all MagicEdit functionality, the original image is untouched. It is simply replaced when a site visitor's browser requests it.

Adding magicedit inside an image tag is all you need to make it editable.

Image Sizing

By default any future image the content manager uploads will be sized the same as the original image. MagicEdit zooms and crops the image automatically to fit (yes, it actually resizes the image and does not depend on the browser to do it). In many cases this will work fine. However, there are often times when you want to constrain the image in one direction and let it be fluid in the other. Most sites are designed to scroll vertically, so you might want to fix the width and let the height be sized appropriately to maintain the original aspect ratio.

MagicEdit looks at the width and height attributes set on the image. If it has one and not the other, the image will be constrained in only that direction. For example, to set all images to be a maximum of 400 pixels wide, simply set the width to 400:

<img magicedit src="images/myImage.jpg" width="400" alt="My Image" />

If you need to do custom cropping or sizing, read on. Otherwise, you have all you need to get started with using MagicEdit on images.

Image Formats

MagicEdit will accept images in a number of formats, including JPG, PNG, and GIF. Files need to be in RGB format as well.

The system will create new images on the fly based on your sizing requirements, and these new images will generally be in the same format as your input file. For example, if you upload a JPG, any new images generated from it will also be in the JPG format (likewise for PNG images).

GIF images are the exception. Indexed color images are first converted to RGB before resizing, if the original image is a GIF the default output image will be a PNG.

Default format

You can set the default output format to be the same regardless of the input image by using cl_effects. More effects are shown below, but to force the output images to always be JPG, for example, you would do the following:

  <img magicedit me_name="myImage" src="images/myImage.jpg" cl_effects="maxsize=100,100,1;format=png" />

Here, we have a placeholder image called "myImage.jpg". If a content manager adds a new image, the new thumbnail will be saved as a PNG.

Linking to Images

In some cases you might not want to directly place the image on the page and instead link to it. This is often used in image galleries and lightbox-style image popups. Here's an example of how to link to a larger image from a thumbnail:

<a cl_image="$myImage" cl_effects="maxsize=800,600,1">
  <img magicedit me_name="myImage" src="images/myImage.jpg" width="100" alt="My Image" />
</a>

When the link is clicked on, the system will generate the image with maximum dimensions of 800 pixels wide and 600 pixels tall, then send it to the browser. If you want to link to the original image, simply omit the "cl_effects" attribute. All of the available image effects are documented below.

Note that this technique only works when the image exists in the database (i.e. the image has been edited).

Custom Image Effects

MagicEdit is built on the powerful ClearLake framework by Traction Systems. To take advantage all of the various image effects, you can also add the cl_effects attribute to your images. Here is how cl_effects work:

<img magicedit cl_effects="[type=options];[type=options]" src="image.jpg"  />

You can chain effects, and they will be applied in the order they are listed. Here are all of the effects available to you, along with examples of their use. If the arguments are in parentheses (like this), they are optional, but you must always include commas where ClearLake expects the arguments to be.

NOTE: For accessibility, you should always set an ALT attribute on your images. For the sake of brevity, we will not show that attribute in these examples.

autocrop(=threshold)

This effect just removes any clear space around the outside of the image. It looks for colors that are about the same (within a particular threshold) and just leaves what it calculates the main object of the image to be. The default threshold is 40, so leaving the argument off will autocrop with a threshold of 40. The threshold range is from 0 to 255.

An example of its usage would be:

<img magicedit cl_effects="autocrop;maxsize=300,200,1" src="image.jpg" />

This will first apply the autocrop, then scale the image to a maximum dimension of 300 pixels wide and 200 pixels tall.

To apply a more strict autocrop, lower the threshold. If you want to crop off only a solid color (for example, you don't know if users are going to be uploading images with solid borders or not), use a low threshold like 5 or 10:

<img magicedit cl_effects="autocrop=10;maxsize=300,200,1" src="image.jpg" />

centercrop=(width),(height)

This effect crops the center of an image to a size determined by the effect arguments. It has two arguments, width and height.

For example, to crop the center 100 pixels out of an image, use the following effect:

<img magicedit cl_effects="centercrop=100,100" src="image.jpg" />

crop=x,y,width,height

This effect will crop a specific portion of the image. Its four arguments are the x,y coordinate of the upper left corner of the crop box (measured from the upper left corner of the image in pixels), and the width and height of the cropped image.

For example, to crop the top left 100x100 pixels of an image, you would use the following effect:

<img magicedit cl_effects="crop=0,0,100,100" src="image.jpg" />

The utility of this is often limited if you do not know the size of the image. It would most likely be used after an image resize in most cases.

maxsize=(width),(height),(blend)

This is the most common effect, and its three optional arguments are width, height, and blend. The blend argument is a normally false boolean that determines whether the image is resampled ("blended") or not. Using this effect maintains the original image's aspect ratio, but resizes the largest dimension to the set maximum size. Here's an example:

<img magicedit cl_effects="maxsize=400,,1" src="image.jpg" />

This will resize the image to a maximum width of 400 pixels and apply blending. Since the maximum height has been left blank, there is no limit on the image's height.

minsize=(width),(height),(blend)

If you want to resize an image up (not recommended, but sometimes necessary), you can use this effect. It is very similar to maxsize, so to make an image always 400 pixels wide, even if the original image is too small, you would use the following code:

<img magicedit cl_effects="minsize=400,,1" src="image.jpg" />

size=width,height,(blend)

The size effect will force the image size, and does not maintain the image's original aspect ratio. It will resize the image to the size specified regardless of the size or aspect ratio of the original image, but this can be useful for square images. Here's an example that resizes an image to 400 pixels wide and 400 pixels tall:

<img magicedit cl_effects="size=400,400,1" src="image.jpg" />

zoom=(width),(height),(blend),(side)

The zoom effect does a resize and a center crop. This is useful for making sure the final result always fits precisely in a particular container, but it does crop the image to fit. It's an important effect since it does not distort the image, and it is the default effect applied on MagicEdit images if you do not specify cl_effects. Here's how to take an image of any size and "zoom" it to fit into a final image of 600 pixels wide and 400 pixels tall:

<img magicedit cl_effects="zoom=600,400,1" src="image.jpg" />

Now, suppose you want to create a square thumbnail of images that are portraits. The face is usually going to be at the top of the image, so if you crop the center the face gets cut off (or maybe just the top of the head). In that case, you can use the fourth option in the zoom effect: the side. To create a square thumbnail 50 pixels on a side, and just zoom to the top of the image (cropping the bottom off), you could do the following:

<img magicedit cl_effects="zoom=50,50,1,top" src="image.jpg" />

In this case, landscape oriented images are unaffected, but portrait oriented images will be cropped to the top. The options for the zoom side are:

  • top
  • right
  • bottom
  • left