User Guide

###1. Requests are binded to entities

You can simply call

[DrupalEntity pushToServer];         // to post data to server.
[DrupalEntity pullFromServer];       // to pull data from server.
[DrupalEntity deleteFromServer];     // to remove data from server.
[DrupalEntity patchServerData];      // to patch data to server.

###2. Object serialization/deserialization Library automatically serializes/deserializes objects, including attached objects and arrays of objects.

Note: all properties of your DrupalEntity subclass should not be primitives.

Because objective c does not support strongly typed arrays you have to implement method: - (Class)classOfItems:(NSString *)propertyName and return class of objects of array by a property name.

- (Class)classOfItems:(NSString *)propertyName 
{
    if ([propertyName isEqualToString:@"someArrayPropertyName"])
        return [MyDrupalEntity class]; //  Array of MyDrupalEntity objects
    return nil;                        //  Array of not DrupalEntity objects
}

To configure serialized data you can override method - (NSDictionary *)toJSONDictionary of DrupalEntity class and return needed content. This method is called before each not-safe request.

- (NSDictionary *)toJSONDictionary 
{
    // Do custom entity serialization here
}

###3. Responses are not binded to entities only Besides of entity api provides few more handy structures: NSArray, NSDictionary, NSString and NSNumber and can manage drupal and non-drupal entities.

If you need to pull list of objects from server in one request you just should use completion handler (void (^EntityActionHandler)(id result)). To get a list of objects of another DrupalEntity subclass return items' class in - (Class)classOfItems:(NSString *)propertyName method.

For example to pull blog posts by pages we have two classes: BlogPage and BlogPostPreview that are inherited from DrupalEntity (see SampleApp project). BlogPage class has a property NSNumber *page that indicates number of page and overrides method:

- (Class)classOfItems:(NSString *)propertyName {
    return [BlogPostPreview class];
}

Pulling BlogPostPreview objects from server:

BlogPage *bp = [BlogPage new];
bp.page = @(1);
[bp pullFromServer:^(NSArray *result) {
    if (result) {
        //  Do something with an array of BlogPostPreview objects
    }
}];

When server returns a list of objects library calls classOfItems for item's type and deserializes it. If you don't override this method or return nil, library will just use the class of called entity.

###4. DrupalAPIManager Object, containing server base URL and is responsible for server request generation and posting to server. You have to set DrupalAPIManager.baseURL before making action with DrupalEntity instance.

Additional methods that you can use to implement custom workflow:

- (void)getEntity:(DrupalEntity *)entity completeHandler:(CompleteHandler)block;     //  Get entity from server 
- (void)postEntity:(DrupalEntity *)entity completeHandler:(CompleteHandler)block;     //  Post entity to server

typedef void (^CompletionHandler)(id response, NSError *error);

Example:

[[DrupalAPIManager sharedDrupalAPIManager] postEntity:someEntity completeHandler:^(id object, NSError *error) {
    if (error) {
        //    Something went wrong, log error
    } else {
        //    Do something with object
    }
}];

###5. Other details ####ResponseData DrupalEntity object or array of objects (depends on response). ####AFHTTPRequestOperationManager+DrupalLib.h Category extends manager of AFNetworking and is used in DrupalAPIManager. Will be imporoved and extended to support login scheme. ####Transient fields

If field should not be serialized or deserialized override method - (BOOL)isPropertyTransient:(NSString *)propertyName and return YES of transient property by name:

- (BOOL)isPropertyTransient:(NSString *)propertyName
{
    if ([propertyName isEqualToString:@"somePropertyName"])
        return YES;     //  Property is transient and won't be serialized.
    return NO;
}

Note: you can override - (NSDictionary *)toJSONDictionary method and return custom serialized object.