SimpleSample-customObjects-ios

Ask tech team
From QuickBlox Developers (API docs, code samples, SDK)
Jump to: navigation, search

Contents

Sources

Project homepage on GIT — https://github.com/QuickBlox/quickblox-ios-sdk/tree/master/sample-custom-objects

Download ZIP - https://github.com/QuickBlox/quickblox-ios-sdk/archive/master.zip


Overview

This sample demonstrates how to work with Custom Objects QuickBlox API.
It allows you to create any server side data structure, use it as you want, create any logic and a lot of other custom features.

It shows how to:

  1. Create your own server data structure & use it. In our example we created a data structure, that represents a simple Note.
  2. Get, Create, Update and Delete your data using a lot of filters.




Guide: Getting Started with Custom Objects API

Getting a QuickBlox account

http://admin.quickblox.com/register

Creating applications on the Admin panel

http://admin.quickblox.com/apps/new

In addition we have this useful 5 minute guide.

Connecting QuickBlox to your application

To get the information on how to connect to the QuickBlox.framework, please, refer to the IOS-how-to-connect-Quickblox-framework page.

Adding a Custom Data structure to your application

Note: This guide based on Custom Objects REST API documentation. It is very helpful, describes the full list of QuickBlox Custom Objects API features and need to be read in addition to reading this guide.

To start using the Custom Objects module you should create your data scheme. Go to admin.quickblox.com, find the Custom Objects module page and press the Add new class button. The 'add new class' popup will then appear.

Enter the Class name, add any fields you want. It allows 5 types of fields:

  • Integer
  • Float
  • Boolean (true/false)
  • String
  • Array (of Integers, Floats, Booleans, Strings)

COCreateClass.png

Press the Create class button and a new class will be created

COPredefinedFields.png

There are some predefined fields, that are described in this Custom Objects REST API Module description documentation.


Creating a record

There are 2 ways to create a record:

  • through the Admin panel
  • using the iOS SDK


Creating records through Admin panel

Just go to admin.quickblox.com, find the Custom Objects module page and press the Add record button. The 'add new record' popup will then appear. Fill in any fields you want and press the Add record button again. The new record will then be added & shown in the table.


Creating a record using the iOS SDK

In order to create records you must be logged in and to act on a user's behalf - please refer to iOS Users API documentation.

To create a record just use the code below:

QBCOCustomObject *object = [QBCOCustomObject customObject];
object.className = @"Movie"; // your Class name
 
// Object fields
[object.fields setObject:@"Star Wars" forKey:@"name"];
[object.fields setObject:[NSNumber numberWithFloat:9.1f] forKey:@"rating"];
[object.fields setObject:[NSNumber numberWithBool:NO] forKey:@"documentary"];
[object.fields setObject:@"fantasy" forKey:@"genre"];
[object.fields setObject:@"Star Wars is an American epic space opera franchise consisting of a film series created by George Lucas." forKey:@"descriptions"];
 
[QBCustomObjects createObject:object delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Create record result
    if(result.success && [result isKindOfClass:QBCOCustomObjectResult.class]){        
        QBCOCustomObjectResult *createObjectResult = (QBCOCustomObjectResult *)result;
         NSLog(@"Created object: %@", createObjectResult.object);        
    }else{
        NSLog(@"errors=%@", result.errors);
    }
}


Retrieving records

By ID

To retrieve a record by id:

[QBCustomObjects objectWithClassName:@"Note" ID:@"51c9ab92535c12951b0032d6" delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Get objects result
    if(result.success && [result isKindOfClass:QBCOCustomObjectResult.class]){
       QBCOCustomObjectResult *objectResult = (QBCOCustomObjectResult *)result;
       NSLog(@"Object: %@", objectResult.object);
    }else{
       NSLog(@"errors=%@", result.errors);
    }
}


By IDs

To retrieve records by ids:

[QBCustomObjects objectsWithClassName:@"Note" IDs:@[@"51c9aafe535c127d98004a13",@"51c9aafe535c127d98004a14", @"51c9aafe535c127d98004a16"] delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Get objects result
    if(result.success && [result isKindOfClass:QBCOCustomObjectPagedResult.class]){
       QBCOCustomObjectPagedResult *getObjectsResult = (QBCOCustomObjectPagedResult *)result;
       NSLog(@"Objects: %@, count: %d", getObjectsResult.objects, getObjectsResult.count);
    }else{
       NSLog(@"errors=%@", result.errors);
    }
}


