Global Fields
Global Fields
A global field is a reusable field, or group of fields, that you define once and use in several content types. Use the GlobalField class to read the definition of one global field, or to list every global field of the stack.
Import GlobalField.h in Objective-C. Contentstack.h does not import GlobalField.h, so an Objective-C file that calls a GlobalField method also needs #import <Contentstack/GlobalField.h>. Every Objective-C example on this page and its method pages carries both lines. In Swift, import Contentstack covers the class.
| Name | Type | Description |
|---|---|---|
| uid | NSString * | Read-only. UID of the global field. Holds the UID you passed to globalFieldWithName: before any fetch. |
| title | NSString * | Read-only. Title of the global field. |
| Description | NSString * | Read-only. Description of the global field. The Swift name is description. |
| version | unsigned int | Read-only. Version number, from the _version key. |
| schema | NSArray<NSDictionary *> * | Read-only. Field definitions of the global field. |
| branch | NSString * | Read-only. Branch UID, from the _branch key that includeBranch requests. |
| createdAt | NSDate * | Read-only. Creation time. Known issue: In Swift, reading it before a fetch fills the object crashes the app. Read it only after fetch: or fetchAll: succeeds. |
| updatedAt | NSDate * | Read-only. Last update time. Known issue: In Swift, reading it before a fetch fills the object crashes the app. Read it only after fetch: or fetchAll: succeeds. |
| inbuiltClass | BOOL | Read-only. Value of the inbuilt_class key. |
| maintainRevisions | BOOL | Read-only. Value of the maintain_revisions key. |
| lastActivity | NSDictionary * | Read-only. Value of the last_activity key. |
| properties | NSDictionary<NSString *, id> * | Read-only. Known issue: Always nil, or an empty dictionary in Swift, because no fetch fills it. Read the other properties instead. |
| cachePolicy | [CachePolicy](../CachePolicy/class_reference.md) | Read and write. Where fetch: and fetchAll: read the response from. Known issue: Only NETWORK_ONLY and NETWORK_ELSE_CACHE behave as named. The other policies send a network request and never read the cache. Use NETWORK_ELSE_CACHE for an offline fallback. |
addHeadersWithDictionary:
addHeadersWithDictionary: sets several HTTP headers at once that the SDK sends with the requests of this global field.
| Name | Type | Description |
|---|---|---|
| headers (required) | NSDictionary<NSString *, NSString *> * | Header names mapped to the values to send. |
Returns: void. Nothing. The global field keeps the setting for its next fetch.
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 fetchAll: call.
Behavior
- Client-side only. addHeadersWithDictionary: copies each pair into the headers of this global field 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.
- fetch: and fetchAll: on this object send its headers with every later request.
- The global field objects that fetchAll: returns do not carry 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 the branch and a custom header in one call (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
[globalField addHeadersWithDictionary:@{@"branch": @"BRANCH_UID", @"x-request-source": @"ios-app"}];
[globalField fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%@", globalField.title);
}];Set the branch and a custom header in one call (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.addHeaders(with: ["branch": "BRANCH_UID", "x-request-source": "ios-app"])
globalField.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print(globalField.title)
}fetch:
fetch: reads one global field by its UID and fills the properties of this object with the response.
| Name | Type | Description |
|---|---|---|
| callback (required) | void (^)(ResponseType, NSError *) | Receives where the response came from, and an error or nil. |
Returns: void. Nothing. The completion block receives the result.
Validation
- There is no client-side validation. On an object without a UID, fetch: still sends the request. The API rejects it, as the Warning on the GlobalField class page describes.
- 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.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- One call sends one Get a single global field request (GET /global_fields/{global_field_uid}).
- The completion block receives no data argument. On success, fetch: fills the properties of this object, such as title and schema, from the global_field key of the response. Read them on the same object inside the block.
- The request carries the stack environment in the environment parameter, the flags that includeGlobalFieldSchema and includeBranch set, and the headers of this object.
- The cachePolicy property decides where the response comes from, and the ResponseType argument reports CACHE or NETWORK. Only NETWORK_ONLY and NETWORK_ELSE_CACHE behave as named, as the Known issue on cachePolicy in the Properties table of the GlobalField class page describes.
Example
Read one global field (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
[globalField fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%@ version %u", globalField.title, globalField.version);
}];Read one global field (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(globalField.title) version \(globalField.version)")
}Fall back to the cache when the network fails (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
globalField.cachePolicy = NETWORK_ELSE_CACHE;
[globalField fetch:^(ResponseType type, NSError *error) {
if (error) { return; }
NSLog(@"%@ from %@", globalField.title, type == CACHE ? @"cache" : @"network");
}];Fall back to the cache when the network fails (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.cachePolicy = .NETWORK_ELSE_CACHE
globalField.fetch { (type, error) in
guard error == nil else { return }
print(globalField.title, type == .CACHE ? "from cache" : "from network")
}fetchAll:
fetchAll: lists every global field of the stack and returns one GlobalField object for each.
| Name | Type | Description |
|---|---|---|
| completionBlock (required) | void (^)(ResponseType, NSArray<GlobalField *> *, NSError *) | Receives the response source, the global fields, and an error 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.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- One call sends one Get all global fields request (GET /global_fields). fetchAll: ignores the UID of the object.
- The result argument holds a new GlobalField for each item of the global_fields key. The SDK fills the properties of each object from its item. It is an empty array when the stack has no global fields, and nil when the response has no global_fields array.
- The returned objects carry a UID, so you can call fetch: on any of them. They do not carry the flags, headers or cache policy of the object you called fetchAll: on.
- The request carries the stack environment in the environment parameter, the flags that includeGlobalFieldSchema and includeBranch set, and the headers of this object.
- fetchAll: sends no limit or skip, and the API reference lists no pagination parameter for this request.
- Calling fetch: on this object afterwards crashes the app, as the Known issue on fetch: describes. Call fetch: on a separate object from [stack globalFieldWithName:].
Example
List every global field (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalField];
[globalField fetchAll:^(ResponseType type, NSArray<GlobalField *> *result, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (GlobalField *field in result) {
NSLog(@"%@ %@", field.uid, field.title);
}
}];List every global field (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField()
globalField.fetchAll { (type, result, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for field in result ?? [] {
print(field.uid, field.title)
}
}List every global field with its schema and branch (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalField];
[globalField includeGlobalFieldSchema];
[globalField includeBranch];
[globalField fetchAll:^(ResponseType type, NSArray<GlobalField *> *result, NSError *error) {
if (error) { return; }
for (GlobalField *field in result) {
NSLog(@"%@ on %@: %lu fields", field.uid, field.branch, (unsigned long)field.schema.count);
}
}];List every global field with its schema and branch (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField()
globalField.includeSchema()
globalField.includeBranch()
globalField.fetchAll { (type, result, error) in
guard error == nil else { return }
for field in result ?? [] {
print("\(field.uid) on \(field.branch): \(field.schema.count) fields")
}
}includeBranch
includeBranch asks the API to add the _branch key, which names the branch of the global field, to the next response.
Returns: void. Nothing. The global field keeps the setting for its next fetch.
Validation
- There is no client-side validation.
- Errors that do occur come from the fetch: or fetchAll: call that follows, not from includeBranch. Its completion block receives them.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeBranch stores include_branch set to true on this object and makes no request.
- fetch: and fetchAll: send the parameter with every later request of this object. No method removes it.
- The API adds the _branch key, as the Get a single global field and Get all global fields parameters describe. The SDK reads it into the branch property.
- Without includeBranch, branch stays nil, or an empty string in Swift.
Example
Read the branch of a global field (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
[globalField includeBranch];
[globalField fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%@ is on branch %@", globalField.title, globalField.branch);
}];Read the branch of a global field (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.includeBranch()
globalField.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print("\(globalField.title) is on branch \(globalField.branch)")
}includeGlobalFieldSchema
includeGlobalFieldSchema asks the API to include the schema of the global field in the next response.
Returns: void. Nothing. The global field keeps the setting for its next fetch.
Validation
- There is no client-side validation.
- Errors that do occur come from the fetch: or fetchAll: call that follows, not from includeGlobalFieldSchema. Its completion block receives them.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeGlobalFieldSchema stores include_global_field_schema set to true on this object and makes no request.
- In Swift, the method is includeSchema().
- fetch: and fetchAll: send the parameter with every later request of this object. No method removes it.
- The Get a single global field and Get all global fields requests take the parameter to include the schema of the global field in the response. The SDK reads the schema into the schema property.
Example
Read a global field with its schema (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
[globalField includeGlobalFieldSchema];
[globalField fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
for (NSDictionary *field in globalField.schema) {
NSLog(@"%@ (%@)", field[@"uid"], field[@"data_type"]);
}
}];Read a global field with its schema (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.includeSchema()
globalField.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
for field in globalField.schema {
print(field["uid"] ?? "", field["data_type"] ?? "")
}
}removeHeaderForKey:
removeHeaderForKey: removes one header that you set on this global field, so later requests no longer send it.
| Name | Type | Description |
|---|---|---|
| headerKey (required) | NSString * | Name of the header to remove. |
Returns: void. Nothing. The global field keeps the setting for its next fetch.
Validation
- There is no client-side validation. A name that this global field does not hold, or nil, changes nothing.
- An invalid header surfaces in the error argument of the completion block of the next fetch: or fetchAll: call.
Behavior
- Client-side only. removeHeaderForKey: deletes the header from this global field and makes no request.
- It removes only headers set on this object. Stack headers such as api_key and access_token stay in place.
- fetch: and fetchAll: on this object send its headers with every later request.
Example
Stop sending a branch header (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
[globalField setHeader:@"BRANCH_UID" forKey:@"branch"];
[globalField removeHeaderForKey:@"branch"];
[globalField fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%@", globalField.title);
}];Stop sending a branch header (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.setHeader("BRANCH_UID", forKey: "branch")
globalField.removeHeader(forKey: "branch")
globalField.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print(globalField.title)
}setHeader:forKey:
setHeader:forKey: sets one HTTP header that the SDK sends with the requests of this global field.
| 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 global field keeps the setting for its next fetch.
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 fetchAll: call.
Behavior
- Client-side only. setHeader:forKey: stores the pair on this global field and makes no request. A second call with the same headerKey replaces the value.
- fetch: and fetchAll: on this object send its headers with every later request.
- The global field objects that fetchAll: returns do not carry 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 a single global field request reads the branch UID from the branch header. 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
Read a global field from a branch (Objective-C)
#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
[globalField setHeader:@"BRANCH_UID" forKey:@"branch"];
[globalField fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%@", globalField.title);
}];Read a global field from a branch (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.setHeader("BRANCH_UID", forKey: "branch")
globalField.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print(globalField.title)
}