Getting Started with Responsive Images

Getting Started with Responsive Images

Probably the most straightforward way to use Responsive Images is to request an optimized image from the server that matches the size of the image container. This article provides step-by-step instructions as to how to do this, including how to upload an image to Files.

You can also apply the information in this article to any native iOS app where you want to use the Responsive Images service. Simply skip to Connect Your App to the Responsive Images Service.

Steps at a glance:

  1. Upload an Image File
  2. (Optional) Configure the Allowed Image Source Domains
  3. Obtain the URI of the Image
  4. Connect Your App to the Responsive Images Service
  5. Prepare the Resize Parameters
  6. Request a Resized Image
  7. Display the Resized Image

Prerequisites

  • A Telerik Platform account.
  • The App ID for your Telerik Platform app. You can access it from Settings.
  • The Data service enabled.

Upload an Image File

You can optimize any publicly available image file using its HTTP(S) URL. However, if you want to store your images using Telerik Platform, you can take these steps to upload an image:

Image files with a larger size and resolution take greater advantage of Responsive Images.

  1. Open you app.
  2. Click Data > Files in the left-side navigation pane.
  3. Click the Upload files button.
  4. Drag and drop your image file to the right-side edit pane or browse for the file location.
  5. Click Save to upload the file.

"Uploading an image file"

To upload an image programmatically, use any of these approaches:

  • Using the iOS SDK: Uploading Files
  • Using the Telerik Kendo UI HTML5 & jQuery Upload Component: Upload
  • Using the Telerik UI for ASP.NET AJAX Cloud Upload Control: RadCloudUpload

(Optional) Configure the Allowed Image Source Domains

Skip this step if you store your images in Telerik Platform Files.

If you want to optimize image files from an outside source, you need to whitelist its domain name in Telerik Platform. Not allowing other sources makes your Responsive Images endpoint more secure.

  1. Open you app.
  2. Click Data > Responsive Images in the left-side navigation pane.
  3. Click the Add Domain button.
  4. In the Name text box, enter the name of the domain that you want to trust and click Save. Use the following format:

    (subdomain.)domainname.tld

    For example:

    telerik.com or images.telerik.com

    Do not enter protocol prefixes, slashes, or port numbers. Wildcards are not supported.

Note that it takes several minutes for the setting to take effect. During that time you get an error if you attempt to optimize images from the recently added domain.

"Adding an allowed domain"

Obtain the URI of the Image

You need the image URI before you can pass it to Telerik Platform for optimization. Depending on where the image is stored, use one of the following approaches to get its URI:

  • If you store your image outside of Telerik Platform, use the specific steps for the storage service you are using.
  • If you store your image in Telerik Platform, take these steps to get its URI:

    1. Open you app.
    2. Click Data > Files in the left-side navigation pane.
    3. Select the file entry in the file browser.
    4. In the right-hand pane, right-click the hyperlink under the file preview thumbnail and select to copy the URL.

To get the URL of an image programmatically, get the file using the following method. In the request, set the X-Everlive-Fields header value to {"Uri" : "1"} to only return the Uri field instead of the entire object:

Connect Your App to the Responsive Images Service

Add the Responsive Images server's address as a constant of your app's view controller. You will refer to it whenever you need to request a mobile-optimized image. Then declare the App ID of your Telerik Platform app.

static NSString * const AppId = @"your-app-id";
static NSString * const imageServerBaseUrl = @"https://bs1.cdn.telerik.com/image/v1/";
let AppId:String = "your-app-id";
let imageServerBaseUrl = https://bs1.cdn.telerik.com/image/v1/"

Prepare the Resize Parameters

You need to know the properties of the target image container to determine the resized image's dimensions and fill mode (how to handle the image in case the container has a different aspect ratio).

The following code reads the container's width and height and sets the fill mode to contain, which keeps the image information but may not fill the entire container. You can also set the fill to cover which fills the entire container but at the expense of cropping the picture.

CGRect imageViewBounds = [[self imageView] bounds];
CGSize size = imageViewBounds.size;

int width = (int)size.width;
int height = (int)size.height;   
int pixelDensity = 2; // will double the pixel density in the returned image
NSString *fillMode = @"contain";

NSMutableArray *resizedParametersArray = [[NSMutableArray alloc]init];
[resizedParametersArray addObject:([NSString stringWithFormat: @"w:%d", width])];
[resizedParametersArray addObject:([NSString stringWithFormat: @"h:%d", height])];
[resizedParametersArray addObject:([NSString stringWithFormat: @"fill:%@", fillMode])];
[resizedParametersArray addObject:([NSString stringWithFormat: @"pd:%d", pixelDensity])];

NSString *joiner = @",";
NSString *joinedResizeParameters = [resizedParametersArray componentsJoinedByString:joiner];

// The resize parameters should be in the format "resize=w:400,h:300,fill:contain,pd:2"
NSString *resizeOperator = @"resize=";
NSString *resizeParameters = [resizeOperator stringByAppendingString:joinedResizeParameters];
var imageBounds: CGRect = self.imageView.bounds;
var size:CGSize = imageBounds.size;

var width:Int = Int(size.width)
var height:Int = Int(size.height)
var fillMode = "contain";
var pixelDensity = 2; // will double the pixel density in the returned image

var resizedParametersArray = [String]()
resizedParametersArray.append("w:" + width.description)
resizedParametersArray.append("h:" + height.description)
resizedParametersArray.append("fill:" + fillMode)
resizedParametersArray.append("pd:" + pixelDensity.description)

// The resize parameters should be in the format "resize=w:400,h:300,fill:contain,pd:2"
var joiner = ",";
var resizeParameters:String = "resize=" + joiner.join(resizedParametersArray);

Request a Resized Image

After assembling the parameters string, you can contact the Responsive Images service to request the resized image's URI. In the next example, the original image location (originalImageUri) is explicitly set, but in the real world you would use the Backend Services iOS SDK to query Telerik Platform and find the image URL or use some other means of acquiring it if you are reading the image from an external source.

NSString *imageServerUrl = [NSString stringWithFormat:@"%@%@%@", imageServerBaseUrl, AppId, @"/"];

NSString *originalImageUri = @"https://bs1.cdn.telerik.com/v1/TopkyrLaF3O6CGiC/c473ea72-f7c0-11e4-87db-713680c9d2da"; //Or use an external URI

NSString *resizedFileUri =  [NSString stringWithFormat:@"%@%@%@%@", imageServerUrl, resizeParameters, @"/", originalImageUri];
let imageServerUrl:String = imageServerBaseUrl + AppId + "/";

var originalImageUri:String = "https://bs1.cdn.telerik.com/v1/TopkyrLaF3O6CGiC/c473ea72-f7c0-11e4-87db-713680c9d2da"; //Or use an external URI

var resizedFileUri:String =  imageServerUrl + resizeParameters + "/" + originalImageUri;

Display the Resized Image

Now that you have the resized image's URI, you are ready to display it. For instance:

NSURL *url = [NSURL URLWithString:resizedFileUri];
NSData *data = [NSData dataWithContentsOfURL:url];
UIImage* img = [[UIImage alloc] initWithData:data];

self.imageView.contentMode = UIViewContentModeScaleAspectFill;
self.imageView.image = img;
let url = NSURL(string: resizedFileUri)
let data = NSData(contentsOfURL: url!)
self.imageView.contentMode = .ScaleAspectFit
self.imageView.image = UIImage(data: data!)

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.