Using operators

There are lots of operators that you can use to retrieve records:

  • Retrieve records using search operators by your class fields
  • Sort operators
  • 'Pagination' operators
  • Aggregation operators

Please refer to this Custom Objects REST API Retrieve records documentation. All these operators & parameters can also be used in your code.

For example, if we want to retrieve 5 movies that:

  • Have a rating > 5.5
  • Are not documentaries.
  • Must be sorted by the rating field in ascending order.
NSMutableDictionary *getRequest = [NSMutableDictionary dictionary];
[getRequest setObject:@"5.5" forKey:@"rating[gt]"];
[getRequest setObject:@"5" forKey:@"limit"];
[getRequest setObject:[NSNumber numberWithBool:NO] forKey:@"documentary"];
[getRequest setObject:@"rating" forKey:@"sort_asc"];
 
[QBCustomObjects objectsWithClassName:@"Movie" extendedRequest:getRequest delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Get objects result
    if(result.success && [result isKindOfClass:QBCOCustomObjectPagedResult.class]){
       QBCOCustomObjectPagedResult *getObjectsResult = (QBCOCustomObjectPagedResult *)result;
       NSLog(@"Objects: %@, count: %d", getObjectsResult.objects, getObjectsResult.count);
    }else{
       NSLog(@"errors=%@", result.errors);
    }
}

Updating records

To update an existing record you should know the record's ID. Let's update Movie with ID of 502f7c4036c9ae2163000002 - and set rating to 7.88:

QBCOCustomObject *object = [QBCOCustomObject customObject];
object.className = @"Movie";
[object.fields setObject:@"7.88" forKey:@"rating"];
object.ID = @"502f7c4036c9ae2163000002";
 
[QBCustomObjects updateObject:object delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Update object result
    if(result.success && [result isKindOfClass:QBCOCustomObjectResult.class]){       
        QBCOCustomObjectResult *updateObjectResult = (QBCOCustomObjectResult *)result;
        NSLog(@"Object: %@", updateObjectResult.object);        
    }else{
        NSLog(@"errors=%@", result.errors);
    }
}

Also there are these Special update operators, that are very helpful for some purposes - updating Array fields etc.

Deleting records

To delete existing records you should know the record's ID. Let's delete a Movie with the ID 502f83ed36c9aefa62000002:

NSString *ID = @"502f83ed36c9aefa62000002";
NSString *className = @"Movie";
 
[QBCustomObjects deleteObjectWithID:ID className:className delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Delete object result
    if(result.success && [result isKindOfClass:QBCOCustomObjectResult.class]){       
        NSLog(@"Object was deleted successfully");        
    }else{
        NSLog(@"errors=%@", result.errors);
    }
}

Operations on multiple objects

Is it possible to perform some operations on multiple objects in a single query.


Creating multiple records

Creating multiple records in a single query:

QBCOCustomObject *object1 = [QBCOCustomObject customObject];
[object1.fields setObject:@"2049124" forKey:@"rating"];
//
QBCOCustomObject *object2 = [QBCOCustomObject customObject];
[object2.fields setObject:@"12" forKey:@"rating"];
 
[QBCustomObjects createObjects:@[object1, object2] className:@"Movie" delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // success result
    if(result.success && [result isKindOfClass:QBCOCustomObjectPagedResult.class]){
        QBCOCustomObjectPagedResult *res = (QBCOCustomObjectPagedResult *)result;
        NSLog(@"QBCOCustomObjectPagedResult, objects=%@", res.objects);
    }
}


Updating multiple records

Update multipling records in a single query:

QBCOCustomObject *object1 = [QBCOCustomObject customObject];
object1.ID = @"5228ad042195be5d8d41bd99";
[object1.fields setObject:@"101" forKey:@"rating"];
//
QBCOCustomObject *object2 = [QBCOCustomObject customObject];
object2.ID = @"5228ad042195be5d8d41bd9a";
[object2.fields setObject:@"201" forKey:@"rating"];
//
QBCOCustomObject *object3 = [QBCOCustomObject customObject];
object3.ID = @"5228ad042195be5d8d41bd9a33";
[object3.fields setObject:@"31" forKey:@"rating"];
 
