Interface IImageService

Service to help create responsive img and picture tags the best possible way.

This service helps you generate advanced HTML for responsive / resized images.

Tip

We suggest you read the Image Guide for maximum power!

📔 Images Guide (Best Practices & Code)

Inherited Members
Namespace: ToSic.Sxc.Services
Assembly: ToSic.Sxc.dll
Syntax
[PublicApi]
public interface IImageService : ICanDebug
Remarks

History: Released 2sxc 13.10

Methods

| Improve this Doc View Source

Img(Object, Object, String, Object, Object, String, String, String, Object)

Get a Responsive Image object which you can then either just show, or use to construct a more customized output as you need it.

The resulting object can just be added to the html, like @img or you can work with sub-properties as specified in the IResponsiveImage

Declaration
IResponsiveImage Img(object link = null, object settings = null, string noParamOrder = "Params must be named (https://r.2sxc.org/named-params)", object factor = null, object width = null, string imgAlt = null, string imgAltFallback = null, string imgClass = null, object recipe = null)
Parameters
Type Name Description
System.Object link

What should be in this, can be:

  • a string url, in which case it would be used if url is not specified
  • a IDynamicField in which case it would be used if field is not specified
System.Object settings
  • A standardized Image-Settings object like Settings.Images.Content - see http://r.2sxc.org/settings
  • The name of a settings configuration, like "Content" or "Screen"
  • Or a dynamic object containing settings properties (this can also be a merged custom + standard settings)
  • Or a specially prepared IResizeSettings object containing all settings.

Note: If you need to construct very custom settings, use Settings(Object, String, Object, Object, Object, Object, String, String, String, Object, String, Object) to create them
System.String noParamOrder

see Convention: Named Parameters
System.Object factor

An optional multiplier, usually used to create urls which resize to a part of the default content-size. Eg. 0.5.

System.Object width

An optional, fixed width of the image
System.String imgAlt

Optional alt attribute on the created img tag for SEO etc. If supplied, it takes precedence to the alt-description in the image metadata which the editor added themselves. If you want to provide a fallback value (in case the metadata has no alt), use imgAltFallback.
System.String imgAltFallback

Optional alt attribute which is only used if the imgAlt or the alt-text in the metadata are empty. new in v15
System.String imgClass

Optional class attribute on the created img tag
System.Object recipe

Optional recipe = instructions how to create the various variants of this link. Can be any one of these:

  • string containing variants
  • Rule object

TODO: DOCS not quite ready
Returns
Type Description
IResponsiveImage

A ResponsiveImage object which can be rendered directly. See Responsive Images API in .net
Remarks

History: Added in 2sxc 13.03

| Improve this Doc View Source

ImgOrPic(Object, Object, String, Object, Object, String, String, String, Object)

Determine the best scenario (has multiple formats or not) and then return either an img (if it is not resizable and/or not multiple formats) or a picture

The resulting object can just be added to the html, like @img or you can work with sub-properties as specified in the IResponsiveImage

Declaration
IResponsiveImage ImgOrPic(object link = null, object settings = null, string noParamOrder = "Params must be named (https://r.2sxc.org/named-params)", object factor = null, object width = null, string imgAlt = null, string imgAltFallback = null, string imgClass = null, object recipe = null)
Parameters
Type Name Description
System.Object link

What should be in this, can be:

  • a string url, in which case it would be used if url is not specified
  • a IDynamicField in which case it would be used if field is not specified
System.Object settings
  • A standardized Image-Settings object like Settings.Images.Content - see http://r.2sxc.org/settings
  • The name of a settings configuration, like "Content" or "Screen"
  • Or a dynamic object containing settings properties (this can also be a merged custom + standard settings)
  • Or a specially prepared IResizeSettings object containing all settings.

Note: If you need to construct very custom settings, use Settings(Object, String, Object, Object, Object, Object, String, String, String, Object, String, Object) to create them
System.String noParamOrder

see Convention: Named Parameters
System.Object factor

An optional multiplier, usually used to create urls which resize to a part of the default content-size. Eg. 0.5.

System.Object width

An optional, fixed width of the image
System.String imgAlt

Optional alt attribute on the created img tag for SEO etc. If supplied, it takes precedence to the alt-description in the image metadata which the editor added themselves. If you want to provide a fallback value (in case the metadata has no alt), use imgAltFallback.
System.String imgAltFallback

Optional alt attribute which is only used if the imgAlt or the alt-text in the metadata are empty. new in v15
System.String imgClass

Optional class attribute on the created img tag
System.Object recipe

Optional recipe = instructions how to create the various variants of this link. Can be any one of these:

  • string containing variants
  • Rule object

TODO: DOCS not quite ready
Returns
Type Description
IResponsiveImage

A ResponsiveImage object which can be rendered directly. See Responsive Images API in .net
Remarks
  • Added in v13.03
  • picClass added in v15.04
| Improve this Doc View Source

Picture(Object, Object, String, Object, Object, String, String, String, Object)

Get a Responsive Picture object which you can then either just show, or use to construct a more customized output as you need it.

The resulting object can just be added to the html, like @pic or you can work with sub-properties as specified in the IResponsivePicture.

Important: This call only allows you to set the most common parameters factor and width. For other parameters like height, aspectRatio, quality etc. create Settings Settings(Object, String, Object, Object, Object, Object, String, String, String, Object, String, Object) and pass them in.

