Global Fields
Global Fields
A global field is a reusable field, or group of fields, that you define once and reuse in several content types of a stack. Use this class to
- list every global field in the stack
- read one global field by its UID
- add the global field schema or the branch UID to the response
The stack creates the object with one of two globalField methods:
| Signature | Use |
|---|---|
| globalField() | Lists every global field. |
| globalField(String global_field_uid) | Reads one global field by its UID. |
fetch
fetch reads one global field by the UID that you pass to stack.globalField.
| Name | Type | Description |
|---|---|---|
| callback (required) | GlobalFieldsResultCallback | Receives the global field or the error. |
Returns: void. The result arrives in the callback.
Validation
- fetch checks that the object holds a UID that is not empty or null. Without one, fetch sends no request and calls onCompletion with a null model and an Error whose status code and error code are 0. This callback runs on the calling thread, before fetch returns.
- An object from stack.globalField() never holds a UID, so fetch on it always takes this path. Use the findAll method on that object instead.
- There is no other client-side validation. An unknown UID surfaces as an Error in the callback when the API rejects the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- fetch calls Get a single global field (GET /v3/global_fields/{global_field_uid}). One call sends one request.
- onCompletion(GlobalFieldsModel globalFieldsModel, Error error) fires when the request ends.
- On success, error is null and globalFieldsModel.getResponse() returns the global_field object from the response body as a JSONObject.
- On this call globalFieldsModel.getResultArray() returns an empty JSONArray.
- On failure, globalFieldsModel is null and error describes the failure.
- fetch sends the flags that includeGlobalFieldSchema and includeBranch recorded on this object.
- fetch always calls the network. It reads no cache and takes no cache policy.
Example
Basic usage: read one global field
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
import org.json.JSONObject;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField("<GLOBAL_FIELD_UID>");
globalField.fetch(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error == null) {
JSONObject globalFieldJson = globalFieldsModel.getResponse();
Log.d("Contentstack", globalFieldJson.optString("uid") + ": "
+ globalFieldJson.optString("title"));
} else {
// The API rejected the request or the network failed
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}Read one global field with its schema and branch
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField("<GLOBAL_FIELD_UID>")
.includeGlobalFieldSchema()
.includeBranch();
globalField.fetch(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error != null) { Log.e("Contentstack", error.getErrorMessage()); return; }
Log.d("Contentstack", globalFieldsModel.getResponse().toString());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}findAll
findAll lists every global field in the stack.
| Name | Type | Description |
|---|---|---|
| callback (required) | GlobalFieldsResultCallback | Receives the global fields or the error. |
Returns: void. The result arrives in the callback.
Validation
- There is no client-side validation.
- An invalid flag or header surfaces as an Error in the callback when the API rejects the request.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- findAll calls Get all global fields (GET /v3/global_fields). One call sends one request.
- onCompletion(GlobalFieldsModel globalFieldsModel, Error error) fires when the request ends.
- On success, error is null and globalFieldsModel.getResultArray() returns the global_fields array from the response body as a JSONArray.
- On this call globalFieldsModel.getResponse() returns an empty JSONObject.
- On failure, globalFieldsModel is null and error describes the failure.
- findAll ignores the UID of an object that you create with stack.globalField("<GLOBAL_FIELD_UID>") and lists every global field.
- findAll sends the flags that includeGlobalFieldSchema and includeBranch recorded on this object.
- findAll sends no limit or skip parameter, and the SDK has no method that adds one to this request.
- findAll always calls the network. It reads no cache and takes no cache policy.
Example
Basic usage: list every global field
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
import org.json.JSONArray;
import org.json.JSONObject;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField();
globalField.findAll(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error == null) {
JSONArray globalFields = globalFieldsModel.getResultArray();
for (int i = 0; i < globalFields.length(); i++) {
JSONObject globalFieldJson = globalFields.optJSONObject(i);
Log.d("Contentstack", globalFieldJson.optString("uid"));
}
} else {
// The API rejected the request or the network failed
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}List every global field with its schema and branch
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField().includeGlobalFieldSchema().includeBranch();
globalField.findAll(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error != null) { Log.e("Contentstack", error.getErrorMessage()); return; }
Log.d("Contentstack", globalFieldsModel.getResultArray().toString());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}includeBranch
includeBranch asks the API to add the _branch key, which holds the UID of the branch where the global field resides.
Returns: GlobalField. The same global field, for chaining.
Validation
- There is no client-side validation.
- An error from the request surfaces as an Error in the callback when fetch or findAll sends it, not from includeBranch.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeBranch records include_branch=true on this object and sends no request.
- fetch and findAll send the flag on every later call on the same object. A second call to includeBranch changes nothing.
- The API reference describes the flag on Get a single global field and Get all global fields.
- The callback model exposes only the global_field object (getResponse()) and the global_fields array (getResultArray()). Read the _branch key from those values.
- To read from a branch other than the stack's, set the branch header with the setHeader method. includeBranch only reports the branch.
Example
Basic usage: show the branch of a global field
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField("<GLOBAL_FIELD_UID>").includeBranch();
globalField.fetch(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error == null) {
Log.d("Contentstack", "Branch: " + globalFieldsModel.getResponse().optString("_branch"));
} else {
// The API rejected the request or the network failed
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}includeGlobalFieldSchema
includeGlobalFieldSchema asks the API to include the schema of each global field in the response.
Returns: GlobalField. The same global field, for chaining.
Validation
- There is no client-side validation.
- An error from the request surfaces as an Error in the callback when fetch or findAll sends it, not from includeGlobalFieldSchema.
Additional Resource Refer to Content Delivery API Errors for the full error code list.
Behavior
- Client-side only. includeGlobalFieldSchema records include_global_field_schema=true on this object and sends no request.
- fetch and findAll send the flag on every later call on the same object. A second call to includeGlobalFieldSchema changes nothing.
- The API reference describes the flag on Get a single global field and Get all global fields.
- The schema arrives in the schema array of each global field object. Nested global fields appear inside that schema.
Example
Basic usage: read the fields of a global field
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
import org.json.JSONArray;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField("<GLOBAL_FIELD_UID>").includeGlobalFieldSchema();
globalField.fetch(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error == null) {
JSONArray schema = globalFieldsModel.getResponse().optJSONArray("schema");
Log.d("Contentstack", "Fields: " + (schema == null ? 0 : schema.length()));
} else {
// The API rejected the request or the network failed
Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
+ error.getErrorCode() + " " + error.getErrorMessage());
}
}
});
} catch (Exception e) {
// Contentstack.stack throws when a credential is null
Log.e("Contentstack", "Setup failed: " + e.getMessage());
}removeHeader
removeHeader removes a header that setHeader added to this global field object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header to remove. |
Returns: void. This method returns nothing.
Validation
- removeHeader ignores the call when key is empty or null.
- A key that this object does not hold changes nothing and raises no error.
Behavior
- Client-side only. removeHeader changes this object and sends no request.
- removeHeader removes only the headers that you add through setHeader on this object. A stack header with the same name, such as environment or branch, still goes out on this object's requests.
- fetch and findAll stop sending the header on later calls.
Example
Basic usage: stop sending a custom header
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField("<GLOBAL_FIELD_UID>");
globalField.setHeader("branch", "<BRANCH>");
// Read the global field from the stack's branch instead
globalField.removeHeader("branch");
globalField.fetch(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error != null) { Log.e("Contentstack", error.getErrorMessage()); return; }
Log.d("Contentstack", globalFieldsModel.getResponse().optString("title"));
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}setHeader
setHeader adds a header to the requests of this global field object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header to send. |
| value (required) | String | Value of the header to send. |
Returns: void. This method returns nothing.
Validation
- setHeader ignores the call when key or value is empty or null. It records nothing and raises no error.
- There is no other client-side validation.
Behavior
- Client-side only. setHeader records the header on this object and sends no request.
- A second call with the same key replaces the value.
- fetch and findAll send the header on every later call on this object.
- The header replaces a stack header with the same name for this object's requests. The stack and other global field objects keep their own headers.
- Use the removeHeader method to stop sending it.
Example
Basic usage: list the global fields of a branch
import android.util.Log;
import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.GlobalField;
import com.contentstack.sdk.GlobalFieldsModel;
import com.contentstack.sdk.GlobalFieldsResultCallback;
import com.contentstack.sdk.Stack;
try {
Config config = new Config();
config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
GlobalField globalField = stack.globalField();
globalField.setHeader("branch", "<BRANCH>");
globalField.findAll(new GlobalFieldsResultCallback() {
@Override
public void onCompletion(GlobalFieldsModel globalFieldsModel, Error error) {
if (error != null) { Log.e("Contentstack", error.getErrorMessage()); return; }
Log.d("Contentstack", "Global fields: " + globalFieldsModel.getResultArray().length());
}
});
} catch (Exception e) {
Log.e("Contentstack", e.getMessage());
}