2.0

This release of Mantle contains major breaking changes that we were unable to make after freezing the 1.0 API.

The changes in 2.0 focus on simplifying concepts and increasing flexibility in the framework.

For a complete list of the changes made in Mantle 2.0, see the milestone.

Breaking changes

1. Explicit JSON key paths
2. Predefined transformers now part of JSON adapter
3. Core Data adapter now separate
4. Managed object transformers reversed
5. OS X 10.9 and iOS 8
6. JSON key paths can only traverse objects

Additions and improvements

1. MTLModel protocol
2. Error handling for value transformers
3. Storage behaviors for properties
4. Type checking during JSON parsing
5. Mapping multiple JSON fields to a single property

Breaking changes

Explicit JSON key paths

+JSONKeyPathsByPropertyKey will no longer infer your property mappings automatically.

Instead, you must explicitly specify every property that should be mapped, and any properties omitted will not be considered for JSON serialization or deserialization.

For convenience, you can use +[NSDictionary mtl_identityPropertyMapWithModel:] to automatically create a one-to-one mapping that matches the previous default behavior.

To update:

• Explicitly declare any property mappings in +JSONKeyPathsByPropertyKey that were previously implicit.
• Optionally use +[NSDictionary mtl_identityPropertyMapWithModel:] for an initial property map.

Predefined transformers now part of JSON adapter

The +mtl_JSONDictionaryTransformerWithModelClass: and +mtl_JSONArrayWithModelClass: methods have moved to MTLJSONAdapter.

This allows custom JSON adapter subclasses to substitute their own transformers with additional logic, and moves the transformers closer to their actual point of use.

To update:

• Replace occurrences of +[NSValueTransformer mtl_JSONDictionaryTransformerWithModelClass:] with +[MTLJSONAdapter dictionaryTransformerWithModelClass:]
• Replace occurrences of +[NSValueTransformer mtl_JSONArrayTransformerWithModelClass:] with +[MTLJSONAdapter arrayTransformerWithModelClass:]

Core Data adapter now separate

The MTLManagedObjectAdapter class, used for converting to and from Core Data objects, has been moved to its own framework. This better indicates its “semi-official” status, as it gets less attention than the core Mantle features.

To update:

• Import the MTLManagedObjectAdapter framework into your project.

Managed object transformers reversed

In addition to being a separate framework, the behavior of MTLManagedObjectAdapter has changed as well—specifically, the direction of managed object attribute transformers has been flipped.

Managed object transformers now convert from managed object attributes to model properties in the forward direction. In the reverse direction, they convert from properties to managed object attributes.

To update:

• Swap the forward and reverse transformation logic of any custom managed object transformers, or use -mtl_invertedTransformer to do it automatically.

OS X 10.9 and iOS 8

Mantle now requires OS X 10.9+ or iOS 8+, for the use of Swift and dynamic frameworks.

To update:

• Increase your project’s deployment target to at least OS X 10.9 or iOS 8.

JSON key paths can only traverse objects

Every element of a JSON key path specified in +JSONKeyPathsByPropertyKey must now refer to an object (dictionary).

It was previously possible to use an array as a key path element, but this was unintended behavior, and is now explicitly disallowed.

To update:

• If you were using an array as an element in a key path, change the key path to end at the array, and update your JSON transformer to handle the nested elements instead.

Additions and improvements

MTLModel protocol

The new <MTLModel> protocol represents the basic behaviors expected from any model object, and can be used instead of the MTLModel class when inheritance is impossible, or to create more generic APIs.

For example, <MTLModel> conformance can be added to the objects from other persistence frameworks in order to use those objects in conjunction with Mantle’s adapters.

Accordingly, MTLJSONAdapter has been updated to only depend on <MTLModel> conformance, and no longer requires a MTLModel subclass in order to serialize or deserialize from JSON.

Error handling for value transformers

The new <MTLTransformerErrorHandling> protocol can be used to add error reporting behaviors to any NSValueTransformer.

MTLValueTransformer has been updated to take advantage of the new interface, with the following new methods that provide error information:

• +transformerUsingForwardBlock:
• +transformerUsingReversibleBlock:
• +transformerUsingForwardBlock:reverseBlock:

Similarly, the predefined transformers that Mantle provides now provide error information upon failure as well.

Storage behaviors for properties

The new +storageBehaviorForPropertyWithKey: method can be used to redefine the default behavior of methods like -dictionaryValue, -isEqual:, -description, and -copy all at once.

Properties which have been omitted from +propertyKeys by default will continue to be omitted under the new API, with a default behavior of MTLPropertyStorageNone.

Type checking during JSON parsing

MTLJSONAdapter now implicitly validates the type of values assigned to your <MTLModel> objects during JSON parsing.

This can be prevent errors like an NSString being assigned to a BOOL property.

This is only a simple safety check, though, and cannot catch every kind of error! Continue to verify that your types align ahead of time.

Mapping multiple JSON fields to a single property

MTLJSONAdapter can now map multiple fields to a single property, and vice-versa. Specify an array of keypaths for the property when implementing +JSONKeyPathsByPropertyKey rather than an NSString.

The default behaviour is to set the property to a dictionary of values for the specified keypaths. If you specify a value transformer for the given property key, this transformer will receive an NSDictionary of values.