Interesting.AdvancedImages 1.0.9

Advanced Images by Interesting

Advanced Images is a Kentico module that allows cropping and quality controls via query string for media library images as well as Media Request Protection that ensures server resources are only spent on image URLs generated by the server.

Supported Kentico Versions

Currently, this has only been tested on Kentico 10, however it may work on previous versions.

Assumes

• User of this package can install nuget packages in to their Kentico solution
• User of this package wants the ability to alter media images via query string and/or the ability to protect their media query strings with a hash parameter automatically

Limitations

• The current implementation of Advanced Images only works with /getmedia URLs. /getfile and /getmetafile URLs are not impacted by the module. This will be considered in future releases.

Query string parameters

Any media library URL can have the default Kentico media query string parameters (width, height, maxsidesize), and Advanced Images adds a few more. Below is a table explaining them in more detail.

When the Advanced Images module has been successfully installed, the additional query string parameters for cropping and quality will be honoured on /getmedia URLs regardless if any of the other Advanced Imagees options are enabled (Media Request Protection and JS/CSS minification).

1. cropwidth Sets the width of the cropped image. If this is combined with the default Kentico width parameter, the cropwidth must be less than the width parameter for this to have any effect. Default: null Required: No
2. cropheight Sets the height of the cropped image. If this is combined with the default Kentico height parameter, the cropheight must be less than the height parameter for this to have any effect. Default: null Required: No
3. cropanchor Sets the crop position and instructs the module where to base the crop. Valid values are: center, topleft, top, topright, right, bottomright, bottom, bottomleft, left. This parameters is only valid if combined with cropwidth and/or cropheight. Default: center Required: No
4. quality Sets the quality of the resized or cropped image. If this parameter is not included, quality defaults to the setting defined in Admin > Settings > Content > Media > Advanced Images > Thumbnail Quality. Default: Defaults to the Thumbnail Quality setting. Required: No
5. hash This value is an encrypted string of the entire query string. This is only required when the Media Request Protection feature is enabled (Admin > Settings > Media > Advanced Images > Media Request Protection). This should not be set manually. If the Media Request Protection feature is enabled, and this value is not being generated automatically, the URL will need to be generated using the Generate Protected Media URL page in the Advanced Images module pages (Admin > Advanced Images > Generate Protected Media URL). See the When is the hash parameter automatically generated? section below for more information. Default: null Required: Yes if the Media Request Protection feature is enabled. No otherwise.

An example of a URL with Advanced Images parameters would be:

/getmedia/1de9dd92-8bc0-40e6-87a6-375cb05d1c6c/buddha.aspx?width=1001&height=600&ext=.jpg&cropwidth=203&cropanchor=bottomright&quality=55

If the Media Request Protection feature is enabled, and protected URLs need to be manually generated, the following URL can be obtained by going to the Generate Protected Media URL page and pasting the above URL in to the Media URL box (notice the hash parameter has been added). Please see the When is the hash parameter automatically generated? section below for more information.

/getmedia/1de9dd92-8bc0-40e6-87a6-375cb05d1c6c/buddha.aspx?width=1001&height=600&ext=.jpg&cropwidth=203&cropanchor=bottomright&quality=55&hash=a28c3aa3f10391a269c0cd1433ac3270876ebbcb232729287ad149e71889ddc0

When is the hash parameter automatically generated?

When the Media Request Protection feature is enabled, a valid hash query string paramter must be present on the image URL in order for the width/height/cropwidth/cropheight/quality parameters to be honoured.

If the hash query string parameter is not present, Kentico returns the original, unaltered image. Requests for the original image (without any resizing/scaling parameters) work as usual and are not restricted.

By default, any image links (link starting with /getmedia) rendered in the HTML will be automatically modified to include a hash query string parameter. This includes any inline JavaScript or inline CSS. For external CSS/JS files that are not rendered in to the HTML, links to images inside these files can be updated automatically when these files are served to the browser, however, the following conditions need to be met:

• Media Request Protection must be enabled (Admin > Settings > Content > Media > Advanced Images)
• JS/CSS Minification must be enabled (Admin > Settings > System > Performance > Resources)
• JS/CSS files must be served from the Kentico GetResource page (this page provides minfication functionality).
  • JS files must be served from ~/CMSPages/GetResource.ashx?scriptfile=<path to JS file>
  • CSS files must be served from ~/CMSPages/GetResource.ashx?stylesheetfile=<path to CSS file>

When the above conditions are not met (ie cases when minification is not enabled/desired), any static URLs will need to contain the hash parameter and the Generate Protected Media URL tool can be used to generate URLs with the hash query string parameter. The resulting image URL can then be used in JS/CSS files so the images will render correctly.