Table of Contents

Interface IImageService

Namespace
ToSic.Sxc.Services
Assembly
ToSic.Sxc.dll

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)

[PublicApi]
public interface IImageService : ICanDebug
Inherited Members

Remarks

History: Released 2sxc 13.10

Methods

Img(object, object, NoParamOrder, Func<ITweakMedia, ITweakMedia>, object, object, string, string, string, object, object, 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

IResponsiveImage Img(object link = null, object settings = null, NoParamOrder noParamOrder = default, Func<ITweakMedia, ITweakMedia> tweak = null, object factor = null, object width = null, string imgAlt = null, string imgAltFallback = null, string imgClass = null, object imgAttributes = null, object toolbar = null, object recipe = null)

Parameters

link object

What should be in this, can be:

  • a string url, in which case it would be used if url is not specified
  • a IField in which case it would be used if field is not specified
settings object
  • The name of a settings configuration, like "Content", "Screen", "Square", etc.
  • A standardized Image-Settings object like Settings.Images.Content - see https://go.2sxc.org/settings
  • Or a dynamic object containing settings properties (this can also be a merged custom + standard settings)
  • A IResizeSettings object containing all settings created using ResizeSettings
noParamOrder NoParamOrder

see Convention: Named Parameters

tweak Func<ITweakMedia, ITweakMedia>

Tweak API to configure everything (new v18.03). This is recommended above using parameter names and all newer parameters will only be available on this. Note that tweak will be executed after applying other parameters.

factor object

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

width object

An optional, fixed width of the image

imgAlt string

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.

imgAltFallback string

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

imgClass string

Optional class attribute on the created img tag

imgAttributes object

Optional additional attributes - as anonymous object like new { style = "padding: 10px" } or Dictionary (new 16.07)

toolbar object

Provide a custom toolbar or false to not show a toolbar

recipe object

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

IResponsiveImage

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

Remarks

  • Added in 2sxc 13.03
  • toolbar added in v16.04
  • tweak added in 18.03

Picture(object, object, NoParamOrder, Func<ITweakMedia, ITweakMedia>, object, object, string, string, string, object, string, object, object, 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, NoParamOrder, Func<ITweakResize, ITweakResize>, object, object, object, object, string, string, string, object, string, object) and pass them in.

IResponsivePicture Picture(object link = null, object settings = null, NoParamOrder noParamOrder = default, Func<ITweakMedia, ITweakMedia> tweak = null, object factor = null, object width = null, string imgAlt = null, string imgAltFallback = null, string imgClass = null, object imgAttributes = null, string pictureClass = null, object pictureAttributes = null, object toolbar = null, object recipe = null)

Parameters

link object

What should be in this, can be:

  • a string url, in which case it would be used if url is not specified
  • a IField in which case it would be used if field is not specified
  • a IFile (new 16.03)
settings object
  • The name of a settings configuration, like "Content", "Screen", "Square", etc.
  • A standardized Image-Settings object like Settings.Images.Content - see https://go.2sxc.org/settings
  • Or a dynamic object containing settings properties (this can also be a merged custom + standard settings)
  • A IResizeSettings object containing all settings created using ResizeSettings
noParamOrder NoParamOrder

see Convention: Named Parameters

tweak Func<ITweakMedia, ITweakMedia>

Tweak API to configure everything (new v18.03). This is recommended above using parameter names and all newer parameters will only be available on this. Note that tweak will be executed after applying other parameters.

factor object

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

width object

An optional, fixed width of the image

imgAlt string

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

imgAltFallback string

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

imgClass string

Optional class attribute on the created img tag

imgAttributes object

Optional additional attributes - as anonymous object like new { style = "padding: 10px" } or Dictionary (new 16.07)

pictureClass string

Optional class attribute on the created picture tag

pictureAttributes object

Optional additional attributes - as anonymous object like new { style = "padding: 10px" } or Dictionary (new 16.07)

toolbar object

Provide a custom toolbar or false to not show a toolbar

recipe object

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

IResponsivePicture

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

Remarks

  • Added in v13.03
  • Extended in v16.03 to also support IFile
  • toolbar added in v16.04
  • imgAttributes, picClass and picAttributes added in 16.07
  • tweak added in 18.03

Recipe(string) 

Recipe Recipe(string variants)

Parameters

variants string

Returns

Recipe

Recipe(Recipe, NoParamOrder, string, int, string, IDictionary<string, object>, IEnumerable<Recipe>, bool?, bool?, string, string, string) 

Recipe Recipe(Recipe recipe, NoParamOrder noParamOrder = default, string name = null, int width = 0, string variants = null, IDictionary<string, object> attributes = null, IEnumerable<Recipe> recipes = null, bool? setWidth = null, bool? setHeight = null, string forTag = null, string forFactor = null, string forCss = null)

Parameters

recipe Recipe
noParamOrder NoParamOrder
name string
width int
variants string
attributes IDictionary<string, object>
recipes IEnumerable<Recipe>
setWidth bool?
setHeight bool?
forTag string
forFactor string
forCss string

Returns

Recipe

Settings(object, NoParamOrder, Func<ITweakResize, ITweakResize>, 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

IResizeSettings Settings(object settings = null, NoParamOrder noParamOrder = default, Func<ITweakResize, ITweakResize> tweak = null, 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

settings object
  • A standardized Image-Settings object like Settings.Images.Content used as a template - see https://go.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.
noParamOrder NoParamOrder

see Convention: Named Parameters

tweak Func<ITweakResize, ITweakResize>

Tweak API to configure everything (new v18.03). This is recommended above using parameter names and all newer parameters will only be available on this. Note that tweak will be executed after applying other parameters.

factor object

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

width object

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

height object

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

quality object

Optional quality parameter. Usually takes the default from the settings.

resizeMode string

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

scaleMode string

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

format string

Optional file format like jpg or png

aspectRatio object

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

parameters string
  • the parameters either as id=47&name=daniel (Dnn also supports /id/47/name/daniel)
  • it can also be an IParameters
recipe object

WIP - not ready yet

Returns

IResizeSettings

A settings object which has all the parameters as configured

Remarks

  • Added in v13.03
  • Tweak added in v18.03
Edit this page