Custom image loaders

Valdi supports loading and displaying https and res images by default with the <image> tag. If you need additional formats or custom image loading behavior, you can build a native custom image loader.

You will need a custom loader for each platform where you intend to load images.

Before you create your custom loader, take a look at the existing custom loaders to determine if your functionality has already been implemented: See iOS and Android.

How custom loaders work

The src attribute specifies the target of an <image>. This is often thought of as a URL but it is just a string. Anything that can be encoded as a string can be used as a src: a URL, a b64 encoded blob of something, a db key.

Custom loaders specify supportedURLSchemes these are not strictly URL schemes but again just strings. If the prefix of the specified src matches a custom loader's supportedURLSchemes then Valdi will use that loader to load that image.

supportedURLSchemes => returns ['my-image-loader']

Matches: my-image-loader://url.shaped.thing my-image-loader://bG9sd3V0

supportedURLSchemes should be unique to your loader; if there are conflicting strings, the first one registered will be used.

Your custom loader should live in a folder that you own, not Valdi's codebase.

iOS

On iOS, the loader must conform to the SCValdiImageLoader protocol and implement the following methods (including at least one of the optional methods):

objc


/**
 Returns the URL schemes that this VideoLoader knows how to load.
 */
- (NSArray<NSString*>*)supportedURLSchemes;

/**
 Returns the request payload object which will be provided to the loadVideoWithRequestPayload:
 method for the given imageURL. The payload can be any Objective-C object. The payload might
 be cached internally by the framework.
 */
- (id)requestPayloadWithURL:(NSURL*)imageURL error:(NSError**)error;

@optional

/**
 Load the image with the given request payload and call the completion when done.
 This method should only be implemented if this SCValdiImageLoader instance supports loading
 URLs into SCValdiImage instances.
 */
- (id<SCValdiCancelable>)loadImageWithRequestPayload:(id)requestPayload
                                             parameters:(SCValdiAssetRequestParameters)parameters
                                             completion:(SCValdiImageLoaderCompletion)completion;

/**
 Load the bytes with the given request payload and call the completion when done.
 This method should only be implemented if this SCValdiImageLoader instance supports loading
 URLs into raw bytes.
 */
- (id<SCValdiCancelable>)loadBytesWithRequestPayload:(id)requestPayload
                                             completion:(SCValdiImageLoaderBytesCompletion)completion;

[!WARNING] The returned implementation for SCValdiCancelable must be thread-safe as cancel() can be called on any thread.

Android

The loader must conform to ValdiImageLoader and implement the following methods:

kotlin


    /**
    Returns the URL schemes supported by this ImageLoader
     */
    fun getSupportedURLSchemes(): List<String>

    /**
     * Returns a RequestPayload that will be provided to the load function of the implementation.
     * The request payload might be cached by the runtime to avoid processing
     * it again. This method can throw a ValdiException if Uri cannot be parsed.
     */
    @Throws(ValdiException::class)
    fun getRequestPayload(url: Uri): Any

    /**
     * Returns the output types that this ValdiAssetLoader supports.
     */
    fun getSupportedOutputTypes(): Int

    /**
    Load the bitmap for the given URL and call the completion when done.
     */
    fun loadImage(requestPayload: Any,
                  options: ValdiImageLoadOptions,
                  completion: ValdiImageLoadCompletion): Disposable?

The getSupportedOutputTypes method should return a list of ValdiAssetLoadOutputTypes.