Mantle v2.0 Release Notes
-
🚀 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.
- Explicit JSON key paths
- Predefined transformers now part of JSON adapter
- Core Data adapter now separate
- Managed object transformers reversed
- OS X 10.9 and iOS 8
- JSON key paths can only traverse objects
- MTLModel protocol
- Error handling for value transformers
- Storage behaviors for properties
- Type checking during JSON parsing
- 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:]
0️⃣ 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 toMTLJSONAdapter
.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 theMTLModel
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 aMTLModel
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 anyNSValueTransformer
.⚡️
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 0️⃣ default behavior of methods like-dictionaryValue
,-isEqual:
,-description
, and-copy
all at once.0️⃣ Properties which have been omitted from
+propertyKeys
by default will continue 0️⃣ to be omitted under the new API, with a default behavior ofMTLPropertyStorageNone
.📜 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 aBOOL
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 anNSString
.0️⃣ 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.