Release 0.1.6

We focused on a single significant feature in this release. And we think we nailed it! You can now edit your images directly in the CMS.

There are a number of components to image editing that we wanted to address with this release to make the process of editing images as fun, simple, and intuitive as possible for content editors while also making it flexible for template developers and making it fast and secure for live websites.

First: The Old Method

Before this release, we had utilized a URL-based API for editing images, which had a series of drawbacks:

1. Editing images can potentially take a significant amount of processing power, and the URL API had to be available from live sites. Despite some built-in DOS-prevention measures in the library we use to edit images, that still left a lot of room for people to abuse the API and prevent legitimate images from being served in the case of an "attack".
2. You had to know what url variables were available in order to use them, and since we did not have an interface for creating image URLs that meant that only a handful of developers actually knew how to use them.
3. It was difficult to encourage consistency for images across the site since the editing was happening outside of the CMS in an environment that we cannot influence.
4. There was potentially confusion between setting height and width properties in the HTML vs resizing the height and width of the image.
5. This generated a lot of ugly URLs on live sites (eg: https://images.marketpath.com/a894178f-28ad-4b08-947e-15c08f642963/image/d0ce48ee-d6dc-4167-857c-9f4a559458c1/llama_on_machu_picchu[1].jpg?width=250&height=250&mode=max).

For now, the old image URL API is still enabled. It is deprecated, however, while we work on moving all old sites that utilize those images to a new approach. You should not utilize the URL API for any new images or else they will stop being displayed correctly when the URL API is turned off (probably sometime in the next couple of months).

Next: The New Method

The new method is actually fairly simple at it's core. Instead of creating a new URL for each generated image, you actually create a whole new image. We even made it easy for you to do this anywhere that the images are listed or selected.

From the Image Dialog:

1. In your main site navigation, select "Images". For each image, the last action available is "Edit Image" and looks like a wand. Clicking on that action opens up our brand new image editing interface.
2. The first thing you will notice about the interface is that the image you are editing takes up the entire window (unless the image is smaller than the window, in which case it will be displayed at its actual size). The controls for editing the image are at the bottom of the window by default, but you can move them to the top, left, or right of the window if desired by clicking on the third icon ("Editor Settings") and changing the "Button Display" value.
3. Feel free to explore the rest of the controls. Any time you change a setting that affects how the image is displayed, you can easily "Undo" (or "Redo") the setting, although at the moment that does not apply to changing the image you are editing using the "Select Picture" control. There is a lot more included in this interface than we have space to write about here, so keep your eyes peeled for a full image editing tutorial if you have any unanswered questions about this interface.
4. When you are ready to save your image, you have two options, "Save & Replace" and "Save & Copy". If you are unsure which option you want to choose, you should definitely use "Save & Copy" since "Save & Replace" may have undesired consequences. Especially note that due to browser and CDN caching, the "Save & Replace" option may take a very long time to be visible to end users.

From the HTML Editor:

1. Click the "Add Image" button in the editor, just like you used to.
2. In the Images dialog that appears, you can either edit an image and then select it, or you can select it and then edit it.
3. After selecting the image, the first two controls in the resulting popup are "Replace" and "Edit Image". Both options work! Note that there is another control, "Change Size", which allows you to specify the height and width of the image. The "Change Size" control ONLY changes the height and width in the resulting markup - the image itself will still be the original size.

From the Page Editor:

1. Edit a page that includes an image custom field (eg: for a header or background image).
2. Click on the custom field to select an image.
3. In the Images dialog that appears, you have the old option to select the image, but you also have a new option to "Edit Image".
4. If you choose to edit an image before selecting it, the edit image interface will pop up. When you are done editing the image, the edit image interface will disappear and the "Select Image" dialog will refresh so that you can select your newly-created image.

More: Image Presets

We want to make it as simple, fun, and intuitive as possible to edit images in the CMS, and it can sometimes be annoying to try and remember your exact settings if you want to make multiple images look the same (eg: height/width, padding, shadow, etc...). To ease that pain, we created Image Presets. Image Presets are simply a saved group of effects that can either be applied to images programmatically by template developers or as desired by content editors while editing images. The process of creating and applying image presets is very simple:

1. Edit an image (or, alternatively, edit an existing preset)
2. Select the effects you want to apply in the preset
3. It is a good idea to review the effects you have selected by clicking on the "Info" control in the image editor before saving the preset. You can remove undesired effects by clicking on it in the "Info" tab.
4. When you are done selecting your effects, click on the "Save" control. If you are editing an image, select "Create Preset". If you are editing a preset this will already be selected for you.
5. Enter a helpful and intuitive code. Some good examples of codes that describe what they are used for might be "crop250" (crop the image to 250px wide), "thumb100" (constrain the image to 100px wide), or "blueBorder6" (add a 6px blue border to the image).
6. You are allowed to enter the same code as another preset that has already been created on the site, but that is not recommended as you will overwrite the settings on the previous preset, which may make the website look funny if that code is being used by a template developer and has already been used to generate images on the live site.
7. Click "Create" to create the preset.
8. If you used an existing preset code, you will be prompted to confirm that you actually want to update the existing code. Only click "Continue" if you are sure that is what you want to do (see previous warning for why that might not be a good idea).

Note that existing presets are stored under the "Develop" section of the site navigation - above Javascript, Stylesheets, and Templates.

Finally: From Templates

If you are a template developer, this probably all sounds well and good but you are no doubt interested in how you should use this new functionality in your templates. Once again, we tried to keep the solution simple and flexible. All image manipulation in templates should be done using Image Presets. The first step is to create any image presets you may want to apply to images on the site. Then in your templates, you can take advantage of a new Liquid Tag: "{% ImageUrl %}". All this tag does is returns a new URL for any image on your site with the specified presets applied. Here is the syntax:

{% ImageUrl (output_to_template | variable [output_to_template]) Image [name:"filename"] [extension:"ext"] ["code1" [code2 [etc...]]] %}

OK. That is a little ugly. Let's try to clarify:

1. The first thing you need is the "ImageUrl" tag. If you are a template developer then this is probably obvious.
2. Next, write "output_to_template" to simply output the new URL directly to the template. Alternatively, you could include a variable name to save the URL to. Or, if you want both, simply write both - with the variable name BEFORE "output_to_template" (eg: {% ImageURL my_image_url output_to_template page.header_image %}
3. Third, you need to include a reference to the image that you want to modify. This should also be fairly obvious, but if you do not reference an image on the site then this won't work.
4. You can optionally specify a filename for the generated image. This also may be useful for "uncaching" images if you edit a preset and want users to load the image from the server instead of from their browser cache.
5. You can also optionally specify an extension for the generated image. This may be useful if one of your presets converts the image to an alternate format (eg: .png in order to apply transparency) so that it does not confuse the browser to request an image in one format and receive it in another.
6. Finally, you can supply as many image preset codes as desired to be applied to the image. Furthermore, since image presets codes cannot have spaces, you can potentially include multiple codes in a single parameter.

Examples:

• {% ImageUrl output_to_template entity.image %}
• {% ImageUrl variable page.banner_image name:"home-banner" "banner-size" "sepia-simple" %}
• {% capture imageCode %}thumb-{{size}} border-{{bordercolor}}{% endcapture %}{% ImageUrl variable output_to_template img.GUID extension:"png" "transparent20" "border10" imageCode %}