[QBCustomObjects updateObjects:@[object1, object2, object3] className:@"SuperSample" delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // success result
    if(result.success && [result isKindOfClass:QBCOCustomObjectPagedResult.class]){
        QBCOCustomObjectPagedResult *res = (QBCOCustomObjectPagedResult *)result;
        NSLog(@"QBCOCustomObjectPagedResult, objects=%@", res.objects);
    }
}


Deleting multiple records

Deleting multiple records in a single query:

NSArray *IDs = @[@"51c9aafe535c127d98004a15", @"51c9ab92535c12951b0032d6", @"51c9ab92535c12951b0032da", @"51c9ab92535c12951b0032de", @"52283b38535c12fa32010efd"];
 
NSString *className = @"Movie";
 
[QBCustomObjects deleteObjectsWithIDs:IDs className:className delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // success result
    if(result.success && [result isKindOfClass:QBCOMultiDeleteResult.class]){
        QBCOMultiDeleteResult *res = (QBCOMultiDeleteResult *)result;
        NSLog(@"QBCOMultiDeleteResult, deletedObjectsIDs: %@, notFoundObjectsIDs: %@, wrongPermissionsObjectsIDs: %@",
                  res.deletedObjectsIDs, res.notFoundObjectsIDs, res.wrongPermissionsObjectsIDs);
 
    }
}

Relations

We can allow relations between 2 objects to be organized - just use the special field _parent_id.

For example, if you want to add Comments to a movie - you can use this code snippet below:

QBCOCustomObject *object = [QBCOCustomObject customObject];
object.className = @"Comment"; // your Class name
 
// Object fields
[object.fields setObject:@"The first film in the series was originally released on May 25, 1977, under the title Star Wars, by 20th Century Fox" forKey:@"text"];
[object.fields setObject:@"50aa4d8fefa357fa14000001" forKey:@"_parent_id"]; // Movie ID
 
[QBCustomObjects createObject:object delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Create record result
    if(result.success && [result isKindOfClass:QBCOCustomObjectResult.class]){        
        QBCOCustomObjectResult *createObjectResult = (QBCOCustomObjectResult *)result;
         NSLog(@"Created object: %@", createObjectResult.object);        
    }else{
        NSLog(@"errors=%@", result.errors);
    }
}


This is a strong reference - it means that if you delete parent record (Movie) - all the child records (Comments) will be deleted too. This field (_parent_id) may be included in Retrieve/Create/Update queries as well.

Permissions

A Permission (access control list) is a list of permissions attached to a record in the Custom Objects module. This list specifies which users are granted access to records, as well as what operations are allowed on given objects (READ,CREATE,UPDATE,DELETE).

Each entry in a typical Permissions specifies a subject and an operation. For instance, if a record has a permission that contains (Garry, EDIT), this would give Garry permission to edit this record.

Read Permissions REST API description to better understand how it works

There are 4 typical operations on record:

  • CREATE
  • READ
  • UPDATE
  • DELETE

CREATE operations can't be set through API (only in Admin panel)

Each operation has information on who can perform it on object.

There are 5 values (enum QBCOPermissionsAccess):

  • QBCOPermissionsAccessOpen - any user can perform operation on this record
  • QBCOPermissionsAccessOwner - only owner can perform operation on this record
  • QBCOPermissionsAccessNotAllowed - nobody can perform operation on this record (except Owner)
  • QBCOPermissionsAccessOpenForUsersIDs - users with these IDs can perform operation on this record
  • QBCOPermissionsAccessOpenForGroups - users in these groups can perform operation on this record

Note: Owners always have access to their own records (except for any case where Class permissions level is enabled)


Creating records with Permissions

Let's create a record with the following permissions:

  • READ: Open
  • UPDATE: Users in groups golf, man
  • DELETE: Users with IDs 3060, 63635
QBCOCustomObject *object = [QBCOCustomObject customObject];
object.className = @"Movie"; // your Class name
 
// Object fields
[object.fields setObject:@"Star Wars" forKey:@"name"];
[object.fields setObject:@"fantasy" forKey:@"genre"];
 
