Add support for asset renditions

Suzii commented 2 years ago

Motivation

New Kontent feature - Asset renditions, will be released soon (beginning of December with) and it will be available through DeliveryAPI. We should have them covered in SDKs as well.

Proposed solution

When the asset element is retrieved from Deliver, the referenced assets can now contain user-defined renditions and it is easy for the developer to apply the rendition query string to the URL of the original asset so that the customized image can be rendered in the UI.

Additional context

This is the updated Deliver contract for referenced assets of asset element:

New renditions property is present and it is a dictionary with a single key (for now) equal to the "default" preset codename. Presets are not a real entity for now but are part of the long-term vision of asset renditions.
- the property will only be present for image-like objects (those which have both width & height properties set by the system)
- when no renditions are defined for the linked asset, the empty object/dictionary is returned in the rendition property
- if the asset is of non-image type (e.g. .pdf) the property won't be present (same as width & height in that case)
Ideally, to ease the adoption for the users, it would be nice to introduce support for "defaultPreset" which would automatically apply the query parameters of the rendition in preset specified by the global config.
- Feel free to get inspired by the already implemented support in JS or .NET SDKs

Note, that this only applies to assets in the asset element. There is no support for renditions in inline RTE images, yet.

{
"name": "name-of-the-uploaded-file.jpg",
"type": "image/jpeg",
"size": 90895,
"description": "Description of what the asset represents.",
"url": "https://assets-us-01.kc-usercontent.com/975bf280-fd91-488c-994c-2f04416e5ee3/3e76909f-599f-4742-b472-77fd4b510e92/sources.jpg",
"width": 1000,
"height": 666,
"renditions": {
  "default": {
    {
      "rendition_id": "d44a2887-74cc-4ab0-8376-ae96f3f534e5",
      "preset_id": "a6d98cd5-8b2c-4e50-99c9-15192bce2490",
      "width": 200,
      "height": 150,
      "query", "w=200&h=150&fit=clip&rect=7,23,300,200"
  }
}
}

SmootherSpike commented 2 years ago

Projects which are using the java-sdk are heavily waiting for this change to be included in the sdk. Would be great if such kind of features are immediately pushed to all of the sdks, regardless of the language, js/c#, java etc. Any plan when this will be available?

Simply007 commented 2 years ago

Projects which are using the java-sdk are heavily waiting for this change to be included in the SDK. Would be great if such kinds of features are immediately pushed to all of the SDKs, regardless of the language, js/c#, java etc. Any plan when this will be available?

Hello @SmootherSpike, thanks for reaching out. We have been currently heavily working to include new API functionality to .NET and Javascript delivery and management SDKs since .NET and JS are our primary stacks right now.

I can take a look at this one.

Do you have any thoughts on how you would use the rendition? I am asking specifically about the query parameter - do you have any plans of parsing its value, or you are fine with just a string representation?

connyduck commented 1 year ago

When will this be published? We would really like to use this feature, but can't until we have sdk support. @Simply007

Simply007 commented 1 year ago

When will this be published? We would really like to use this feature, but can't until we have sdk support. @Simply007

Hello @connyduck - it was already released in beta 4.5.0-SNAPSHOT - and waiting for feedback: https://github.com/kontent-ai/java-packages/pull/137#issuecomment-1102390518

Since there was no feedback for it, so we decided to wait for the demand.

It is currently in the pre-migrated version 4.X.X. Could you test it out like that, if the implementation fulfills the requirements?

ExternalWeb commented 9 months ago

Hello I'm trying to get updated code with renditions changes, but the package on Maven and nexus does not contain the changes: https://s01.oss.sonatype.org/service/local/repositories/releases/content/ai/kontent/delivery-sdk/5.0.0/delivery-sdk-5.0.0-sources.jar https://s01.oss.sonatype.org/#nexus-search;quick~kontent

I have added to maven, but Asset.class does not contain this changes

<dependency>
            <groupId>ai.kontent</groupId>
            <artifactId>delivery-sdk</artifactId>
            <version>5.0.0</version>
 </dependency>

can you point me in the right direction @Simply007 ?

Simply007 commented 9 months ago

Hello, it was released in version 4.5.0-SNAPSHOT only - which was before splitting out to the standalone company (Kentico -> Kontent.ai) - so it is under a different group ID.

Plus it is not in the release server maven - it is on the snapshot server under the old name: https://oss.sonatype.org/content/repositories/snapshots/com/github/kentico/kontent-delivery/4.5.0-SNAPSHOT/

I am not with Kontent.ai anymore - pinging @IvanKiral as a new code owner

If PR #137 is rebased to the latest code, it is possible to release a new Snapshot under a new naming to push it to the latest snapshot and release version.

https://github.com/kontent-ai/java-packages/blob/master/docs/Release-process.md#version-specification

IvanKiral commented 9 months ago

Hello,

@Simply007 Thank you for replying and tagging me :)

@ExternalWeb - thanks for the opening conversation in this issue :) As a new code owner, I look at the code. However, have you tried the published snapshot version 4.5.0? Just to be sure, if it is working as you would expect. Otherwise, could you try it and give us your opinion? The feedback would really help me to release the code that is useful. Thanks again :)

ExternalWeb commented 9 months ago

Hello,

@Simply007 Thank you for replying and tagging me :)

@ExternalWeb - thanks for the opening conversation in this issue :) As a new code owner, I look at the code. However, have you tried the published snapshot version 4.5.0? Just to be sure, if it is working as you would expect. Otherwise, could you try it and give us your opinion? The feedback would really help me to release the code that is useful. Thanks again :)

Thank you for your answer, but switching to a older? version 4.5.0 is not great for us, as we would have to change all the namespaces in the code and retest. For getting dependencies we are only getting them via maven. Can these changes be rebased as Simply007 said and released in release maven server?

IvanKiral commented 9 months ago

@ExternalWeb, let's do that! :)

I have run through changes in PR https://github.com/kontent-ai/java-packages/pull/137 and rebased the changes to the main branch. However, I released right now only the 5.0.5-SNAPSHOT version where are is the support for asset renditions now. It seems to be working, however, I would still like to have another opinion whether it is working properly. If you try it, please let me know if it is working as you expected :)

Thank you

ExternalWeb commented 9 months ago

Ahoj Ivane,

Thank you for work. I've tried in my project and because i do not have s01.oss.sonatype.or as repository setup and everything is going through https://mvnrepository.com/artifact/ai.kontent/delivery-sdk I cannot download the snapshot. This is configuration issue, but maybe you want to also upload it there as many people are using Maven Central for they java dependencies.

IvanKiral commented 9 months ago

Ahoj, @ExternalWeb :)

Okay, as it was a small PR, I have tested the snapshot and released the version to the maven https://repo1.maven.org/maven2/ai/kontent/delivery-sdk/5.0.5/. I believe it will be propagated to the mvnrepository soon. If there is any problem, please let us know. However, I hope everything is ok now :)

ExternalWeb commented 8 months ago

Ahoj Ivane,

Maven update worked, updated to 5.0.5 (delivery-sdk, delivery-sdk-generators) and deployed on our test server. Renditions work as expected, data are being mapped to new rendition property in Asset class and our project is buildable and our tests completed successfuly.

Thank you for your support. Přeji klidný zbytek roku ;)

kontent-ai / java-packages