ContentType
ContentType
A ContentType object stands for one content type of your stack. Use it for the tasks below:
- build an Entry by UID
- build a Query over the entries of the content type
- read the content type schema
- set headers for entry and query requests
Get the object from the contentTypeWithName: method of Stack, which takes the content type UID. Each call returns a new object. The SDK does not check the UID, so a wrong UID fails only at the first request.
addHeadersWithDictionary:
addHeadersWithDictionary: sets several HTTP headers at once that the SDK sends with the requests of this content type.
| Name | Type | Description |
|---|---|---|
| headers (required) | NSDictionary<NSString *, NSString *> * | Header names mapped to the values to send. |
Returns: void. Nothing. The content type keeps the setting for its next entry or query request.
Validation
- There is no client-side validation. A nil or empty dictionary changes nothing.
- An invalid header surfaces in the error argument of the completion block of the next fetch: or find: call.
Behavior
- Client-side only. addHeadersWithDictionary: copies each pair into the headers of this content type and makes no request.
- A name that the object already holds gets the new value. Headers that the dictionary does not name stay as they are.
- The SDK sends the headers of this content type with fetch: on every entry from entryWithUID:, and with find: and findOne: on every query from query. It reads them when the request goes out, so entries and queries created before the change send them too.
- A header that the entry or the query sets with its own setHeader:forKey: replaces the content type header of the same name for that object.
- fetch:completion: on this content type does not send these headers.
- A header with the same name as a stack header, such as access_token, replaces the stack value for these requests.
- When you set Config.branch, the SDK writes it to the branch header after your headers, so it replaces a branch header that you set here.
Example
Set a variant and a branch in one call (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
[contentType addHeadersWithDictionary:@{@"x-cs-variant-uid": @"VARIANT_UID", @"branch": @"BRANCH_UID"}];
Query *query = [contentType query];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];Set a variant and a branch in one call (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
contentType.addHeaders(with: ["x-cs-variant-uid": "VARIANT_UID", "branch": "BRANCH_UID"])
let query = contentType.query()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.getResult()?.count ?? 0) entries")
}entryWithUID:
entryWithUID: creates an Entry object for one entry of this content type, ready to fetch.
| Name | Type | Description |
|---|---|---|
| uid (required) | NSString * | UID of the entry to fetch. |
Returns: Entry. A new entry object for the given UID.
Validation
- There is no client-side validation. entryWithUID: stores uid as given and makes no request.
- A wrong or empty UID surfaces in the error argument of the completion block of the fetch: call that follows.
Behavior
- Client-side only. Each call returns a new Entry, even for the same UID.
- The entry holds no field values until fetch: succeeds. fetch: sends the Get a single entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}).
- The entry reads the headers of this content type when it sends its request, so a header that you set with setHeader:forKey: after entryWithUID: still reaches that request.
Example
Fetch an entry (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%@", entry.title);
}];Fetch an entry (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print(entry.title)
}fetch:completion:
fetch:completion: reads the definition of this content type, including its schema, and hands the content_type value of the response to the completion block.
| Name | Type | Description |
|---|---|---|
| params | NSDictionary<NSString *, id> * | Query parameters to send, such as include_branch. |
| completionBlock (required) | void (^)(NSDictionary<NSString *, NSString *> *, NSError *) | Receives the content type dictionary, or an error. |
Returns: void. Nothing. The completion block receives the result.
Validation
- There is no client-side validation. fetch:completion: sends every key of params as given.
- 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.
- When the response has no content_type dictionary, the completion block receives an NSError with domain Error, code -4001, and the reason under userInfo[@"error"].
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- One call sends one Get a single content type request (GET /content_types/{content_type_uid}). The API returns the content type schema without its entries.
- The completion block receives the value of the content_type key, not the whole response body.
- The block declares NSDictionary<NSString *, NSString *> *, but the values have mixed types, such as the schema array. Read each value as id.
- The SDK adds the stack environment in the environment parameter. A params key named environment replaces it.
- include_branch set to true asks the API for the _branch key, which names the branch of the content type, as the Get a single content type parameters describe.
- The request carries the stack headers only. Headers that you set on this content type with setHeader:forKey: do not reach it.
- The request always goes to the network. fetch:completion: has no cache policy.
Example
Read a content type schema (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
[contentType fetch:@{@"include_branch": @"true"} completion:^(NSDictionary<NSString *, NSString *> *definition, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSDictionary *raw = definition;
NSArray *fields = raw[@"schema"];
NSLog(@"%@ has %lu fields", raw[@"title"], (unsigned long)fields.count);
}];Read a content type schema (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
// fetch(_:completion:) crashes in Swift on success, so read the content type through a query.
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.includeContentType()
query.limitObjects(1)
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
let definition = result?.content_type() ?? [:]
let fields = definition["schema"] as? [[String: Any]] ?? []
print("\(definition["title"] ?? "") has \(fields.count) fields")
}query
query creates a Query that finds the published entries of this content type.
Returns: Query. A new query object for this content type.
Validation
- There is no client-side validation. query makes no request.
- Errors come from the find: or findOne: call that follows, not from query. Its completion block receives them.
Behavior
- Client-side only. Each call returns a new Query with no conditions, so conditions on one query do not reach another.
- find: sends the Get all entries request (GET /content_types/{content_type_uid}/entries) and passes a QueryResult to its completion block.
- The query reads the headers of this content type when it sends the request. A header that the query sets with its own setHeader:forKey: replaces the content type header of the same name.
Example
Find the entries that match a field value (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] query];
[query whereKey:@"title" equalTo:@"Red running shoes"];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (Entry *entry in [result getResult]) {
NSLog(@"%@ %@", entry.uid, entry.title);
}
}];Find the entries that match a field value (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.whereKey("title", equalTo: "Red running shoes")
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for entry in result?.getResult() ?? [] {
print(entry.uid, entry.title)
}
}Read the first matching entry (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] query];
[query whereKey:@"url" equalTo:@"/products/red-running-shoes"];
[query findOne:^(ResponseType type, Entry *entry, NSError *error) {
if (error) { return; }
NSLog(@"%@", entry.title);
}];Read the first matching entry (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.whereKey("url", equalTo: "/products/red-running-shoes")
query.findOne { (type, entry, error) in
guard error == nil, let entry = entry else { return }
print(entry.title)
}removeHeaderForKey:
removeHeaderForKey: removes one header that you set on this content type, so later requests no longer send it.
| Name | Type | Description |
|---|---|---|
| headerKey (required) | NSString * | Name of the header to remove. |
Returns: void. Nothing. The content type keeps the setting for its next entry or query request.
Validation
- There is no client-side validation. A name that this content type does not hold, or nil, changes nothing.
- An invalid header surfaces in the error argument of the completion block of the next fetch: or find: call.
Behavior
- Client-side only. removeHeaderForKey: deletes the header from this content type and makes no request.
- It removes only headers set on this content type. Stack headers such as api_key and access_token, and headers set on an entry or a query, stay in place.
- The SDK sends the headers of this content type with fetch: on every entry from entryWithUID:, and with find: and findOne: on every query from query. It reads them when the request goes out, so entries and queries created before the change send them too.
Example
Stop sending a variant header (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
[contentType setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
[contentType removeHeaderForKey:@"x-cs-variant-uid"];
Query *query = [contentType query];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];Stop sending a variant header (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
contentType.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
contentType.removeHeader(forKey: "x-cs-variant-uid")
let query = contentType.query()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.getResult()?.count ?? 0) entries")
}setHeader:forKey:
setHeader:forKey: sets one HTTP header that the SDK sends with the requests of this content type.
| Name | Type | Description |
|---|---|---|
| headerValue (required) | NSString * | Value of the header to send. |
| headerKey (required) | NSString * | Name of the header to send. |
Returns: void. Nothing. The content type keeps the setting for its next entry or query request.
Validation
- There is no client-side validation. The SDK stores an empty string as given.
- A nil headerValue or headerKey raises NSInvalidArgumentException, because the SDK stores the pair in a mutable dictionary that rejects nil. Both parameters are nonnull, so the compiler warns on a literal nil.
- An invalid header surfaces in the error argument of the completion block of the next fetch: or find: call.
Behavior
- Client-side only. setHeader:forKey: stores the pair on this content type and makes no request. A second call with the same headerKey replaces the value.
- The SDK sends the headers of this content type with fetch: on every entry from entryWithUID:, and with find: and findOne: on every query from query. It reads them when the request goes out, so entries and queries created before the change send them too.
- A header that the entry or the query sets with its own setHeader:forKey: replaces the content type header of the same name for that object.
- fetch:completion: on this content type does not send these headers.
- A header with the same name as a stack header, such as access_token, replaces the stack value for these requests.
- The Get multiple variants of an entry request reads variant UIDs from the x-cs-variant-uid header. The API then applies that variant to the entries of this content type.
Example
Apply a variant to the entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
[contentType setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
Query *query = [contentType query];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];Apply a variant to the entries (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
contentType.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
let query = contentType.query()
query.find { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(result?.getResult()?.count ?? 0) entries")
}