Taxonomy
Taxonomy
A taxonomy arranges the content of a stack into a hierarchy of terms that entries carry. Use the Taxonomy class to find the published entries tagged with a term, across every content type of the stack, in one request.
Get the object from the taxonomy method of Stack, which takes no arguments. Each call returns a new Taxonomy object. The object holds no taxonomy UID. You name the taxonomy inside each condition, as the field path taxonomies.<TAXONOMY_UID>.
addHeadersWithDictionary:
addHeadersWithDictionary: sets several HTTP headers at once that the SDK sends with the requests of this taxonomy.
| Name | Type | Description |
|---|---|---|
| headers (required) | NSDictionary<NSString *, NSString *> * | Header names mapped to the values to send. |
Returns: void. Nothing. The taxonomy keeps the setting for its next 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 findTaxonomy: call.
Behavior
- Client-side only. addHeadersWithDictionary: copies each pair into the headers of this taxonomy 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.
- findTaxonomy: sends the headers of this taxonomy with every query that the taxonomy created through query, including queries created before the change.
- A header that a query sets with its own setHeader:forKey: replaces the taxonomy header of the same name for that query.
- fetch:completion: on this taxonomy 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"];
Taxonomy *taxonomy = [stack taxonomy];
[taxonomy addHeadersWithDictionary:@{@"x-cs-variant-uid": @"VARIANT_UID", @"branch": @"BRANCH_UID"}];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(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 taxonomy = stack.taxonomy()
taxonomy.addHeaders(with: ["x-cs-variant-uid": "VARIANT_UID", "branch": "BRANCH_UID"])
let query = taxonomy.query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (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")
}fetch:completion:
fetch:completion: requests the published entries tagged with taxonomy terms, with the query parameters you pass, and hands the entries value of the response to the completion block.
| Name | Type | Description |
|---|---|---|
| params | NSDictionary<NSString *, id> * | Query parameters to send, such as query and locale. |
| completionBlock (required) | void (^)(NSDictionary<NSString *, NSString *> *, NSError *) | Receives the entries value, 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 entries dictionary, the completion block receives an NSError with domain Error, code -4001, and the reason under userInfo[@"error"]. The Known issue above describes when this happens.
Additional Resource Refer to Delivery API Errors for the full error code list.
Behavior
- One call sends one Get all entries with defined taxonomies request (GET /taxonomies/entries).
- The SDK adds the stack environment in the environment parameter. A params key named environment replaces it.
- The SDK encodes a dictionary under the query key of params as JSON in the query parameter. Every other key goes into the query string as given.
- The request carries the stack headers only. Headers that you set on this taxonomy with setHeader:forKey: do not reach it.
- The request always goes to the network. fetch:completion: has no cache policy.
Example
Request the entries tagged with a term (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
NSDictionary *params = @{@"query": @{@"taxonomies.TAXONOMY_UID": @"TERM_UID"}, @"locale": @"en-us"};
[taxonomy fetch:params completion:^(NSDictionary<NSString *, NSString *> *entries, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
NSLog(@"%@", entries);
}];Request the entries tagged with a term (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let params: [String: Any] = ["query": ["taxonomies.TAXONOMY_UID": "TERM_UID"], "locale": "en-us"]
taxonomy.fetch(params) { (entries, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
print(entries ?? [:])
}Error handling: tell an unexpected response from an API rejection (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[[stack taxonomy] fetch:nil completion:^(NSDictionary<NSString *, NSString *> *entries, NSError *error) {
if ([error.domain isEqualToString:@"Error"]) {
// The response arrived, but entries was not a dictionary.
NSLog(@"%@", error.userInfo[@"error"]);
return;
}
if (error) { return; }
NSLog(@"%@", entries);
}];Error handling: tell an unexpected response from an API rejection (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.taxonomy().fetch(nil) { (entries, error) in
if let error = error as NSError?, error.domain == "Error" {
// The response arrived, but entries was not a dictionary.
print(error.userInfo["error"] ?? "")
return
}
guard error == nil else { return }
print(entries ?? [:])
}query
query creates a Query that finds the published entries tagged with taxonomy terms, across every content type of the stack.
Returns: Query. A new query object for this taxonomy.
Validation
- There is no client-side validation. query makes no request.
- Errors come from the findTaxonomy: 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.
- findTaxonomy: sends the Get all entries with defined taxonomies request (GET /taxonomies/entries). The SDK encodes the conditions as JSON in the query parameter and adds the stack environment in the environment parameter.
- The query keeps a reference to this taxonomy. findTaxonomy: reads the taxonomy headers when it sends the request, so a header that you set on the taxonomy after query still applies.
- A header that the query sets with its own setHeader:forKey: replaces the taxonomy header of the same name for that query.
- The SDK has no method for the hierarchy operators (Equal and Below, Below, Equal and Above, Above). Use whereKey:equalTo: instead.
- whereKey:equalTo: stores a dictionary value as given, so you can pass a hierarchy operator dictionary as the value. The third example below shows this.
Example
Find the entries tagged with a term (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack taxonomy] query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(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 tagged with a term (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.taxonomy().query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (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)
}
}Match a term in either of two taxonomies (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *colorQuery = [taxonomy query];
[colorQuery whereKey:@"taxonomies.color" equalTo:@"red"];
Query *sizeQuery = [taxonomy query];
[sizeQuery whereKey:@"taxonomies.size" equalTo:@"small"];
Query *query = [taxonomy query];
[query orWithSubqueries:@[colorQuery, sizeQuery]];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];Match a term in either of two taxonomies (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let colorQuery = taxonomy.query()
colorQuery.whereKey("taxonomies.color", equalTo: "red")
let sizeQuery = taxonomy.query()
sizeQuery.whereKey("taxonomies.size", equalTo: "small")
let query = taxonomy.query()
query.or(withSubqueries: [colorQuery, sizeQuery])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
print("\(result?.getResult()?.count ?? 0) entries")
}Match a term and the two levels of terms below it (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack taxonomy] query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@{@"$eq_below": @"TERM_UID", @"levels": @2}];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
if (error) { return; }
NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];Match a term and the two levels of terms below it (Swift)
import Contentstack
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.taxonomy().query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: ["$eq_below": "TERM_UID", "levels": 2])
query.findTaxonomy { (type, result, error) in
guard error == nil else { return }
print("\(result?.getResult()?.count ?? 0) entries")
}removeHeaderForKey:
removeHeaderForKey: removes one header that you set on this taxonomy, so later requests no longer send it.
| Name | Type | Description |
|---|---|---|
| headerKey (required) | NSString * | Name of the header to remove. |
Returns: void. Nothing. The taxonomy keeps the setting for its next query request.
Validation
- There is no client-side validation. A name that this taxonomy does not hold, or nil, changes nothing.
- An invalid header surfaces in the error argument of the completion block of the next findTaxonomy: call.
Behavior
- Client-side only. removeHeaderForKey: deletes the header from this taxonomy and makes no request.
- It removes only headers set on this taxonomy. Stack headers such as api_key and access_token, and headers set on an entry or a query, stay in place.
- findTaxonomy: sends the headers of this taxonomy with every query that the taxonomy created through query, including queries created before the change.
Example
Stop sending a variant header (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
[taxonomy setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
[taxonomy removeHeaderForKey:@"x-cs-variant-uid"];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(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 taxonomy = stack.taxonomy()
taxonomy.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
taxonomy.removeHeader(forKey: "x-cs-variant-uid")
let query = taxonomy.query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (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 taxonomy.
| 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 taxonomy keeps the setting for its next 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 findTaxonomy: call.
Behavior
- Client-side only. setHeader:forKey: stores the pair on this taxonomy and makes no request. A second call with the same headerKey replaces the value.
- findTaxonomy: sends the headers of this taxonomy with every query that the taxonomy created through query, including queries created before the change.
- A header that a query sets with its own setHeader:forKey: replaces the taxonomy header of the same name for that query.
- fetch:completion: on this taxonomy 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 entries by taxonomy with variants request reads variant UIDs from the x-cs-variant-uid header. The API then applies that variant to each matching entry.
Example
Apply a variant to the entries (Objective-C)
#import <Contentstack/Contentstack.h>
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
[taxonomy setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(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 taxonomy = stack.taxonomy()
taxonomy.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
let query = taxonomy.query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (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")
}