Gentics CMS-OSS Documentation

Chapters

1. Usage

   • Resize modes

   • Crop and resize mode

   • Degree of compression

2. Gentics CMS

   • Handlebars Helper

   • Render Directive

   • Static Cross Node Projects

   • Publishing

   • Restricting parallel resize requests

3. Servlet Parameters

   • cacheKeyQueryParameters

   • portalBasePath

   • portalBasePathRegEx

   • urlPrefix

   • uriMapper

   • Request Decorators

   • loadTimeout

4. Caching

1 Usage

/GenticsImageStore/[width]/[height]/[mode]/[imageurl]

Example:

<img src="/GenticsImageStore/<node width>/auto/prop/<node bild>">

1.1 Resize modes

/GenticsImageStore/[width]/[height]/[mode]/[imageurl]

The following modes are available:

• prop used for proportional resizing. The aspect ratio of the image will be preserved. When target width and height do not match the original image proportions, the lower value (height, width) will be used for resizing.
• force used for forced resizing. The aspect ratio of the original image will not be preserved when this mode is used. If the original aspect ratio of the image is different than the resized aspect ratio, the image will be distorted.
• smart used for automatic resizing and cropping of images.

1.2 Crop and resize mode

Additionally the special ‘cropandresize’ mode can be used to crop images.

/GenticsImageStore/[width]/[height]/cropandresize/[mode]/[topleft_x]/[topleft_y]/[cropwidth]/[cropheight]/[imageurl]

Parameter:

1.3 Degree of compression

The compression value for JPEG is a value from 0.0 (max compression) to 1.0 (min compression). By default this value is set to 0.9 and can be configured inside your node.conf like following:

image_resizer_jpeg_quality: "1.0"

2 Gentics CMS

2.1 Handlebars Helper

See gtx_gis Helper for details of how to include a resized image into a handlebars tag.

2.2 Render Directive

To include a resized image into a velocity tag, this should be done with the directive #gtx_gis.

<img src='#gtx_gis($image, $resize)'>

or, when cropping shall be done:

<img src='#gtx_gis($image, $resize, $crop)'>

The $image may be an image from the same or from another node.

2.2.1 Parameters

2.2.2 Resize options

2.2.3 Cropping options

2.2.4 Usage examples

The following example assumes, that the tag has a part img of type URL (Image):

#set($image = $cms.tag.parts.img.target)##
<img src='#gtx_gis($image, {"width": 100, "height": 100, "mode": "prop"})'>

It is also possible, to define the resizing parameters in a separate variable (which can be reused in the template):

#set($image = $cms.tag.parts.img.target)##
#set($resize = {"width": 50, "mode": "smart"})##
<img src='#gtx_gis($image, $resize)'>

Additionally, when cropping shall be done, the cropping parameters have to be passed as (optional) third parameter:

#set($image = $cms.tag.parts.img.target)##
#set($resize = {"width": 50, "mode": "smart"})##
#set($crop = {"x": 10, "y": 10, "width": 30, "height": 30})##
<img src='#gtx_gis($image, $resize, $crop)'>

2.3 Static Cross Node Projects

The GenticsImageStore is also able to resize images in foreign nodes. A page in node A may contain the following image url:

http://www.node-b-hostname.tld/GenticsImageStore/300/auto/prop/Content.Node/images/flower.jpg

Such an url will be identified by the GenticsImageStore during the publish process. The GenticsImageStore identifies the referenced node by examining the hostname within the found url. The image within node B will be resized when the GenticsImageStore determines that the referenced node (in this case node b) is publishing into the file system. Resizing will otherwise be omitted.

The image tag must be adapted to include the node B hostname.

Example velocity implementation:

#set( $nodePath = "$cms.tag.parts.src.target.folder.node.path")
#set( $pubdir = "$cms.tag.parts.src.target.folder.pub_dir")
#set( $imagePath = "$cms.tag.parts.src.target.name")

## Remove the trailing slash from the pub_dir
#set( $pubdir = $pubdir.trim())
#if($pubdir.endsWith("/"))
#set( $len = $cms.imps.velocitytools.math.sub($pubdir.length(),1) )
#set( $pubdir = $pubdir.substring(0, $len))
#end

## Remove the trailing slash from the nodePath
#set( $nodePath = $nodePath.trim())
#if($nodePath.endsWith("/"))
#set( $len = $cms.imps.velocitytools.math.sub($nodePath.length(),1) )
#set( $nodePath = $nodePath.substring(0, $len))
#end

#if($cms.rendermode.publish)
<img  src="http://${cms.tag.parts.src.target.folder.node.host}/GenticsImageStore/300/auto/prop${nodePath}${pubdir}/${imagePath}"/>
#else
<img src="/GenticsImageStore/300/auto/prop/$cms.tag.parts.src.target.url" />
#end

2.4 Publishing

Resized images will be written to the file system when the GenticsImageStore was used within the project. The usage will be determined by examining the final page content. All GenticsImageStore URLs will be processed. The GenticsImageStore will invoke the resizing of a page when the GenticsImageStore finds a resize call within a published page. The resized image will be written to a folder called GenticsImageStore within the pub directory of that particular node. Please note that this directory has to be synced with the target webserver as well.

