Group

View as Markdown

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.

NameTypeDescription
key (required)NSString *

UID of the multiple Markdown subfield to convert.

Default: Not applicable

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.

NameTypeDescription
key (required)NSString *

UID of the Markdown subfield to convert.

Default: Not applicable

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.

NameTypeDescription
key (required)NSString *

UID of the file subfield to read.

Default: Not applicable

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.

NameTypeDescription
key (required)NSString *

UID of the multiple file subfield to read.

Default: Not applicable

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.

NameTypeDescription
referenceKey (required)NSString *

UID of the reference subfield to read.

Default: Not applicable
contentTypeName (required)NSString *

Content type UID to give each returned entry.

Default: Not applicable

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.

NameTypeDescription
key (required)NSString *

UID of the nested Group field to read.

Default: Not applicable

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.

NameTypeDescription
key (required)NSString *

UID of the multiple nested Group field to read.

Default: Not applicable

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.

NameTypeDescription
key (required)NSString *

UID of the subfield to read.

Default: Not applicable

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