DKDBManager is simple, yet very useful, CRUD manager around Magical Record (a wonderful CoreData wrapper). The current library will implement a logic around it and helps the developer to manage his entities.
Through the implemented CRUD logic you will be able to focus on other things than the classic-repetitivly boring data management.
The main concept is to use JSON dictionaries representing your entities. The logic to create, read or update your entities are done with just one single function. The delete logic has also been improved with a deprecated state.
Extend the NSManagedObject subclasses is required.
The complete documentation is available on CocoaDocs.
The library is explained using Swift code. For an Obj-C example see the sample projects.
DKDBManager is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod "DKDBManager"
and run pod install from the main directory.
To get started, first, import the header file DKDBManager.h in your project's .pch or bridge-header file. This will import in your project all required headers for Magical Record and CoredData`.
#import "DKDBManager.h"
As the DKDBManager is a light wrapper around Magical Record you first need to implement minor methods within your AppDelegate. Afterwhat you still have to generate your model classes and create categories (or extensions in Swift).
First you need to setup the CoreData stack with a specifc file name. Of course you can play with the name to change your database on startup whenever you would like to.
A good practice will be to call this method at the beginning of the application:application didFinishLaunchingWithOptions:launchOptions method of your AppDelegate.
You could also sublclass the DKDBManager and wrap the following in a dedicated class.
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
var didResetDB = self.setupDatabaseWithName("DKDatabaseName.sqlite")
if (didResetDB) {
// The database is fresh new.
// Depending on your needs you might want to do something special right now as:.
// - Setting up some user defaults.
// - Deal with your api/store manager.
// etc.
}
// Starting this point your database is ready to use.
// You can now create any object you could need.
return true
}
func applicationWillTerminate(application: UIApplication) {
DKDBManager.cleanUp()
}
You can configure how the manager will react on execution. Add the following optional lines before calling setupDatabaseWithName::
+ verbose to toggle the log.
DKDBManager.setVerbose(true)
+ allowUpdate to allow the manager to update the entities when parsing new data.
DKDBManager.setAllowUpdate(true)
+ resetStoredEntities to completely reset the database on startup. Instead of removing your app from the simulator just activate this flag and the local DB will be brand new when your app starts.
DKDBManager.setResetStoredEntities(false)
+ needForcedUpdate to force the manager to update the entities during the CRUD process.
DKDBManager.setNeedForcedUpdate(false)
The models configuration is done as in any other projects.
First create and configure your model entities inside the .xcdatamodel file.
Then generate with Xcode the NSManagedObject subclasses as you are used to.
After that, create category files (or extensions in Swift) for each model. The functions and logic will be implemented in those files. If it was done in the generated files, your changes would be removed everytime you generate them again.
Example: DBEntity.swift and DBEntity+DKDBManager.swift
warning If your code is in Swift you can either generate the NSManagedObject subclasses in Swift or Obj-C.
-
Swift: add
@objc(ClassName)before the implementation:@objc(Entity) class Entity: NSManagedObject { @NSManaged var name: NSString? @NSManaged var order: NSNumber? } -
Obj-C: import the class header in the bridge-header file.
#import "Entity.h"
This part explains how to create and configure a single local database that do not need to be updated from an API. In this case there is no need of deprecated entities or automatic updates.
As explained earlier, you first need the data inside a NSDictionary object. This data will get parsed and the library will apply a CRUD logic on it.
In each extented class the following methods are required:
+ primaryPredicateWithDictionary: to create a predicate used in the CRUD process to find the right entity corresponding to the given dictionary.
+ (NSPredicate *)primaryPredicateWithDictionary:(NSDictionary *)dictionary {
// If returns nil then only ONE entity will ever be created and updated.
// If returns a `false predicate` then a new entity will always be created.
// Otherwise the CRUD process use the entity found by the predicate.
return NSPredicate(format: "FALSEPREDICATE");
}
- updateWithDictionary: to update the current entity with a given dictionary.
override public func updateWithDictionary(dictionary: [NSObject : AnyObject]!) {
// Update attributes
self.name = GET_STRING(dictionary, "name")
self.order = GET_NUMBER(dictionary, "order")
}
The following optional ones are also recommended:
- description to improve how the receiving entity is described/logged.
override var description: String {
get {
return "\(self.order) : \(self.name)"
}
}
+ sortingAttributeName to specify a default order for the + all and and + count functions.
override public class func sortingAttributeName() -> String! {
return "order"
}
+ verbose to toggle the log for the receiving class.
override public class func verbose() -> Bool {
return true
}
DKDBManager is used in the following projects:
- WhiteWall
- Pons-SprachKalender
- Pons-Bildwoerterbuch
- ERGO ZahnPlan
- Handhelp
- RezeptBOX
- Huethig
- Digster Music Deals
- Your project here
- Improve documentation
- Add tests
- Add project links
kevindelord, delord.kevin@gmail.com
DKDBManager is available under the MIT license. See the LICENSE file for more info.