2.5 Restricting parallel resize requests

Requests to the CMS for resizing images might consume large amounts of memory. If too many requests are handled at the same time, this might even cause OutOfMemory situations. Therefore, the maximum number of actual resize operations is per default limited to 10.

This can be configured in the CMS configuration files:

gis_requests: 5

3 Servlet Parameters

The GenticsImageStore can be used within Portal implementations. The configuration is performed using the following servlet parameters.

3.1 cacheKeyQueryParameters

This parameter can be used to modify the internally used cache key for cached images. It is possible to specify certain get parameters. These parameters will then be used (if available) to enhance the cache.key. Normally all other query parameters will not be used for generating the cache key. The parameters can be specified in a comma-separated list. This parameter is useful when the images will be retrieved using a servlet that uses query parameters to identify the image that should be loaded.

Example:

	<init-param>
			<param-name>cacheKeyQueryParameters</param-name>
			<param-value>contentid,type,mycustomparam</param-value>
	</init-param>

3.2 portalBasePath

The portal base path is used to identify the image url within a GenticsImageStore url. The default value is “/Portal.Node”. The used prefix can be adapted using this parameter. This is useful of images will not be delivered by Portal.Node.

	<init-param>
			<param-name>portalBasePath</param-name>
			<param-value>/MyWebapp</param-value>
	</init-param>

3.3 portalBasePathRegEx

This parameter has the same functionality as the portalBasePath. It is possible to configure multiple basepaths by using a regular expression. When set, this parameter has priority over portalBasePath.

	<init-param>
		<param-name>portalBasePathRegEx</param-name>
		<param-value>(\/Portal\.Node.*)|(\/GCN5_Portal.*)</param-value>
	</init-param>

3.4 urlPrefix

By default the image will be loaded from the host that received the initial GenticsImageStore request. The urlPrefix setting can be used when the image should be loaded from a different host.

	<init-param>
		<param-name>urlPrefix</param-name>
		<param-value>http://localhost:8080/</param-value>
	</init-param>

3.5 uriMapper

An addition to the uriPrefix is the uriMapper parameter. This parameter allows specifying a custom implementation that is able to modify the image uri. It is therefore possible to customize the uri according to set uri parameters or hostnames.

To achieve this, one has to implement the interface com.gentics.api.imagestore.ImageUriMapper. The name of the implemented class has to be set as value for the “uriMapper” parameter. Please note that the full package name has to be specified. The implemented class must be able to be loaded by the Servlet ClassLoader.

Interface:

public interface ImageUriMapper {

	/**
	 * Maps a request for an image to an URI where the image can be fetched from.
	 *
	 * This method should have no side effects and should always return the same URI
	 * for the given imageUri and the parameters in the given servletRequest.
	 *
	 * Further, this method should be idempotent such that passing back the returned URI
	 * to this method again returns the given URI unchanged.
	 *
	 * @param servletRequest
	 * 		  The request that fetches the image.
	 * @param imageUri
	 * 		  The URI of the image to fetch.
	 * @return
	 * 		  May either return the given URI unchanged, or an alternate URI
	 * 		  where the image will be fetched from instead.
	 */


	URI mapImageUri(HttpServletRequest servletRequest, URI imageUri);

}

	<init-param>
		<param-name>uriMapper</param-name>
		<param-value>com.example.ImageUriMapperImpl</param-value>
	</init-param>

3.6 Request Decorators

This parameter allows a custom implementation to be specified that will intercept requests to the GenticsImageStore and modify them as desired.

For this to be done, an implementation of the interface com.gentics.api.imagestore.RequestDecorator has to be specified in the configuration. The name of the implemented class (including the full package name) has to be set as value for the “requestDecorator” parameter. As with the uriMapper, the implemented class must be able to be loaded by the Servlet ClassLoader.

Interface:

public interface RequestDecorator {

	/**
	 * Provides the ability to alter parameters of requests sent to the GenticsImageStore
	 *
	 * @param gisRequest
	 * 		  The GenticsImageStoreRequest Bean containing request information
	 * @param request
	 * 		  The HttpServletRequest object containing request information
	 */
	void decorateRequest(GenticsImageStoreRequest gisRequest, HttpServletRequest request);

}

	<init-param>
		<param-name>requestDecorator</param-name>
		<param-value>com.example.RequestDecoratorImpl</param-value>
	</init-param>

For use in Gentics CMS, the RequestDecorator class must be configured in the node.conf with the setting gis_request_decorator, for example:

gis_request_decorator: "com.example.RequestDecoratorImpl"

3.7 loadTimeout

This parameter defines the timeout used for loading the original image for resizing in milliseconds. The default is 60000 ms (= 1 minute).

	<init-param>
		<param-name>loadTimeout</param-name>
		<param-value>5000</param-value>
	</init-param>

4 Caching

The GenticsImageStore uses the JCS Cache which can be configured using the cache.ccf file.

Example Cache Region Configuration:

jcs.region.gentics-content-imagestorecache=DC
jcs.region.gentics-content-imagestorecache.cacheattributes.MaxObjects=0
jcs.region.gentics-content-imagestorecache.elementattributes.MaxLifeSeconds=86400