Create From Template - Android

import android.net.Uri
import ly.img.engine.DesignBlockType
import ly.img.engine.Engine
import ly.img.engine.ExportOptions
import ly.img.engine.Font
import ly.img.engine.FontStyle
import ly.img.engine.FontWeight
import ly.img.engine.MimeType
import ly.img.engine.Typeface
import java.nio.ByteBuffer

data class FromTemplate(
    val pageCount: Int,
    val textBlockCount: Int,
    val customizedText: String?,
    val previewPngData: ByteBuffer,
)

suspend fun fromTemplate(engine: Engine): FromTemplate {
    val templateUri = Uri.parse(
        "https://cdn.img.ly/packages/imgly/cesdk-android/1.79.0/assets/ly.img.templates/templates/cesdk_business_card_1.scene",
    )
    val scene = engine.scene.load(sceneUri = templateUri, waitForResources = true)

    check(scene == engine.scene.get())

    val templateString = engine.scene.saveToString(scene = scene)
    engine.scene.load(scene = templateString, waitForResources = true)

    val replacementTemplateUri = Uri.parse(
        "https://cdn.img.ly/packages/imgly/cesdk-android/1.79.0/assets/ly.img.templates/templates/cesdk_business_card_1.scene",
    )
    engine.scene.applyTemplate(templateUri = replacementTemplateUri)

    val firstTextBlock = engine.block.findByType(DesignBlockType.Text).firstOrNull()
    if (firstTextBlock != null) {
        engine.block.replaceText(block = firstTextBlock, text = "Your Company")
    }

    val page = engine.block.findByType(DesignBlockType.Page).first()
    val exportTypeface = Typeface(
        name = "Fira Sans",
        fonts = listOf(
            Font(
                uri = Uri.parse("file:///android_asset/imgly-assets/ly.img.typeface/fonts/FiraSans/FiraSans-Regular.ttf"),
                subFamily = "Regular",
                weight = FontWeight.NORMAL,
                style = FontStyle.NORMAL,
            ),
        ),
    )
    val exportFont = exportTypeface.fonts.first()
    engine.block.findByType(DesignBlockType.Text).forEach { textBlock ->
        engine.block.setFont(block = textBlock, fontFileUri = exportFont.uri, typeface = exportTypeface)
    }
    engine.block.forceLoadResources(blocks = listOf(page))
    val pageWidth = engine.block.getWidth(page)
    val pageHeight = engine.block.getHeight(page)
    val previewPngData = engine.block.export(
        block = page,
        mimeType = MimeType.PNG,
        options = ExportOptions(
            targetWidth = 1200F,
            targetHeight = 1200F * pageHeight / pageWidth,
        ),
    )

    return FromTemplate(
        pageCount = engine.block.findByType(DesignBlockType.Page).size,
        textBlockCount = engine.block.findByType(DesignBlockType.Text).size,
        customizedText = firstTextBlock?.let { engine.block.getString(block = it, property = "text/text") },
        previewPngData = previewPngData,
    )
}

Load pre-designed templates to give users a professional starting point instead of a blank canvas.

Customized template preview

5 mins

estimated time

GitHub

Templates provide consistent layouts and styling that users can customize for their own needs. CE.SDK loads Android templates from remote or local scene URIs, from serialized strings, and applies template content to an existing scene while preserving its page dimensions.

Load a Template from URL#

The most common approach is loading a template from a .scene file URI. Pass the URI to engine.scene.load(sceneUri=_), and the engine replaces the current scene with the loaded template.

val templateUri = Uri.parse(
    "https://cdn.img.ly/packages/imgly/cesdk-android/1.79.0/assets/ly.img.templates/templates/cesdk_business_card_1.scene",
)
val scene = engine.scene.load(sceneUri = templateUri, waitForResources = true)

The scene file references assets by URI, so those assets must stay reachable. Use waitForResources=true when later code depends on the template’s resources being loaded before it continues.

Load a Template from String#

When a template is stored as serialized scene data, load it with engine.scene.load(scene=_). The string usually comes from a previous engine.scene.saveToString(scene=_) call and can be stored in your database or app storage.

val templateString = engine.scene.saveToString(scene = scene)
engine.scene.load(scene = templateString, waitForResources = true)

This path is useful for restoring saved user designs or serving templates through your backend.

Apply a Template to an Existing Scene#

To populate an existing scene with template content while keeping its current page dimensions, use engine.scene.applyTemplate(templateUri=_). Android also exposes engine.scene.applyTemplate(template=_) when the template is already available as a serialized string.

val replacementTemplateUri = Uri.parse(
    "https://cdn.img.ly/packages/imgly/cesdk-android/1.79.0/assets/ly.img.templates/templates/cesdk_business_card_1.scene",
)
engine.scene.applyTemplate(templateUri = replacementTemplateUri)

Use this when the canvas size is already set for a fixed output format and you want to drop in template content without changing those dimensions.

Modify Template Content#

After loading or applying a template, customize its blocks with the block APIs. Find the elements you want to change and update them.

val firstTextBlock = engine.block.findByType(DesignBlockType.Text).firstOrNull()
if (firstTextBlock != null) {
    engine.block.replaceText(block = firstTextBlock, text = "Your Company")
}

Common modifications include:

Replacing text: engine.block.replaceText(block=_, text=_) swaps text content.
Swapping images: set fill/image/imageFileURI on a graphic block’s image fill with engine.block.setUri(block=_, property=_, value=_) — see Image Fills.
Adjusting colors: set fill/color/value on a block’s fill — see Color Fills.

Troubleshooting#

Template fails to load

Verify the URI is reachable and returns a valid .scene file.
Ensure the template format is compatible with your CE.SDK version.
For remote URLs, confirm your app has network access and the server allows Android clients to download the file.

Assets not displaying after load

Scene files store asset references as URIs; ensure those URIs remain reachable.
Use an archive (.zip) for a self-contained template with bundled assets, and load that archive with engine.scene.loadArchive(archiveUri=_).
Configure a URI resolver if assets are hosted on a different server.

API Reference#

Methods#

Method	Description
`engine.scene.load(sceneUri=_, waitForResources=_)`	Load a scene from a remote or local URI.
`engine.scene.load(scene=_, waitForResources=_)`	Load a scene from a serialized string.
`engine.scene.applyTemplate(templateUri=_)`	Apply a `.scene` template URI to the current scene.
`engine.scene.applyTemplate(template=_)`	Apply a serialized string template to the current scene.
`engine.scene.loadArchive(archiveUri=_)`	Load a self-contained scene archive.
`engine.scene.saveToString(scene=_)`	Serialize the current scene to a string.
`engine.block.findByType(type=_)`	Find all blocks of a given type.
`engine.block.replaceText(block=_, text=_)`	Replace text content in a text block.
`engine.block.setString(block=_, property=_, value=_)`	Set a string property.
`engine.block.setUri(block=_, property=_, value=_)`	Set a URI property, such as an image fill URI.
`engine.block.setColor(block=_, property=_, value=_)`	Set a color property, such as a fill color.

Next Steps#

Load a Scene — Load saved scenes from various sources
Save a Design — Save your customized template