36 votes

Slimsy

Effortless Responsive Images with Slimmage and Umbraco

Note Slimsy v1.1.6+ requires Umbraco v7.3.0+ (for earler versions of Umbraco use Slimsy v1.1.5 from the archive)

Slimmage.js used in conjunction with ImageProcessor.Web (included in Umbraco v7.1) and the built-in Umbraco Image Cropper will make your responsive websites images both adaptive and "retina" quality (if supported by the client browser).

Slimsy installs everything you need to use Slimmage.js in Umbraco v7.1. It includes Slimmage.js, SlimResponse and some helper methods that work with both dynamic and typed published content models.

Implementing post package installation

1. Add slimmage.js to your pages

In your master template add the Slimmage Javascript file(s) to the top of your head section (Slimmage should be the first js library)

without bundling scripts (plain HTTP requests)

    <script type="text/javascript">
        window.slimmage = { verbose: false };
    </script>
    <script src="/scripts/slimmage.min.js"></script>

with bundling of your scripts you can fetch the configuration from a separate file

    <script src="/scripts/slimmage.settings.js"></script>
    <script src="/scripts/slimmage.min.js"></script>

If you don't already have js bundling in place you should take a look at the Optimus package, it will allow you to bundle them together in minutes.

2. Adjust your image src attributes

Use the GetResponsiveImageUrl or GetResponsiveCropUrl methods on your dynamic or typed content/media items. For these methods to function correctly your image property types should use the built-in Image Cropper.

GetResponsiveImageUrl(width, height)

use this method for setting the crop dimensions in your Razor code, assumes your image cropper property alias is "umbracoFile"

e.g. An initial image size of 270 x 161. This example is looping pages, each page has a media picker with property alias "Image"

@foreach (var feature in homePage.umbTextPages.Where("featuredPage"))
{
    <div class="3u">
        <!-- Feature -->
        <section class="is-feature">
            @if (feature.HasValue("Image"))
            {
                var featureImage = Umbraco.Media(feature.Image);
                <a href="@feature.Url" class="image image-full">
                <img src="@featureImage.GetResponsiveImageUrl(270, 161)" alt="" />
                </a>
            }
            <h3><a href="@feature.Url">@feature.Name</a></h3>
            @Umbraco.Truncate(feature.BodyText, 100)
        </section>
        <!-- /Feature -->
    </div>
}

e.g. If you need only a width dimension (and a flexible height) set height parameter to 0

    <img src="@featureImage.GetResponsiveImageUrl(270, 0)" alt="" />

GetResponsiveImageUrl(width, height, propertyAlias)

Overloaded method, with additional propertyAlias parameter to specify your image cropper property alias.

e.g. An initial image size of 270 x 161, Image Cropper property alias of "Image"

    <img src="@featureImage.GetResponsiveImageUrl(270, 161, "Image")" alt="" />

e.g. If you need only a width dimension (and a flexible height) set height parameter to 0

    <img src="@featuredNewsItem.GetResponsiveImageUrl(859, 0, "Image")" alt="" />

GetResponsiveImageUrl(width, height, propertyAlias, outputFormat)

Overloaded method, with additional outputFormat parameter so you can specify if this image should be returned as a specific format type.

e.g. If you wanted a image to always be returned as a png

    <img src="@featureImage.GetResponsiveImageUrl(270, 161, "Image", "png")" alt="" />

GetResponsiveCropUrl(cropAlias)

use this method when you want to use a predefined crop, assumes your image cropper property alias is "umbracoFile".

    <img src="@featureImage.GetResponsiveCropUrl("home")" alt="" />

GetResponsiveCropUrl(cropAlias, propertyAlias)

Overloaded method, with additional propertyAlias parameter to specify your image cropper property alias.

    <img src="@featureImage.GetResponsiveCropUrl("home", "Image")" alt="" />

GetResponsiveCropUrl(cropAlias, propertyAlias, outputFormat)

Overloaded method, with additional outputFormat parameter so you can specify if this image should be returned as a specific format type.

    <img src="@featureImage.GetResponsiveCropUrl("home", "Image", "png")" alt="" />

Advanced Options

By default Slimsy v1.1.0+ will request that all images generated by ImageProcessor are jpg as this provides the best compression and optimisation, this is regardless of the source image type. You can disable this behaviour by adding the following appsetting to web.config.

<add key="Slimsy:Format" value="false"/>

The above overloaded methods specifying outputFormat will of course take precedence over this default.

If you really wanted to have all default URLs return pngs you could also do this

<add key="Slimsy:Format" value="png"/>

Added in Slimsy v1.1.2 - you can now specify the default background color by added another appsetting to web.config. As an exmaple this setting is used if ImageProcessor is converting a png to a jpg and it as some transparency

<add key="Slimsy:BGColor" value="fff"/>

Credits and references

This project includes Slimmage and SlimResponse Both projects are MIT/Apache dual licensed by Imazen.

Many thanks to Douglas Robar for naming Slimsy.

Upgrades

Slimsy v1.1.4 includes the update to Slimmage.js v0.4.1 - for this version of Slimmage you must ensure your images have the max-width:100% css property.

Change log

Here

Screenshots

 Download package
version 1.1.7

Project owner

Jeavon Leopold

Jeavon Leopold

Jeavon has 11897 karma points

Project Compatibility

This project is compatible with the following versions as reported by community members who have downloaded this package:
Untested or doesn't work on Umbraco Cloud
7.5.x (untested)
7.4.x (100%)
7.3.x (73%)
7.2.x (100%)
7.1.x (100%)
7.0.x (untested)
6.1.x (untested)
6.0.x (untested)

You must login before you can report on package compatibility.

Project Information

  • Project owner: Jeavon Leopold
  • Contributors: Marc Stöcker
  • Created: 22/05/2014
  • Current version 1.1.7
  • .net Version 4.0,4.5
  • License MIT
  • Downloads: 4802

External resources

Our.umbraco.org is the community mothership for Umbraco, the open source asp.net cms. With a friendly forum for all your questions, a comprehensive documentation and a ton of packages from the community. This site is running Umbraco version 7.5.6