Group
Group
A Group field contains a set of subfields inside an entry, and can contain other Group fields. Use this class to
- read the raw value of a subfield
- read file subfields as Asset objects
- read nested Group fields as Group objects
- read reference subfields as Entry objects
- convert Markdown subfields to HTML
Group makes no network request. It reads values that an Entry fetch or a query already loaded. Its readers work the same way as the readers of the same name on Entry.
HTMLArrayForMarkdownKey:
HTMLArrayForMarkdownKey: converts each value of a multiple Markdown subfield of the group to an HTML string.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the multiple Markdown subfield to convert. |
Returns: NSArray. The HTML for each Markdown value under the key, or nil.
Validation
- There is no client-side validation.
- HTMLArrayForMarkdownKey: returns nil in each of these cases:
- The group holds no value under the key.
- The value is not an array, for example the string of a single Markdown subfield.
- The conversion of any element fails.
Behavior
- Client-side only. HTMLArrayForMarkdownKey: converts the values that the group already holds, and makes no request.
- The result keeps the order of the subfield value, with one HTML string for each Markdown string.
- The SDK converts with GitHub Flavored Markdown extensions, the same as the HTMLStringForMarkdownKey: method.
- In Swift, the method is htmlArray(forMarkdownKey:) and returns [Any]?.
Example
Render a multiple Markdown subfield as HTML (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;
}
Group *faq = [entry groupForKey:@"faq"];
for (NSString *html in [faq HTMLArrayForMarkdownKey:@"answers"]) {
NSLog(@"%@", html);
}
}];Render a multiple Markdown subfield as HTML (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
}
guard let faq = entry.group(forKey: "faq") else { return }
for case let html as String in faq.htmlArray(forMarkdownKey: "answers") ?? [] {
print(html)
}
}HTMLStringForMarkdownKey:
HTMLStringForMarkdownKey: converts the value of a Markdown subfield of the group to an HTML string.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the Markdown subfield to convert. |
Returns: NSString. The HTML for the Markdown value under the key, or nil.
Validation
- There is no client-side validation.
- HTMLStringForMarkdownKey: returns nil in each of these cases:
- The group holds no value under the key.
- The value is not a string, for example the array of a multiple Markdown subfield.
- The value is an empty string.
- The conversion fails.
Behavior
- Client-side only. HTMLStringForMarkdownKey: converts the value that the group already holds, and makes no request.
- The SDK converts with GitHub Flavored Markdown extensions, so tables, fenced code blocks and strikethrough produce HTML.
- A Markdown subfield marked as multiple holds an array. Use the HTMLArrayForMarkdownKey: method for it.
- In Swift, the method is htmlString(forMarkdownKey:) and returns String?.
Example
Render a Markdown subfield as HTML (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;
}
Group *hero = [entry groupForKey:@"hero"];
NSString *html = [hero HTMLStringForMarkdownKey:@"body"];
NSLog(@"%@", html ?: @"No Markdown under body");
}];Render a Markdown subfield as HTML (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
}
let hero = entry.group(forKey: "hero")
print(hero?.htmlString(forMarkdownKey: "body") ?? "No Markdown under body")
}assetForKey:
assetForKey: returns the asset in a single file subfield of the group as an Asset object.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the file subfield to read. |
Returns: Asset. The asset stored under the key, or nil.
Validation
- There is no client-side validation.
- A key that the group does not hold, or a value that is not a JSON object, returns nil.
Known issue In Swift, asset(forKey:) returns a non-optional Asset even when the SDK finds no asset, and using that value can crash the app. Check that group.object(forKey:) returns a [String: Any] for the key before you call asset(forKey:).
Behavior
- Client-side only. assetForKey: builds an Asset from the subfield value that the group already holds, and makes no request.
- The Asset exposes the asset details from the entry response, such as uid, fileName, url and fileType. See the Asset class.
- A file subfield that allows multiple files holds an array. Use the assetsForKey: method for it, because assetForKey: returns nil for an array.
- On a group from an entry that a taxonomy query returned, assetForKey: returns nil. See the Known issue on the Entry class page.
Example
Read the image of a Group field (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;
}
Group *seo = [entry groupForKey:@"seo"];
Asset *image = [seo assetForKey:@"social_image"];
if (image) {
NSLog(@"%@ %@", image.fileName, image.url);
}
}];Read the image of a Group field (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
}
// Check the raw value first, because asset(forKey:) is non-optional in Swift.
if let seo = entry.group(forKey: "seo"), seo.object(forKey: "social_image") is [String: Any] {
let image = seo.asset(forKey: "social_image")
print(image.fileName, image.url)
}
}assetsForKey:
assetsForKey: returns the assets in a multiple file subfield of the group as Asset objects.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the multiple file subfield to read. |
Returns: NSArray. The assets stored under the key, or an empty array.
Validation
- There is no client-side validation.
- A key that the group does not hold, or a value that is not an array, returns an empty array.
Behavior
- Client-side only. assetsForKey: builds one Asset for each element of the array that the group already holds, and makes no request.
- The array keeps the order of the subfield value.
- Each Asset exposes the asset details from the entry response, such as uid, fileName, url and fileType. See the Asset class.
- A file subfield that allows one file holds a single object. Use the assetForKey: method for it, because assetsForKey: returns an empty array for an object.
- On a group from an entry that a taxonomy query returned, assetsForKey: returns an empty array. See the Known issue on the Entry class page.
Example
List the images of a Group field (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;
}
Group *showcase = [entry groupForKey:@"showcase"];
for (Asset *image in [showcase assetsForKey:@"images"]) {
NSLog(@"%@ %@", image.fileName, image.url);
}
}];List the images of a Group field (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
}
guard let showcase = entry.group(forKey: "showcase") else { return }
for case let image as Asset in showcase.assets(forKey: "images") {
print(image.fileName, image.url)
}
}entriesForKey:withContentType:
entriesForKey:withContentType: returns the entries in a reference subfield of the group as Entry objects.
| Name | Type | Description |
|---|---|---|
| referenceKey (required) | NSString * | UID of the reference subfield to read. |
| contentTypeName (required) | NSString * | Content type UID to give each returned entry. |
Returns: NSArray. The referenced entries stored under the key, or nil.
Validation
- There is no client-side validation. entriesForKey:withContentType: does not check contentTypeName against the referenced entries.
- A key that the group does not hold, or a value that is not an array, returns nil in Objective-C and an empty array in Swift.
Behavior
- Client-side only. entriesForKey:withContentType: builds one Entry for each element of the reference subfield, and makes no request.
- The content of each Entry depends on whether the fetch that loaded the parent entry resolved the subfield, in the two cases below:
- When the fetch resolved the subfield, each Entry holds the full referenced entry. Resolve it with a dot path such as seo.related_pages in the includeRefFieldWithKey: method, as Include Reference Within Group describes.
- Otherwise each Entry holds only uid and _content_type_uid. Call fetch: on it to load its fields.
- Every returned Entry belongs to the content type that you pass, even when the subfield references entries of several content types. For such a subfield, read _content_type_uid from each entry with the objectForKey: method of Entry.
- In Swift, the method is entries(forKey:withContentType:) and returns [Any]. Cast each element to Entry.
Example
Read the resolved references of a Group field (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 includeRefFieldWithKey:@[@"seo.related_pages"]];
[entry fetch:^(ResponseType type, NSError *error) {
if (error) {
NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
return;
}
Group *seo = [entry groupForKey:@"seo"];
for (Entry *page in [seo entriesForKey:@"related_pages" withContentType:@"page"]) {
NSLog(@"%@ %@", page.title, page.url);
}
}];Read the resolved references of a Group field (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.includeRefField(withKey: ["seo.related_pages"])
entry.fetch { (type, error) in
if let error = error as NSError? {
print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
return
}
guard let seo = entry.group(forKey: "seo") else { return }
for case let page as Entry in seo.entries(forKey: "related_pages", withContentType: "page") {
print(page.title, page.url)
}
}groupForKey:
groupForKey: returns the value of a single nested Group field as a Group object.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the nested Group field to read. |
Returns: Group. The group stored under the key, or nil.
Validation
- There is no client-side validation.
- A key that the group does not hold, or a value that is not a JSON object, returns nil.
Behavior
- Client-side only. groupForKey: copies the subfield value that the group already holds into a new Group, and makes no request.
- The nested Group keeps the values from the moment of the call, the same as a group from the groupForKey: method of Entry.
- A nested Group field marked as multiple holds an array. Use the groupsForKey: method for it, because groupForKey: returns nil for an array.
- In Swift, the method is forKey(_:), not group(forKey:), and returns Group?. The Swift compiler drops the word "group" from the name because it repeats the class name.
Example
Read a nested Group field (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;
}
Group *seo = [entry groupForKey:@"seo"];
Group *openGraph = [seo groupForKey:@"open_graph"];
NSLog(@"%@", [openGraph objectForKey:@"og_title"]);
}];Read a nested Group field (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
}
// In Swift, Group.groupForKey: is named forKey(_:).
if let seo = entry.group(forKey: "seo"), let openGraph = seo.forKey("open_graph") {
print(openGraph.object(forKey: "og_title") ?? "")
}
}groupsForKey:
groupsForKey: returns the values of a multiple nested Group field as Group objects.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the multiple nested Group field to read. |
Returns: NSArray. The groups stored under the key, or nil.
Validation
- There is no client-side validation.
- A key that the group does not hold, or a value that is not an array, returns nil in Objective-C and an empty array in Swift.
Behavior
- Client-side only. groupsForKey: copies each element of the array that the group already holds into a new Group, and makes no request.
- The array keeps the order of the subfield value.
- Each Group keeps the values from the moment of the call.
- A nested Group field that allows one value holds a single object. Use the groupForKey: method for it.
- In Swift, the method is groups(forKey:) and returns [Any]. Cast each element to Group.
Example
List the items of a multiple nested Group field (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;
}
Group *contact = [entry groupForKey:@"contact"];
for (Group *phone in [contact groupsForKey:@"phones"]) {
NSLog(@"%@: %@", [phone objectForKey:@"label"], [phone objectForKey:@"number"]);
}
}];List the items of a multiple nested Group field (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
}
guard let contact = entry.group(forKey: "contact") else { return }
for case let phone as Group in contact.groups(forKey: "phones") {
print(phone.object(forKey: "label") ?? "", phone.object(forKey: "number") ?? "")
}
}objectForKey:
objectForKey: returns the raw value of one subfield of the group.
| Name | Type | Description |
|---|---|---|
| key (required) | NSString * | UID of the subfield to read. |
Returns: id. The value stored under the key, or nil.
Validation
- There is no client-side validation.
- A key that the group does not hold returns nil. In Objective-C, a nil key also returns nil.
Behavior
- Client-side only. objectForKey: reads the values that the group copied from its entry, and makes no request.
- The value keeps the type that the JSON response gave it:
- Text subfields return NSString.
- Number and Boolean subfields return NSNumber.
- Multiple subfields, reference subfields and nested multiple groups return NSArray.
- Nested groups and file subfields return NSDictionary.
- A JSON null returns NSNull.
- Group has no subscript and no hasKey: method. Check that objectForKey: returns a value to test whether a subfield is present.
- In Swift, the method is object(forKey:) and returns Any?.
- Use the typed readers for subfields that the SDK can wrap: assetForKey:, groupForKey:, entriesForKey:withContentType: and HTMLStringForMarkdownKey:.
Example
Read a subfield of a Group field (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;
}
Group *seo = [entry groupForKey:@"seo"];
NSString *metaTitle = [seo objectForKey:@"meta_title"];
NSLog(@"%@", metaTitle);
}];Read a subfield of a Group field (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
}
if let seo = entry.group(forKey: "seo") {
print(seo.object(forKey: "meta_title") as? String ?? "")
}
}