// permissions
QBCOPermissions *permissions = [QBCOPermissions permissions];
// READ
//
permissions.readAccess = QBCOPermissionsAccessOpen;
// UPDATE
//
permissions.updateAccess = QBCOPermissionsAccessOpenForGroups;
permissions.usersGroupsForUpdateAccess = @[@"golf", @"man"];
// DELETE
//
permissions.deleteAccess = QBCOPermissionsAccessOpenForUsersIDs;
permissions.usersIDsForDeleteAccess = @[@3060, @63635];
 
object.permissions = permissions;
 
[QBCustomObjects createObject:object delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Create record result
    if(result.success && [result isKindOfClass:QBCOCustomObjectResult.class]){        
        QBCOCustomObjectResult *createObjectResult = (QBCOCustomObjectResult *)result;
         NSLog(@"Created object: %@", createObjectResult.object);        
    }else{
        NSLog(@"errors=%@", result.errors);
    }
}


Obtaining a record's Permissions

You can obtain info about record permissions by looking at it's ID - Individual users are restricted to information on their own records:

 [QBCustomObjects permissionsForObjectWithClassName:@"SuperSample" ID:@"51c9aafe535c127d98004a13" delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    if(result.success && [result isKindOfClass:QBCOPermissionsResult.class]){        
        QBCOPermissionsResult *res = (QBCOPermissionsResult *)result;
        NSLog(@"QBCOPermissionsResult, permissions=%@", res.permissions);       
    }else{
        NSLog(@"errors=%@", result.errors);
    }
}


Updating a record's Permissions

Let's update a record's permissions to the following:

  • READ: Users in groups car, developers
  • UPDATE: Owner
  • DELETE: Owner
QBCOCustomObject *object = [QBCOCustomObject customObject];
object.className = @"Movie"; // your Class name
 
// permissions
QBCOPermissions *permissions = [QBCOPermissions permissions];
// READ
//
permissions.readAccess = QBCOPermissionsAccessOpenForGroups;
permissions.usersGroupsForUpdateAccess = @[@"car", @"developers"];
// UPDATE
//
permissions.updateAccess = QBCOPermissionsAccessOwner;
// DELETE
//
permissions.deleteAccess = QBCOPermissionsAccessOwner;
 
object.permissions = permissions;
 
[QBCustomObjects updateObject:object specialUpdateOperators:nil delegate:self];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    // Create record result
    if(result.success && [result isKindOfClass:QBCOCustomObjectResult.class]){        
        QBCOCustomObjectResult *createObjectResult = (QBCOCustomObjectResult *)result;
         NSLog(@"Updated object: %@", createObjectResult.object);        
    }else{
        NSLog(@"errors=%@", result.errors);
    }
}

Files

Custom Objects module supports the ‘File’ field type. It is created to easily work with content from Custom Objects module. There is an ability to upload, download, update and delete content of file fields.

The max file size is 32 MB.

Uploading/Updating a file

QBCOFile *file = [QBCOFile file];
file.name = @"plus";
file.contentType = @"image/png";
file.data = [NSData dataWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"plus" ofType:@"png"]];
 
[QBCustomObjects uploadFile:file className:@"Movie" objectID:@"5256c265535c128020000182" fileFieldName:@"image" delegate:self context:testContext];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    if(result.success){
        // uploaded
    }
}

Downloading a file

[QBCustomObjects downloadFileFromClassName:@"Movie" objectID:@"5256c265535c128020000182" fileFieldName:@"image" delegate:self context:testContext];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    if(result.success && [result isKindOfClass:QBCOFileResult.class]){
        COFileResult *res = (QBCOFileResult *)result;
        NSLog(@"QBCOFileResult, file=%@", res.data);
    }
}

Deleting a file

[QBCustomObjects deleteFileFromClassName:@"Movie" objectID:@"5256c265535c128020000182" fileFieldName:@"image" delegate:self context:testContext];
 
#pragma mark -
#pragma mark QBActionStatusDelegate
 
- (void)completedWithResult:(Result *)result{
    if(result.success){
        // deleted
    }
}

Comments

Feel free to comment on this page using the form below.

blog comments powered by Disqus