DataStore is the Eloquent based ORM (for iOS) that also provides a beautiful, simple ActiveRecord implementation for working with your data storage. Each database table has a corresponding Model which is used to interact with a table by the same name. The Model class allows us to insert new records into the table, query for data in our table, as well as update (and delete from) the table.
More can be found on the Eloquent Model here:
- https://laravel.com/docs/5.2/eloquent#inserting-and-updating-models
- https://laravel.com/api/5.2/Illuminate/Database/Eloquent/Model.html
DataStore is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod "DataStore"You can update any class to implement Model in Objective-C:
@interface Flight : Model
@property (strong, nonatomic) NSString *name;
@property (strong, nonatomic) NSString *destination;
@end
@implementation Flight
@end
Alternatively Model subclasses can be defined in Swift as well:
class Flight : Model {
var name: String?
var destination: String?
}
To create a new record in the database, simply create a new instance of your Model subclass, set the attributes on that model, and then call the save method on your model instance.
- (IBAction)bookFlight {
Flight *flight = [[Flight alloc] init];
flight.name = self.flightNumberLabel.text;
flight.destination = self.flightDestinationLabel.text;
[flight save];
[self.navigationController popViewControllerAnimated:YES];
}
In the example above, we simply assign to the name and destination attributes of the Flight model instance. When we call the save method, a record will be inserted into the database. Alternatively, if you make another change to the Model instance and save it again, it will update the database record instead.
Now that we have seen how to use the save method on a Model, we are ready to start retrieving data from our database.
Next we will query the database table associated with the model for all records, with the all function:
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
NSArray * all = [Flight all];
for (Flight* flight in all) {
...
}
}
In this example, we simply assign the NSArray from the all function of the Flight class. As you can see, with a single function call we can get all the records of a specific database table.
Alternatively, if you want to query a subset you will have to use the advanced branch of the DataStore Framework to get access to the where and orWhere query builder functions and the update, remove, and get companion functions to execute the queries.
In addition to retrieving all of the records for a given table, you can also retrieve a single record. Instead of returning a collection of records like with the all function, the find function returns a single Model instance:
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
Flight *flight = (Flight *)[Flight find:1];
self.flightLabel.text = flight.name;
}
Once you have a Model instance, you can use the column values of the table by accessing the corresponding property. For example, above we get a Flight instance from the find function, and begin accessing the name column from the Flight database table.
You also have access to the count function provided by the Model class. This function returns the appropriate scalar value instead of a full model instance (or collection of instances):
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
NSInteger count = [Flight count];
self.flightCountLabel.text = [NSString stringWithFormat:@"%d Flight(s) Booked", count];
}
In this example, we simply assign the count variable from the Flight model class' count function and report it to the UI component.
To delete a record, call the remove method on a model instance:
- (IBAction)cancelFlight {
Flight *flight = (Flight *)[Flight find:1];
[flight remove];
}
Alternatively, to delete all records from a database table, call the truncate function:
- (IBAction)cancelAllFlights {
[Flight truncate];
}
The Example Project has 3 screens that display basic Model CRUD operations, using the Flight class as an example.
The CRUD operations are completed using the count, truncate, save and all functions.
If you are looking for more than those basic operations, the advanced branch contains a more in depth Laravel Eloquent implementation and Example project.
To run the example project, clone the repo, and run pod install from the Example directory first.
git clone https://github.com/the-mac/data-store-ios.git
cd Example
pod install
This pod uses the FMDB Framework, and is already included in the Example Project's Podfile. For your own project (and Podfile), our DataStore reference could look as follows:
platform :ios, '8.0'
target 'MyApp'
pod 'FMDB'
pod 'DataStore'
Android/iOS Project Manager
Fork the repo, and be the first to add a pull request to our advanced branch.
DataStore is available under the MIT license. See the LICENSE file for more info.