Permalink
Browse files

Lots of updates to the documentation from the wiki (and some new cont…

…ent, too)
  • Loading branch information...
1 parent 12b98e3 commit 0c35d9f81d518edd17d79a7f7a3eb5573477ea9d @tonyarnold tonyarnold committed Nov 1, 2014
View
@@ -1,5 +1,5 @@
additional_guides:
- - https://github.com/magicalpanda/MagicalRecord/wiki/Installation
+ - https://github.com/magicalpanda/MagicalRecord/wiki/Installing-MagicalRecord
- https://github.com/magicalpanda/MagicalRecord/wiki/Getting-Started
- https://github.com/magicalpanda/MagicalRecord/wiki/Working-with-Managed-Object-Contexts
- https://github.com/magicalpanda/MagicalRecord/wiki/Creating-Entities
View
@@ -22,4 +22,4 @@ Fork this repository, make some great changes (preferably in a branch named for
All code contributions should match our [coding conventions](/magicalpanda/MagicalRecord/wiki/Coding-Conventions).
-Thanks for reading the guidelines!
+Thanks for reading the guidelines!
@@ -0,0 +1,13 @@
+# Creating Entities
+
+To create and insert a new instance of an Entity in the default context, you can use:
+
+```objective-c
+Person *myPerson = [Person MR_createEntity];
+```
+
+To create and insert an entity into specific context:
+
+```objective-c
+Person *myPerson = [Person MR_createEntityInContext:otherContext];
+```
@@ -1,30 +0,0 @@
-### Default Managed Object Context
-
-When working with Core Data, you will regularly deal with two main objects: `NSManagedObject` and `NSManagedObjectContext`.
-
-MagicalRecord provides a simple class method to retrieve a default `NSManagedObjectContext` that can be used throughout your app. This context operates on the main thread, and is great for simple, single-threaded apps.
-
-To access the default context, call:
-
-```objective-c
-NSManagedObjectContext *defaultContext = [NSManagedObjectContext MR_defaultContext];
-```
-
-This context will be used throughout MagicalRecord in any method that uses a context, but does not provde a specific managed object context parameter.
-
-If you need to create a new managed object context for use in non-main threads, use the following method:
-
-```objective-c
-NSManagedObjectContext *myNewContext = [NSManagedObjectContext MR_newContext];
-```
-
-This will create a new managed object context which has the same object model and persistent store as the default context, but is safe for use on another thread. It automatically sets the default context as it's parent context.
-
-If you'd like to make your `myNewContext` instance the default for all fetch requests, use the following class method:
-
-```objective-c
-[NSManagedObjectContext MR_setDefaultContext:myNewContext];
-```
-
-> **NOTE:** It is *highly* recommended that the default context is created and set on the main thread using a managed object context with a concurrency type of `NSMainQueueConcurrencyType`.
-
@@ -0,0 +1,25 @@
+# Deleting Entities
+
+To delete a single entity in the default context:
+
+```objective-c
+[myPerson MR_deleteEntity];
+```
+
+To delete the entity from a specific context:
+
+```objective-c
+[myPerson MR_deleteEntityInContext:otherContext];
+```
+
+To truncate all entities from the default context:
+
+```objective-c
+[Person MR_truncateAll];
+```
+
+To truncate all entities in a specific context:
+
+```objective-c
+[Person MR_truncateAllInContext:otherContext];
+```
@@ -0,0 +1,131 @@
+# Fetching Entities
+
+> This document is being revised for MagicalRecord 2.3.0, and may contain information that is out of date. Please refer to the MagicalRecord's headers if anything here doesn't make sense.
+
+#### Basic Finding
+
+Most methods in MagicalRecord return an `NSArray` of results.
+
+As an example, if you have an entity named *Person* related to a *Department* entity (as seen in many examples throughout [Apple's Core Data documentation)[https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/CoreData/), you can retrieve all of the *Person* entities from your persistent store using the following method:
+
+```objective-c
+NSArray *people = [Person MR_findAll];
+```
+
+To return the same entities sorted by a specific attribute:
+
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName"
+ ascending:YES];
+```
+
+To return the entities sorted by multiple attributes:
+
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName"
+ ascending:YES];
+```
+
+To return the results sorted by multiple attributes with different values. If you don't provide a value for any attribute, it will default to whatever you've set in your model:
+
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName:NO,FirstName"
+ ascending:YES];
+
+// OR
+
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName:YES"
+ ascending:NO];
+```
+
+If you have a unique way of retrieving a single object from your data store (such as an identifier attribute), you can use the following method:
+
+```objective-c
+Person *person = [Person MR_findFirstByAttribute:@"FirstName"
+ withValue:@"Forrest"];
+```
+
+#### Advanced Finding
+
+If you want to be more specific with your search, you can use a predicate:
+
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", @[dept1, dept2]];
+NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```
+
+#### Returning an NSFetchRequest
+
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
+NSFetchRequest *people = [Person MR_requestAllWithPredicate:peopleFilter];
+```
+
+For each of these single line calls, an `NSFetchRequest` and `NSSortDescriptor`s for any sorting criteria are created.
+
+#### Customizing the Request
+
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
+
+NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];
+[peopleRequest setReturnsDistinctResults:NO];
+[peopleRequest setReturnPropertiesNamed:@[@"FirstName", @"LastName"]];
+
+NSArray *people = [Person MR_executeFetchRequest:peopleRequest];
+```
+
+#### Find the number of entities
+
+You can also perform a count of all entities of a specific type in your persistent store:
+
+```objective-c
+NSNumber *count = [Person MR_numberOfEntities];
+```
+
+Or, if you're looking for a count of entities based on a predicate or some filter:
+
+```objective-c
+NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];
+```
+
+There are also complementary methods which return `NSUInteger` rather than `NSNumber` instances:
+
+```objective-c
++ (NSUInteger) MR_countOfEntities;
++ (NSUInteger) MR_countOfEntitiesWithContext:(NSManagedObjectContext *)context;
++ (NSUInteger) MR_countOfEntitiesWithPredicate:(NSPredicate *)searchFilter;
++ (NSUInteger) MR_countOfEntitiesWithPredicate:(NSPredicate *)searchFilter
+ inContext:(NSManagedObjectContext *)context;
+```
+
+#### Aggregate Operations
+
+```objective-c
+NSNumber *totalCalories = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:"
+ onAttribute:@"calories"
+ withPredicate:predicate];
+
+NSNumber *mostCalories = [CTFoodDiaryEntry MR_aggregateOperation:@"max:"
+ onAttribute:@"calories"
+ withPredicate:predicate];
+
+NSArray *caloriesByMonth = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:"
+ onAttribute:@"calories"
+ withPredicate:predicate
+ groupBy:@"month"];
+```
+
+#### Finding entities in a specific context
+
+All find, fetch, and request methods have an `inContext:` method parameter that allows you to specify which managed object context you'd like to query:
+
+```objective-c
+NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];
+
+Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName"
+ withValue:@"Gump"
+ inContext:someOtherContext];
+
+NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];
+```
View
@@ -1,150 +0,0 @@
-### Fetching
-
-#### Basic Finding
-
-Most methods in MagicalRecord return an `NSArray` of results.
-
-Say you have an Entity called "Person", related to a Department (as seen in various Apple Core Data documentation). To get all of the Person entities from your Persistent Store, use the following method:
-
-```objective-c
-NSArray *people = [Person MR_findAll];
-```
-
-Or, to return the results sorted by a property:
-
-```objective-c
-NSArray *peopleSorted = [Person MR_findAllSortedBy:@"lastName" ascending:YES];
-```
-
-Or, to return the results sorted by multiple properties:
-
-```objective-c
-NSArray *peopleSorted = [Person MR_findAllSortedBy:@"lastName,firstName" ascending:YES];
-```
-
-Or, to return the results sorted by multiple properties with different attributes (these will default to whatever you set them to):
-
-```objective-c
-NSArray *peopleSorted = [Person MR_findAllSortedBy:@"lastName:NO,firstName" ascending:YES];
-
-// OR
-
-NSArray *peopleSorted = [Person MR_findAllSortedBy:@"lastName,firstName:YES" ascending:NO];
-```
-
-If you have a unique way of retrieving a single object from your data store (such as via an identifier), you can use the following method:
-
-```objective-c
-Person *person = [Person MR_findFirstByAttribute:@"firstName" withValue:@"Forrest"];
-```
-
-#### Advanced Finding
-
-If you want to be more specific with your search, you can send in a predicate:
-
-```objective-c
-NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"department IN %@", @[dept1, dept2]];
-NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
-```
-
-#### Returning an NSFetchRequest
-
-```objective-c
-NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"department IN %@", departments];
-NSFetchRequest *people = [Person MR_requestAllWithPredicate:peopleFilter];
-```
-
-For each of these single line calls, the full stack of NSFetchRequest, NSSortDescriptors and a simple default error handling scheme (ie. logging to the console) is created.
-
-#### Customizing the Request
-
-```objective-c
-NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"department IN %@", departments];
-
-NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];
-[peopleRequest setReturnsDistinctResults:NO];
-[peopleRequest setReturnPropertiesNamed:@[@"firstName", @"lastName"]];
-
-NSArray *people = [Person MR_executeFetchRequest:peopleRequest];
-```
-
-#### Find the number of entities
-
-You can also perform a count of all entities of a specific type in your Persistent Store:
-
-```objective-c
-NSNumber *count = [Person MR_numberOfEntities];
-```
-
-Or, if you're looking for a count of entities based on a predicate or some filter:
-
-```objective-c
-NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];
-```
-
-There are also complementary methods which return `NSUInteger` rather than `NSNumber` instances:
-
-* `MR_countOfEntities`
-* `MR_countOfEntitiesWithContext:(NSManagedObjectContext *)context`
-* `MR_countOfEntitiesWithPredicate:(NSPredicate *)predicate`
-* `MR_countOfEntitiesWithPredicate:(NSPredicate *)predicatecontext inContext:(NSManagedObjectContext *)`
-
-#### Aggregate Operations
-
-```objective-c
-NSInteger totalFat = [[CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"fatCalories" withPredicate:predicate] integerValue];
-NSInteger fattest = [[CTFoodDiaryEntry MR_aggregateOperation:@"max:" onAttribute:@"fatCalories" withPredicate:predicate] integerValue];
-NSArray *caloriesByMonth = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"fatCalories" withPredicate:predicate groupBy:@"month"];
-```
-
-#### Finding from a different context
-
-All find, fetch, and request methods have an inContext: method parameter
-
-```objective-c
-NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];
-
-Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName" withValue:@"Gump" inContext:someOtherContext];
-
-NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];
-```
-
-## Creating new Entities
-
-When you need to create a new instance of an Entity, use:
-
-```objective-c
-Person *myPerson = [Person MR_createEntity];
-```
-
-or, to specify which context the entity is inserted into:
-
-```objective-c
-Person *myPerson = [Person MR_createInContext:otherContext];
-```
-
-## Deleting Entities
-
-To delete a single entity:
-
-```objective-c
-[myPerson MR_deleteEntity];
-```
-
-or, to delete the entity from a specific context:
-
-```objective-c
-[myPerson MR_deleteInContext:otherContext];
-```
-
-There is no delete *All Entities* or *truncate* operation in core data, so one is provided for you with Active Record for Core Data:
-
-```objective-c
-[Person MR_truncateAll];
-```
-
-or, to truncate all entities in a specific context:
-
-```objective-c
-[Person MR_truncateAllInContext:otherContext];
-```
@@ -1,9 +1,20 @@
# Getting Started
-## Setting up the Core Data Stack
+To get started, import the `MagicalRecord.h` header file in your project's pch file. This will allow a global include of all the required headers.
-To get started, first, import the header file *CoreData+MagicalRecord.h* in your project's pch file. This will allow a global include of all the required headers.
-Next, somewhere in your app delegate, in either the applicationDidFinishLaunching:(UIApplication \*) withOptions:(NSDictionary \*) method, or awakeFromNib, use **one** of the following setup calls with the **MagicalRecord** class:
+If you're using CocoaPods or MagicalRecord.framework, your import should look like:
+
+```objective-c
+#import <MagicalRecord/MagicalRecord.h>
+```
+
+Otherwise, if you've added MagicalRecord's source files directly to your project, your import should be:
+
+```objective-c
+#import "MagicalRecord.h"
+```
+
+Next, somewhere in your app delegate, in either the `- applicationDidFinishLaunching: withOptions:` method, or `-awakeFromNib`, use **one** of the following setup calls with the **MagicalRecord** class:
```objective-c
+ (void)setupCoreDataStack;
Oops, something went wrong.

0 comments on commit 0c35d9f

Please sign in to comment.