AssetLibrary
AssetLibrary
Assets are the media files uploaded to a stack, such as images, videos, PDFs and audio files. Use the AssetLibrary class to
- list the assets published in an environment
- filter that list by field value and sort it by a field
- add fallback-locale content, metadata, the branch or relative URLs to each asset in the response
[stack assetLibrary] (Swift stack.assetLibrary()) takes no arguments and returns a new AssetLibrary on each call. To read one asset by its UID, call [stack assetWithUID:@"ASSET_UID"], which returns an Asset.
| Name | Type | Description |
|---|---|---|
| cachePolicy | CachePolicy | CachePolicy that fetchAll: uses. Known issue: only NETWORK_ONLY and NETWORK_ELSE_CACHE behave as named. CACHE_ONLY, CACHE_ELSE_NETWORK and CACHE_THEN_NETWORK never read the cache. Use NETWORK_ELSE_CACHE for an offline fallback. |
addHeadersWithDictionary:
addHeadersWithDictionary: sets several request headers that fetchAll: sends with the asset list request.
| Name | Type | Description |
|---|---|---|
| headers (required) | NSDictionary<NSString *, NSString *> * | Header names mapped to the values to send. |
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation of the header names or values.
- A nil or empty headers dictionary makes the call do nothing.
- An invalid value surfaces in the error argument of the completion block of the next fetchAll: call.
Behavior
- Client-side only. addHeadersWithDictionary: adds each pair to the headers stored on the asset library and makes no request. The fetchAll: call that follows sends them.
- A name that the asset library already holds takes the new value. Headers not in the dictionary stay as they are.
- fetchAll: sends the headers of the Stack first and the headers of the asset library after them.
- A header you set here therefore replaces a Stack header of the same name, for this object only.
- When you set the branch property of Config, the SDK sends it as the branch header and replaces a branch header you set here.
- Get all assets accepts the branch header to read assets from a specific branch.
Example
Basic usage: list the assets of a branch (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary addHeadersWithDictionary:@{@"branch": @"BRANCH_UID"}];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu assets", (unsigned long)result.count);
}];Basic usage: list the assets of a branch (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.addHeaders(with: ["branch": "BRANCH_UID"])
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.count ?? 0) assets")
}fetchAll:
fetchAll: lists the published assets of the environment that match the settings stored on the asset library.
| Name | Type | Description |
|---|---|---|
| completionBlock (required) | void (^)(ResponseType, NSArray<Asset *> *, NSError *) | Runs when the request ends. Receives the ResponseType, the assets or nil, and an NSError or nil. |
Returns: void. Nothing. The completion block receives the result.
Validation
- There is no client-side validation.
- When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.
- On an error, result is nil.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- fetchAll: sends one GET request to /v3/assets, the Get all assets request. It carries the environment of the Stack and every setting stored on the asset library.
- On success, result holds one Asset per item in the assets array of the response, and the SDK fills the properties of each one. Each asset has its uid set, so you can call fetch: on it.
- result is nil when the response has no assets array, for example after objectsCount.
- One call returns one page. The API returns the first 100 assets when the request sets no limit. See Pagination.
- The cachePolicy property of the asset library decides whether fetchAll: reads the cache. The default is NETWORK_ONLY.
Limitations
- Does not request further pages. Read every published asset through the syncPublishType:completion: method of Stack instead.
- Does not return the count that includeCount asks for. See the Known issue on that method.
Example
Basic usage: list the assets of an environment (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@ %@", asset.fileName, asset.url);
}
}];Basic usage: list the assets of an environment (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.fileName, asset.url)
}
}Offline fallback: read the list from the cache when the network fails (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
assetLibrary.cachePolicy = NETWORK_ELSE_CACHE;
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) { return; }
NSLog(@"%lu assets from %@", (unsigned long)result.count, type == CACHE ? @"cache" : @"network");
}];Offline fallback: read the list from the cache when the network fails (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.cachePolicy = .NETWORK_ELSE_CACHE
assetLibrary.fetchAll { (type, result, error) in
guard error == nil else { return }
print("\(result?.count ?? 0) assets from \(type == .CACHE ? "cache" : "network")")
}includeBranch
includeBranch asks the API to add the _branch key, which names the branch that holds each asset, to the response.
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. includeBranch takes no input.
- Errors that do occur surface in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeBranch stores include_branch=true on the asset library and makes no request. The fetchAll: call that follows sends it.
- The API adds the _branch key, which holds the unique ID of the branch. See include_branch in Get all assets.
- includeBranch does not choose the branch. The branch property of Config sets the branch header that selects it.
- Calling includeBranch twice changes nothing, because both calls write the same value under the same key.
Example
Basic usage: list assets with their branch (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary includeBranch];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@ %@", asset.fileName, asset.properties);
}
}];Basic usage: list assets with their branch (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.includeBranch()
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.fileName, asset.properties)
}
}includeCount
includeCount asks the API to return the total number of matching assets along with the assets.
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. includeCount takes no input.
- Errors that do occur surface in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeCount stores include_count=true on the asset library and makes no request. The fetchAll: call that follows sends it.
- The API adds the total count to the response. See Count, which applies to assets as well as entries.
- fetchAll: still returns the assets in result.
- Calling includeCount twice changes nothing, because both calls write the same value under the same key.
Example
Basic usage: count the assets on the returned page (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary includeCount];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu assets on this page", (unsigned long)result.count);
}];Basic usage: count the assets on the returned page (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.includeCount()
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.count ?? 0) assets on this page")
}includeFallback
includeFallback asks the API to return assets from the fallback locale when the requested locale has no published version.
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. includeFallback takes no input.
- Errors that do occur surface in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeFallback stores include_fallback=true on the asset library and makes no request. The fetchAll: call that follows sends it.
- The API then includes the published asset details from the fallback locale when the requested locale has none. See include_fallback in Get all assets.
- Set the requested locale with the locale: method.
- Calling includeFallback twice changes nothing, because both calls write the same value under the same key.
Example
Basic usage: list French assets with fallback content (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary locale:@"fr-fr"];
[assetLibrary includeFallback];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@ %@", asset.fileName, asset.url);
}
}];Basic usage: list French assets with fallback content (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.locale("fr-fr")
assetLibrary.includeFallback()
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.fileName, asset.url)
}
}includeMetadata
includeMetadata asks the API to add the metadata of each asset to the response.
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. includeMetadata takes no input.
- Errors that do occur surface in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeMetadata stores include_metadata=true on the asset library and makes no request. The fetchAll: call that follows sends it.
- The API returns the metadata of each asset under the _metadata key, with one entry per extension UID. See include_metadata in Get all assets.
- No typed property holds the metadata. fetchAll: copies every key of each asset object into the properties dictionary of that asset, so read the metadata there.
- Calling includeMetadata twice changes nothing, because both calls write the same value under the same key.
Example
Basic usage: list assets with their metadata (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary includeMetadata];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@ %@", asset.fileName, asset.properties);
}
}];Basic usage: list assets with their metadata (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.includeMetadata()
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.fileName, asset.properties)
}
}includeRelativeUrls
includeRelativeUrls asks the API to return a relative URL for each asset instead of a full URL.
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. includeRelativeUrls takes no input.
- Errors that do occur surface in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeRelativeUrls stores relative_urls=true on the asset library and makes no request. The fetchAll: call that follows sends it.
- The url property of each returned asset holds the value the API returns under url.
- Asset has no matching method. To request a relative URL for one asset, pass relative_urls through the addParamKey:andValue: method of Asset.
- Calling includeRelativeUrls twice changes nothing, because both calls write the same value under the same key.
Example
Basic usage: list assets with relative URLs (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary includeRelativeUrls];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@", asset.url);
}
}];Basic usage: list assets with relative URLs (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.includeRelativeUrls()
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.url)
}
}locale:
locale: sets the locale whose published assets fetchAll: lists.
| Name | Type | Description |
|---|---|---|
| locale (required) | NSString * | Locale code to read, such as fr-fr. |
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. An unknown locale code reaches the API unchanged.
- A nil locale raises NSInvalidArgumentException, because the SDK stores it in a dictionary that cannot hold nil.
- An invalid value surfaces in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. locale: stores the code in the locale query parameter and makes no request. The fetchAll: call that follows sends it.
- Calling locale: twice replaces the first code, because both calls write the same key.
- Pair it with the includeFallback method to receive fallback-locale assets when the requested locale has no published version.
- The parameter takes a locale code string, not a Language enum value.
Example
Basic usage: list the French assets (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary locale:@"fr-fr"];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@ %@", asset.fileName, asset.url);
}
}];Basic usage: list the French assets (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.locale("fr-fr")
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.fileName, asset.url)
}
}objectsCount
objectsCount asks the API to return only the number of matching assets, without the assets.
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. objectsCount takes no input.
- Errors that do occur surface in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. objectsCount stores count=true on the asset library and makes no request. The fetchAll: call that follows sends it.
- The API then returns only the count. See count in Count, which applies to assets as well as entries.
- Calling objectsCount twice changes nothing, because both calls write the same value under the same key.
Example
Basic usage: the result is nil after objectsCount (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary objectsCount];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
// result is nil because the response holds only the count
NSLog(@"result: %@", result);
}];Basic usage: the result is nil after objectsCount (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.objectsCount()
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
// result is nil because the response holds only the count
print("result: \(String(describing: result))")
}removeHeaderForKey:
removeHeaderForKey: removes a request header that you set on the asset library.
| Name | Type | Description |
|---|---|---|
| headerKey (required) | NSString * | Name of the header to remove. |
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation.
- A name that the asset library does not hold, or a nil name, makes the call do nothing.
Behavior
- Client-side only. removeHeaderForKey: changes only the headers stored on the asset library and makes no request.
- It removes only headers that you set through the setHeader:forKey: or addHeadersWithDictionary: method. A Stack header of the same name still goes with the request. To stop sending a Stack header, call the removeHeaderForKey: method of Stack.
Example
Basic usage: remove a header before the next request (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary setHeader:@"BRANCH_UID" forKey:@"branch"];
[assetLibrary removeHeaderForKey:@"branch"];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu assets", (unsigned long)result.count);
}];Basic usage: remove a header before the next request (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.setHeader("BRANCH_UID", forKey: "branch")
assetLibrary.removeHeader(forKey: "branch")
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.count ?? 0) assets")
}setHeader:forKey:
setHeader:forKey: sets one request header that fetchAll: sends with the asset list request.
| Name | Type | Description |
|---|---|---|
| headerValue (required) | NSString * | Header value to send. |
| headerKey (required) | NSString * | Header name, such as branch. |
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation of the header name or value.
- A nil headerValue or headerKey raises NSInvalidArgumentException, because the SDK stores the pair in a dictionary that cannot hold nil.
- An invalid value surfaces in the error argument of the completion block of the next fetchAll: call.
Behavior
- Client-side only. setHeader:forKey: stores the header on the asset library and makes no request. The fetchAll: call that follows sends it.
- A second call with the same headerKey replaces the earlier value.
- fetchAll: sends the headers of the Stack first and the headers of the asset library after them.
- A header you set here therefore replaces a Stack header of the same name, for this object only.
- When you set the branch property of Config, the SDK sends it as the branch header and replaces a branch header you set here.
- Get all assets accepts the branch header to read assets from a specific branch.
Example
Basic usage: list the assets of a branch (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary setHeader:@"BRANCH_UID" forKey:@"branch"];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu assets", (unsigned long)result.count);
}];Basic usage: list the assets of a branch (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.setHeader("BRANCH_UID", forKey: "branch")
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.count ?? 0) assets")
}sortWithKey:orderBy:
sortWithKey:orderBy: sorts the listed assets by the value of one field, in ascending or descending order.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the field to sort by, such as created_at. |
| order (required) | OrderBy | Sort direction, an OrderBy value. |
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- There is no client-side validation. An unknown field UID reaches the API unchanged.
- An order value outside the OrderBy enum makes the call do nothing.
- An invalid value surfaces in the error argument of the completion block of the next fetchAll: call.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. sortWithKey:orderBy: makes no request. The fetchAll: call that follows sends the sort.
- OrderByAscending stores the field UID in the asc query parameter. OrderByDescending stores it in the desc query parameter. See Order by asc and Order by desc, which apply to assets as well as entries.
- A second call with the same order replaces the earlier field. A second call with the other order adds a second parameter, so the request then carries both asc and desc.
Example
Basic usage: list the oldest assets first (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary sortWithKey:@"created_at" orderBy:OrderByAscending];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@ %@", asset.createdAt, asset.fileName);
}
}];Basic usage: list the oldest assets first (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.sort(withKey: "created_at", orderBy: .ascending)
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.properties["created_at"] ?? "", asset.fileName)
}
}List the most recently updated assets first (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary sortWithKey:@"updated_at" orderBy:OrderByDescending];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) { return; }
NSLog(@"Latest: %@", result.firstObject.fileName);
}];List the most recently updated assets first (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.sort(withKey: "updated_at", orderBy: .descending)
assetLibrary.fetchAll { (type, result, error) in
guard error == nil else { return }
print("Latest: \(result?.first?.fileName ?? "")")
}where:equalTo:
where:equalTo: keeps only the assets whose field holds the given value.
| Name | Type | Description |
|---|---|---|
| field (required) | NSString * | UID of the asset field to match, such as filename. |
| value (required) | NSObject * | Value the field must equal, such as a string or number. |
Returns: void. Nothing. The asset library keeps the setting for its next request.
Validation
- An empty field or a nil value makes the call do nothing except log Field or value cannot be empty to the console. Nothing raises, so the next fetchAll: lists assets without the condition. Pass a non-empty field UID and a non-nil value.
- A value of a type that JSON cannot hold crashes the app when fetchAll: builds the request, as the Known issue below describes. Pass an NSString, NSNumber, NSArray, NSDictionary or NSNull.
- An invalid value surfaces in the error argument of the completion block of the next fetchAll: call.
Known issue A value that JSON cannot hold, such as an NSDate, crashes the app with NSInvalidArgumentException when fetchAll: builds the request. Pass a date as an ISO 8601 string, for example @"2024-01-15T00:00:00.000Z".
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. where:equalTo: stores the condition and makes no request. The fetchAll: call that follows sends it.
- fetchAll: sends every condition together as one JSON object in the query parameter, so the API returns only assets that match all of them. See Equals Operator, which applies to assets as well as entries.
- A second call with a different field adds a condition. A second call with the same field replaces the earlier value.
- In Swift, pass a string as NSString or a number as NSNumber, because the parameter type is NSObject.
Limitations
- Supports only an exact match. Filter the result array of fetchAll: in your own code for other comparisons.
Example
Basic usage: find an asset by file name (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary where:@"filename" equalTo:@"logo.png"];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Asset *asset in result) {
NSLog(@"%@ %@", asset.uid, asset.url);
}
}];Basic usage: find an asset by file name (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.where("filename", equalTo: "logo.png" as NSString)
assetLibrary.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for asset in result ?? [] {
print(asset.uid, asset.url)
}
}Combine two conditions (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary where:@"content_type" equalTo:@"image/png"];
[assetLibrary where:@"filename" equalTo:@"logo.png"];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
if (error) { return; }
NSLog(@"%lu matching assets", (unsigned long)result.count);
}];Combine two conditions (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.where("content_type", equalTo: "image/png" as NSString)
assetLibrary.where("filename", equalTo: "logo.png" as NSString)
assetLibrary.fetchAll { (type, result, error) in
guard error == nil else { return }
print("\(result?.count ?? 0) matching assets")
}