Registering a Soup through Code

Hybrid Apps

The JavaScript function for registering a soup requires callback functions for success and error conditions.

1var sfSmartstore = function() {
2    return cordova.require("com.salesforce.plugin.smartstore");
3};
4sfSmartstore().registerSoup(soupName, indexSpecs, successCallback, errorCallback);

If the soup does not exist, this function creates it. If the soup exists, registering lets you access it.

indexSpecs

Use the indexSpecs array to create the soup with predefined indexing. Entries in the indexSpecs array specify how to index the soup. Each entry consists of a path:type pair. path is the name of an index field; type is either “string”, “integer”, “floating”, “full_text”, or “json1”.

1var indexSpecs = [
2    {path:"Name",type:"string"},
3    {path:"Id",type:"string"}
4];

• Index paths are case-sensitive and can include compound paths, such as Owner.Name.
• Index entries that are missing any fields described in an indexSpecs array are not tracked in that index.
• The type of the index applies only to the index. When you query an indexed field (for example, “select {soup:path} from {soup}”), the query returns data of the type that you specified in the index specification.
• Index columns can contain null fields.
• Beginning in Mobile SDK 4.1, you can specify index paths that point to internal (non-leaf) nodes. You can use these paths with like and match (full-text) queries. Use the string type when you define internal node paths.
• Beginning in Mobile SDK 4.1, you can include arrays in index paths, with some restrictions. See Using Arrays in Index Paths.

For example, consider this element in a soup named “spies”:

1{  
2   "first_name":"James",
3   "last_name":"Bond",
4   "address":{  
5      "street_number":10,
6      "street_name":"downing",
7      "city":"london"
8   }
9}

In this case, “address” is an internal node because it has children. Through the index on the path “address”, you can use a like or match query to find the “city” value—“london”—in “address”. For example:

1SELECT {spies:first_name, spies:last_name} FROM spies WHERE {spies:address} LIKE 'london'

Note

successCallback

The success callback function you supply takes one argument: the soup name. For example:

1function(soupName) { alert("Soup " + soupName + " was successfully created"); }

When the soup is successfully created, registerSoup() calls the success callback function to indicate that the soup is ready. Wait to complete the transaction and receive the callback before you begin any activity. If you register a soup under the passed name, the success callback function returns the soup.

errorCallback

The error callback function takes one argument: the error description string.

1function(err) { alert ("registerSoup failed with error: " + err); }

During soup creation, errors can happen for various reasons, including:

• An invalid or bad soup name
• No index (at least one index must be specified)
• Other unexpected errors, such as a database error

1navigator.smartstore.soupExists(soupName, successCallback, errorCallback);

Android Native Apps

1public class OfflineStorage extends SalesforceActivity {
2    private SmartStore smartStore;
3    final IndexSpec[] ACCOUNTS_INDEX_SPEC = {   
4        new IndexSpec("Name", SmartStore.Type.string),
5        new IndexSpec("Id", SmartStore.Type.string),
6        new IndexSpec("OwnerId", SmartStore.Type.string)
7    };
8
9    public OfflineStorage() {
10        smartStore = SmartStoreSDKManager.getInstance().getSmartStore();
11        smartStore.registerSoup("Account", ACCOUNTS_INDEX_SPEC);
12    }
13
14    // ...
15}

iOS Native Apps

Swift

In Mobile SDK 8.0 and later, a SmartStore native Swift extension provides the following soup registration method:

1func createAccountsSoup(name: String) {
2    guard let user = UserAccountManager.shared.currentUserAccount,
3        let store = SmartStore.shared(withName: SmartStore.defaultStoreName, 
4            forUserAccount: user),
5        let  index1 = SoupIndex(path: "Name", indexType: "String", 
6            columnName: "Name"),
7        let  index2 = SoupIndex(path: "Id", indexType: "String", 
8            columnName: "Id")
9    else {
10        return
11    }
12    
13    do {
14        try store.registerSoup(withName: name, withIndices:[index1,index2])
15    } catch (let error) {
16        SalesforceLogger.d(RootViewController.self, 
17            message:"Couldn’t create soup \(name). 
18                Error: \(error.localizedDescription)")
19        return
20    }
21}

Objective-C

1NSString* const kAccountSoupName = @"Account";
2
3...
4- (SFSmartStore *)store
5{
6    return [SFSmartStore sharedStoreWithName:kDefaultSmartStoreName];
7}
8
9...
10- (void)createAccountsSoup {
11    if (![self.store soupExists:kAccountSoupName]) {
12        NSArray *keys = @[@"path", @"type"];
13        NSArray *nameValues = @[@"Name", kSoupIndexTypeString];
14        NSDictionary *nameDictionary = [NSDictionary 
15            dictionaryWithObjects:nameValues forKeys:keys];
16
17        NSArray *idValues = @[@"Id", kSoupIndexTypeString];
18        NSDictionary *idDictionary = 
19            [NSDictionary dictionaryWithObjects:idValues forKeys:keys];
20
21        NSArray *ownerIdValues = @[@"OwnerId", kSoupIndexTypeString];
22        NSDictionary *ownerIdDictionary = 
23            [NSDictionary dictionaryWithObjects:ownerIdValues 
24                forKeys:keys];
25
26        NSArray *accountIndexSpecs = 
27            [SFSoupIndex asArraySoupIndexes:@[nameDictionary, 
28                idDictionary, ownerIdDictionary]];
29
30        NSError* error = nil;
31        [self.store registerSoup:kAccountSoupName 
32                  withIndexSpecs:accountIndexSpecs
33                           error:&error];
34        if (error) {
35            NSLog(@"Cannot create SmartStore soup '%@'\nError: '%@'", 
36                kAccountSoupName, error.localizedDescription);
37        }
38    }
39}