ContentType

View as Markdown

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.

NameTypeDescription
headers (required)NSDictionary<NSString *, NSString *> *

Header names mapped to the values to send.

Default: Not applicable

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.

NameTypeDescription
uid (required)NSString *

UID of the entry to fetch.

Default: Not applicable

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.

NameTypeDescription
paramsNSDictionary<NSString *, id> *

Query parameters to send, such as include_branch.

Default: nil
completionBlock (required)void (^)(NSDictionary<NSString *, NSString *> *, NSError *)

Receives the content type dictionary, or an error.

Default: Not applicable

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.

NameTypeDescription
headerKey (required)NSString *

Name of the header to remove.

Default: Not applicable

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.

NameTypeDescription
headerValue (required)NSString *

Value of the header to send.

Default: Not applicable
headerKey (required)NSString *

Name of the header to send.

Default: Not applicable

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")
}