Declaration
IResponsivePicture Picture(object link = null, object settings = null, string noParamOrder = "Params must be named (https://r.2sxc.org/named-params)", object factor = null, object width = null, string imgAlt = null, string imgAltFallback = null, string imgClass = null, object recipe = null)
Parameters
Type Name Description
System.Object link

What should be in this, can be:

  • a string url, in which case it would be used if url is not specified
  • a IDynamicField in which case it would be used if field is not specified
System.Object settings
  • A standardized Image-Settings object like Settings.Images.Content - see http://r.2sxc.org/settings
  • The name of a settings configuration, like "Content" or "Screen"
  • Or a dynamic object containing settings properties (this can also be a merged custom + standard settings)
  • Or a specially prepared IResizeSettings object containing all settings.

Note: If you need to construct very custom settings, use Settings(Object, String, Object, Object, Object, Object, String, String, String, Object, String, Object) to create them
System.String noParamOrder

see Convention: Named Parameters
System.Object factor

An optional multiplier, usually used to create urls which resize to a part of the default content-size. Eg. 0.5.

System.Object width

An optional, fixed width of the image
System.String imgAlt

Optional alt attribute on the created img tag for SEO etc. If supplied, it takes precedence to the alt-description in the image metadata which the editor added themselves. If you want to provide a fallback value (in case the metadata has no alt), use imgAltFallback
System.String imgAltFallback

Optional alt attribute which is only used if the imgAlt or the alt-text in the metadata are empty. new in v15
System.String imgClass

Optional class attribute on the created img tag
System.Object recipe

Optional recipe = instructions how to create the various variants of this link. Can be any one of these:

  • string containing variants
  • Rule object

TODO: DOCS not quite ready
Returns
Type Description
IResponsivePicture

A ResponsivePicture object which can be rendered directly. See Responsive Images API in .net
Remarks

History:

  • Added in v13.03
  • picClass added in v15.04
| Improve this Doc View Source

Recipe(String)

Declaration
Recipe Recipe(string variants)
Parameters
Type Name Description
System.String variants
Returns
Type Description
Recipe
| Improve this Doc View Source

Recipe(Recipe, String, String, Int32, String, IDictionary<String, Object>, IEnumerable<Recipe>, Nullable<Boolean>, Nullable<Boolean>, String, String, String)

Declaration
Recipe Recipe(Recipe recipe, string noParamOrder = "Params must be named (https://r.2sxc.org/named-params)", string name = null, int width = 0, string variants = null, IDictionary<string, object> attributes = null, IEnumerable<Recipe> recipes = null, bool? setWidth = default(bool? ), bool? setHeight = default(bool? ), string forTag = null, string forFactor = null, string forCss = null)
Parameters
Type Name Description
Recipe recipe
System.String noParamOrder
System.String name
System.Int32 width
System.String variants
System.Collections.Generic.IDictionary<System.String, System.Object> attributes
System.Collections.Generic.IEnumerable<Recipe> recipes
System.Nullable<System.Boolean> setWidth
System.Nullable<System.Boolean> setHeight
System.String forTag
System.String forFactor
System.String forCss
Returns
Type Description
Recipe
| Improve this Doc View Source

Settings(Object, String, Object, Object, Object, Object, String, String, String, Object, String, Object)

Construct custom Resize-Settings as needed, either based on existing settings or starting from scratch

Declaration
IResizeSettings Settings(object settings = null, string noParamOrder = "Params must be named (https://r.2sxc.org/named-params)", object factor = null, object width = null, object height = null, object quality = null, string resizeMode = null, string scaleMode = null, string format = null, object aspectRatio = null, string parameters = null, object recipe = null)
Parameters
Type Name Description
System.Object settings
  • A standardized Image-Settings object like Settings.Images.Content used as a template - see http://r.2sxc.org/settings
  • The string name of a template settings , like "Content" or "Screen"
  • a bool true/false - if true, the normal "Content" configuration is used as a template, if false, no initial configuration is used
  • Or a dynamic object containing settings properties (this can also be a merged custom + standard settings)
  • Or a specially prepared IResizeSettings object containing all settings.
System.String noParamOrder

see Convention: Named Parameters
System.Object factor

A multiplier, usually used to create urls which resize to a part of the default content-size. Eg. 0.5.

System.Object width

Optional width parameter. Cannot be used if factor is set. Usually takes the default from the settings.
System.Object height

Optional height parameter. Can only be 0 if factor is set, no not specify a height. Usually takes the default from the settings.
System.Object quality

Optional quality parameter. Usually takes the default from the settings.
System.String resizeMode

Optional resize-mode, like crop or max. Usually takes the default from the settings.
System.String scaleMode

Optional scale-mode to allow up-scaling images like up or both. Usually takes the default from the settings.
System.String format

Optional file format like jpg or png
System.Object aspectRatio

Aspect Ratio width/height, only relevant if a factor is supplied. Usually takes default from the settings or is ignored.

System.String parameters
  • the parameters either as id=47&amp;name=daniel (Dnn also supports /id/47/name/daniel)
  • it can also be an IParameters
System.Object recipe

WIP - not ready yet
Returns
Type Description
IResizeSettings

A settings object which has all the parameters as configured
Remarks

History: Added in 2sxc 13.03