Assets Module

The Assets Module allows authors to work with assets like images, documents, videos and more. It is already included in the Confinity Core.

Configuration

The Asset Module can be configured using the options pattern. The corresponding options class is Confinity.Assets.AssetOptions and it will automatically try to read your configuration from your appsettings.json from the ConfinityAssets section.

Helpers

IFolderHelper

Useful, if folders needed to be created.

Example usage: var branchesFolder = await _folderHelper.CreateOrGetFolderFromPath(new AssetPath("Assets/Geschäftstellen"));

IAssetHelper

Useful, if assets needed to be stored without cms author interaction or within the host application. This helper does not call _db.SaveChangesAsync()! Call it as soon as possible to free resources.

Example usage:

var imageUri = new Uri("https://confinity.io/logo.png");
string filename = UriUtils.GenerateSlug(Path.GetFileName(imageUri.AbsolutePath));
var httpClient = new HttpClient();
await using var stream = await httpClient.GetStreamAsync(imageUri);

await _assetHelper.SaveRasterImage(filename, stream, branchesFolder);
await _db.SaveChangesAsync();

Endpoints

Two endpoints can serve the assets uploaded to Confinity. They distinguish slightly in the offered features and that one can only be accessed by authorized Confinity users. All assets are stored in the cache folder (AssetOptions.CacheDirectory) for quick access, including resized images.

Public asset endpoints

The public asset endpoint is reachable at /.dam (changeable in at ConifnityOptions.AssetPath). To obtain an asset, call /.dam/[id]/[filename], e.g. /.dam/a33f6060-0332-41c5-904c-c0f1d5376737/How-to-deep-fry-toothpaste.pdf. The filename must match the filename in Confinity.

Resizing an image by with or height

To obtain a resized image with a defined width or height, call /.dam/[id]/[dimension]/[size]/[filename], e.g. /.dam/a7209d37-af1d-47f1-bd15-0cfd5d2388f6/w/1100/Bored-Beach-Boy.webp. The aspect ration will stay the same.

Be aware of:

• The filename must match the filename in Confinity
• Animated images and SVG files will not be resized
• the dimensions are w (width) and h (height)
• if the picture is smaller then the requested size, it will not change
• the requested size must be configured in AssetOptions.AllowedImageSizes
  • if the requested size is not configured, the next bigger size will be used

Resizing an image by with and height

To obtain a resized image with a defined width and height, call /.dam/[id]/x/[width]/[height]/[filename], e.g. /.dam/f676fda9-1ae5-4f4b-bd85-68a2dc784414/x/1100//750/Red-running-rabbit.jpg. The image will be resized with the defined focus point taken into account.

There are some restrictions to be aware of:

• The filename must match the filename in Confinity
• Animated images and SVG files will not be resized
• if the picture is smaller then the requested size, it will be resized to the biggest possible size with the the given aspect ratio.
• the requested size must be configured in AssetOptions.AllowedExactImageSizes

Convert the image file format

All asset endpoints support the conversion of image file formats, e.g. JPG to WEBP. To do so, just call the endpoint with the desired extension in the filename, e.g. /.dam/f676fda9-1ae5-4f4b-bd85-68a2dc784414/w/1100/Red-running-rabbit.webp.

Internal asset endpoints

The internal asset endpoint is reachable at /.confinity/api/asset. It differs from the public on in the following aspects:

• Only available for authorized Confinity users
• Every size is allowed for image resizing
• The general endpoint (without resizing) can be called without a filename, e.g. /.confinity/api/asset/05a1d2d0-485b-497a-b59b-182fdfcd3ae4