Manual Core Data Migrations – Lessons Learned

So, I’ll try to keep this all brief.  In short, as everyone, including Core Data Ninja Master Marcus Zarra, has said:  Avoid heavy Core Data Migrations!

The tools are buggy, the crash bugs difficult to interpret.  I spent 4-5 hours already just sort of shooting at a black box.   So, I hope to share with you the things I learned and what caught me up.  If this is all too brief or out of context in places, it’s because I’m not a tutorial writer, and keep my blog posts quite often so that I can refer back to them.  So please feel free to write me if you need clarification.

I’ll also give the disclaimer that I’m not the most ‘canonical’ of programmers.  So, these are my findings.  I don’t know if they follow best practices, but I don’t think there are any best practices when it comes to this stuff…. otherwise I probably wouldn’t have made this lengthy blog post!

Scenario

Migration of old data store using an old Core Data model to a new data store with a brand new Core Data model

This documents my personal experience trying to migrate a Data Model I want to retire (i.e. completely separate Core Data Model file) to a brand new data model.

I wanted to move away from my old Objective-C pipeline which involves NSManagedObject subclasses using mogenerator that all have an Objective-C style Namespace and codegen, to a pure Swift version which uses the codegen feature of the Latest Xcode Core Data editor.

I kept these models separate because in a few releases when I know everyone has upgraded, I can eventually just remove the legacy model from the bundle and all the associated classes.

What I learned / experienced:

  • How to set up incremental migrations using a handy little helper from http://www.objc.io
  • How to migrate old data to new using Mapping Models
  • How to write and use custom NSEntityMappingPolicy objects
  • How to use the Mapping Model editor to call functions on these custom policies
  • All the various Pitfalls, Gotchas, and things that Apple really needs to improve on.

Useful Pre-requisite Reading:

How to set up incremental migrations

This is really what you want to do.  It makes your life easy in that you only need to make mapping models for each change to your data model.  There is a lot of code floating around the internet that helps you make an incremental migration manager.  I took one from objc.io and then modified it so it could support my use case where I am migrating a completely different store to a new one, and that new one should have its own URL on disk that may not follow from the original store.

Code for that migration manager can be found in a gist here.  Don’t just copy-paste:  You have to copy-paste into the correct files!  Also, it’s in objective-c so you’ll want to make a bridging header… It’s really not hard.

What is different in my version of MHWMigrationManager than from on objc.io:

  • It has a hack fix for a dubious migration error that has minimal debug help: ‘Mismatch between mapping and source/destination models’
  • It allows you to specify via the delegate a “Final Destination URL” once the Migration has successfully completed.  This can be useful as in my case where I have 2 different Stores and Models and want them to stay that way.

Set up your Core Data Stack

Basically, you start with Apple’s boilerplate code for Core Data and a persistent container, then you modify in a way that I’ve done here.  These 2 gists I’ve provided are all just starting points.  We haven’t even got to the annoying stuff yet.

If you create a brand new data model like I have done, be sure that it uses a different name than your old one.  You can’t rename the old one because you want the new one to have the same nice name.  Leave everything about the old one in place.

Pro Tip:  If you didn’t do this but already did the work of creating this new model version, if you create a new model either via duplication or copy-paste of entities, keep in mind that delete rules are not copied over, NOR are the inverse relationships.  So you’ll have to go through and set these by hand again.

Now Create Mapping Models

You can now proceed to create a mapping model in the ways you’ve probably read about on the internet already.   Pro Tips:

  • Only write your mapping model, once your Core Data Object Model is complete.  If you make a modification to your Core Object Model (.xcdatamodeld), any mappings that reference it will no longer be found by the Migration Manager.
  • Due to the nature of the migration process, you won’t have access to any subclass of NSManagedObject, and so this can make setting up NEW relationships difficult.  It is therefore a good idea to keep ‘foreign keys’ on your models with relationships.  (i.e. you extend your Post model to have an Attachment.  Attachment should have an attribute postId, or something identifiable)
  • If you use a subclass of NSEntityMigrationPolicy and you specify it in the Mapping Model editor, make sure that you also provide the Module name.  So, instead of LegacyToModernPolicy, I would put SongbookSimple.LegacyToModernPolicy, because my app’s module name is SongbookSimple.

Mapping Models are useful in that they allow a lot of customization, and you can sort of elect what you want to be done “automagically” and what you’d like to have more control over.  You get more control over these by using custom subclasses of NSEntityMigrationPolicy.

In general, for property or relationship mappings, the auto-generated functionality can get you pretty far.  Otherwise, when you have specified a custom Policy, you can make method calls on that policy.

When to use custom policy methods

If you have a somewhat strange migration for a specific entity, you can just remove all Attribute mappings in for an Entity Mapping, then in your subclass, override the method below.  The method signature is misleading because you are actually asked to create the equivalent version of the old object in the new object.  So you’re manually specifying how one object “becomes” the new object, and in my case where a Song started to store its data in a separate SongData object, you have to create this SongData object and find a way to link the two (i.e. songFilename) because you create the actual relationships later.  EDIT:  What I’ve learned however is that ideally this createDestinationInstances(…) method should really be about 1:1 mapping.  If your migration ends up taking one object and splitting it into two, you should write to Policy Subclasses and have 2 Entity Mappings:  i.e OldSong -> Song and OldSong -> SongData, then in the 2nd pass of the migration where the relationships are re-established, that’s where you can associate them again.

    override func createDestinationInstances(forSource sInstance: NSManagedObject, in mapping: NSEntityMapping, manager: NSMigrationManager) throws {
        
        let dInstance = NSEntityDescription.insertNewObject(forEntityName: mapping.destinationEntityName!, into: manager.destinationContext)
        
        let text = sInstance.value(forKey: "text") as! String?
        
        dInstance.setValue(sInstance.value(forKey: "lastModified"), forKey: #keyPath(Song.createdAt))
        dInstance.setValue(sInstance.value(forKey: "lastModified"), forKey: #keyPath(Song.updatedAt))
        dInstance.setValue("txt",                                   forKey: #keyPath(Song.fileExtension))
        dInstance.setValue(sInstance.value(forKey: "filename"), forKey: #keyPath(Song.filename))
        dInstance.setValue(sInstance.value(forKey: "firstLetterUppercase"), forKey: #keyPath(Song.firstLetterUppercase))
        dInstance.setValue(sInstance.value(forKey: "name"), forKey: #keyPath(Song.title))
        dInstance.setValue(sInstance.value(forKey: "oldFilename"), forKey: #keyPath(Song.oldFilename))
        dInstance.setValue(self.songDataLengthOfText(text), forKey: #keyPath(Song.songDataLength))
        dInstance.setValue(text, forKey: #keyPath(Song.text))
        dInstance.setValue(SongDataType.plainText.rawValue, forKey: #keyPath(Song.typeRaw))
        dInstance.setValue(nil, forKey: #keyPath(Song.userInfoData))
        
        // NOTE: DON'T DO THIS.  Set up a OldSong -> SongData entity mapping!
        // Then fetch this instance later via its songFilename
        //let songData = NSEntityDescription.insertNewObject(forEntityName: SongData.entity().name!, into: manager.destinationContext)
        //songData.setValue(sInstance.value(forKey: "filename"), forKey: #keyPath(SongData.songFilename))
        //let structure = SongDataStructure()
        //structure.set(text: text)
        //songData.setValue(structure.serialize(), forKey: #keyPath(SongData.nsdata))
        
        // NOTE: DON'T DO THIS.  Set up a OldSong -> SongViewPreferences entity mapping!
        //let viewPreferences = NSEntityDescription.insertNewObject(forEntityName: SongViewPreferences.entity().name!, into: manager.destinationContext)
        //viewPreferences.setValue(sInstance.value(forKey: "filename"), forKey: #keyPath(SongViewPreferences.songFilename))
        
        manager.associate(sourceInstance: sInstance, withDestinationInstance: dInstance, for: mapping)
        return
    }

I will say this:  this method above is used to create instances.  You don’t associate them yet!  That’s why you can see I set songFilename on these 2 new data types (in my new model), so that I can create their relationship later…  this is for the second pass in the migration, where relationship mappings are created (more on that).

Quick Reference for Mapping Editor FUNCTION arguments:

NSMigrationManagerKey: $manager
NSMigrationSourceObjectKey: $source
NSMigrationDestinationObjectKey: $destination
NSMigrationEntityMappingKey: $entityMapping
NSMigrationPropertyMappingKey: $propertyMapping
NSMigrationEntityPolicyKey: $entityPolicy

If I don’t need such a detailed mapping of an object, I can also use custom methods to set a property in the editor for any attribute.  Pro Tip: Make sure you change the the “Source Fetch” on a Relationship mapping to “Use Custom Value Expression” if you do this.

FUNCTION($entityPolicy, "filenameForLibraryWith:" , $manager)

This is syntax in the editor.  It’s saying “to get the value for this destination attribute, call a method on the (custom) policy called

func filename(forLibraryWith manager: NSMigrationManager) -> String

Remember you can use the arguments listed about in the Quick Reference section for knowing what kind of arguments you can pass into these methods!

You can also use these custom methods when performing relationship mappings.  Now, I personally haven’t had to override the method:

func createRelationships(forDestination dInstance: NSManagedObject, in mapping: NSEntityMapping, manager: NSMigrationManager) throws

I’ve got by with the Relationship mappings in the Mapping Model editor and custom methods.

Do not reference subclasses of NSManagedObject during migration!

It would seem that this is how Core Data ensures that the migration can work reliably.  It sucks because you need to remember:

  • awakeToInsert is not called, because no instances of your subclass are used in migration, so whatever you would set in awakeToInsert, you should do here too.
  • The relationship accessors aren’t present either.  So be safe and specify the relationship and its inverse.

I created a handy helper method to find NSManagedObject instances:

class LegacyToModernPolicy: NSEntityMigrationPolicy {
    
    static func find(entityName: String,
                     in context: NSManagedObjectContext,
                     sortDescriptors: [NSSortDescriptor],
                     with predicate: NSPredicate? = nil,
                     limit: Int? = nil) throws -> [NSManagedObject] {
        
        let fetchRequest: NSFetchRequest = NSFetchRequest(entityName: entityName)
        fetchRequest.predicate = predicate
        fetchRequest.sortDescriptors = sortDescriptors
        if let limit = limit {
            fetchRequest.fetchLimit = limit
        }
        
        do {
            let results = try context.fetch(fetchRequest)
            return results
        } catch {
            log.error("Error fetching: \(error.localizedDescription)")
            throw error
        }
    }
  }

Pitfalls, Gotchas, Other Tips, Things I’ve already said

Here’s a list of things I might have mentioned already, but in this modern age where attention spans are low, and we need headings to actually read something, here is a list of things that I discovered in this long journey over 2 days:

    1. If you created your new Data Model and it started with the same name as your legacy one (i.e. SongbookSimple), it’s better to just create a new Core Data Model file with a new name (e.g. SongbookSimpleDataModel), then rebuild your data model by hand. This in practice means copy-pasting all the entities from the one to the other. Note! The Delete rules are not copied over, NOR are the inverse relationships. So you’ll have to go in and for each Entity, connect these up again.
    2. If you get an error during Migration such as:
      Couldn’t create mapping policy for class named (LegacyToModernArtistPolicy)
      It’s probably because you have Swift module-related errors. See Sandeep’s comment in this Question:
      So LegacyToModernArtistPolicy becomes SongbookSimple.LegacyToModernArtistPolicy and it works
    3. If you change your current model to accommodate the migration process, AND you’ve already run the app, you’ve altered the data model in a bad way. You don’t know if this is a typical state to be in, so better play it safe. You’ve got to remove the app from the simulator, re-install an old version so to populate an old data store, then run your new version in development.
    4. If you are doing custom fetch requests so to satisfy creating relationships (in your NSEntityMigrationPolicy), it would seem that fetch requests are returning NSManagedObject objects and not the subclasses. Nor can they be casted. For example, you might have seen a crash error:Could not cast value of type 'NSManagedObject_Library_' (0x6100000504d0) to 'SongbookSimple.Library' (0x101679180).This is why the helper above can be useful.  I fixed the bug I mention here with:
          func libraryForManager(_ manager: NSMigrationManager) -> NSManagedObject {
              
              do {
                  var library: NSManagedObject? = try LegacyToModernPolicy.find(entityName: Library.entity().name!,
                                                          in: manager.destinationContext,
                                                          sortDescriptors: [NSSortDescriptor(key: "filename", ascending: true)],
                                                          with: nil,
                                                          limit: 1).first
                  if library == nil {
                      let dInstance = NSEntityDescription.insertNewObject(forEntityName: Library.entity().name!, into: manager.destinationContext)
                      
                      // awakeFromInsert is not called, so I have to do the things I did there, here:
                      dInstance.setValue(Library.libraryFilename, forKey: #keyPath(Library.filename))
                      dInstance.setValue(NSDate(timeIntervalSince1970: 0), forKey: #keyPath(Library.updatedAt))
                      library = dInstance
                  }
                  
                  return library!
                  
              } catch {
                  fatalError("Not sure why this is failing!")
              }
          }
      
    5. You think you are far along because all of your NSEntityMigrationPolicy objects are having their custom methods called, nothing is failing, but at the end of the migration process you’re still getting errors. SpecificallyCocoa error 1570. This implies that data validations are failing.It could easily be that it’s because you made a false assumption that awakeFromInsert will get called on your new instances during the migration process. For example you added a non-optional attribute to your model who gets his default value set in awakeFromInsert. You should specifically make sure these are getting set either via the mapping editor and your custom policy (with a custom method), or try to handle the errors in performCustomValidationForEntityMapping:manager:error:I prefer graphic tools. So I just write some boring methods that will set default values and it’s all good.
    6. IF YOU CHANGE YOUR MODEL, THEN THE MAPPING FILE WILL BREAK AND NOT BE FOUND DURING MIGRATION.IF YOU CHANGE YOUR MODEL, THEN THE MAPPING FILE WILL BREAK AND NOT BE FOUND DURING MIGRATION.This means you have to rebuild the Mapping File.
    7. In all of the NSEntityMigrationPolicy subclass, make sure you are always dealing with NSManagedObject and not their subclasses!! If you don’t, your automatic mappings (that use custom methods on the policy subclass) will fail.
    8. You don’t HAVE to create mappings in the Mapping Model editor. Basically, the part that has attribute mappings is a way of NOT overriding the method
      func createDestinationInstances(forSource sInstance: NSManagedObject, in mapping: NSEntityMapping, manager: NSMigrationManager) throws

      and the Relationship Mappings editor is a way of not having to subclass

      func createRelationships(forDestination dInstance: NSManagedObject, in mapping: NSEntityMapping, manager: NSMigrationManager) throws

      ONE THING you DO need to understand is that during the migration process, you are dealing with NSManagedObject instances, and not instances of your (likely) subclasses. So you don’t get all the benefits of the accessor methods that would ensure object graph integrity. What does this mean? You should make sure that you connect both sides of a relationship via relationship mappings. This means, in your data model it makes sense to keep a field to a ‘primary key’, so that you can use one object to find another.

    9. YAY! The Migration manager says it migrated… except… I got an exception:
      'Mismatch between mapping and source/destination models'

      I have to say, Core Data documentation sucks. There’s just not enough of it, and no explanation of why it fails during migration. Totally crap. I’ve spent a whole day just trying to shoot into the dark, hoping I’ll figure out what’s going on with this giant black box.

      The fix for this occurs in my modified MHWMigrationManager gist, and it’s what sorted me out!

Still Missing from everything that I learned:

  • I don’t really know how one is supposed to work with the createRelationships(…) method.  I only do that aspect of migration via the Mapping Model Editor and custom methods on the Policy
  • I haven’t done anything with validation yet.  So I don’t know how that comes into play.

Wrapping Up

This was a super long post.  But hopefully it can be seen as a good reference guide or at least things to think about when trying to do heavyweight migrations.  Now that I understand how they’re done, they’re not AS scary anymore.  What was annoying was trying to figure this all out.

If you benefit from this, I would be happy if you let me know!

Advertisements

Useful “Finder” methods on NSManagedObject in Swift

I don’t know about you, but CoreData seemed insane to me before I discovered MagicalRecord, back in the days of Mogenerator and Objective-C.

But since Swift 3 has come out, and the tools have improved to support Swift development (remember poor compiler warnings, if not just a “segmentation fault 11” error), I’m finding that I like to work with the Xcode tools again, and forego these old approaches.

My old way of doing things worked very well, and in some ways I miss some aspects of that, but ultimately I quickly (swiftly… cough cough) became a lover of Swift and simply prefer developing in that language.

What I miss most were the “MagicalFinders” categories present in MagicalRecord.  I found quite a concise way to do that however in Swift, and the code looks like this:

import Foundation
import CoreData

@objc public protocol CoreDataFinders {

    /// Because we are doing fetch requests on a data model,
    /// Fetch requests require sort descriptors.
    static func defaultSortDescriptors() -> [NSSortDescriptor]
}

extension CoreDataFinders where Self: NSManagedObject {
    
    public static func findAll(with predicate: NSPredicate?, context: NSManagedObjectContext) -> [Self] {
        
        let fetchRequest: NSFetchRequest = NSFetchRequest(entityName: Self.entity().name!)
        
        let predicate = predicate
        
        fetchRequest.predicate = predicate
        fetchRequest.sortDescriptors = self.defaultSortDescriptors()
        
        do {
            let results = try context.fetch(fetchRequest)
            return results
        } catch {
            if predicate != nil {
                print("Failed to fetch objects with predicate:\(predicate!.description) error:\(error)")
            } else {
                print("Failed to fetch objects with no predicate.  error:\(error)")
            }
        }
        return []
    }
    
    public static func findFirst(with predicate: NSPredicate?, context: NSManagedObjectContext) -> Self? {
        
        let fetchRequest: NSFetchRequest = NSFetchRequest(entityName: Self.entity().name!)
        
        let predicate = predicate
        
        fetchRequest.predicate = predicate
        fetchRequest.sortDescriptors = self.defaultSortDescriptors()
        fetchRequest.fetchLimit = 1
        
        do {
            let results = try context.fetch(fetchRequest)
            return results.first
        } catch {
            if predicate != nil {
                print("Failed to fetch objects with predicate:\(predicate!.description) error:\(error)")
            } else {
                print("Failed to fetch objects with no predicate.  error:\(error)")
            }
            
        }
        return nil
    }
}

And then you can add these to any object by either making a new baseclass in your app that subclasses NSManagedObject, or you just declare protocol support in your class definition and then these methods are added:

import Foundation
import CoreData

@objc(RecentItem)
class RecentItem: NSManagedObject, CoreDataFinders {
  static func defaultSortDescriptors() -> [NSSortDescriptor] {
    return [NSSortDescriptor(key: #keyPath(RecentItem.lastViewed), ascending: false)]
  }
  // ...
}

You can see here that you can extend this approach to pass in your own sort descriptors or limit fetch sizes, etc. This should be enough to get you started! The idea is that you can write the code once and have it apply to all instances of NSManagedObject on an opt-in basis.

“Invisible Container” – HSPassthroughView

I’d like to revisit an older post which deals with allowing subviews in a view hierarchy to be touchable, but making the parent view completely “non-interactive”.

Sometimes you need a ‘container view’ that can simplify Autolayout Constraint animations.  You want the view to be ‘invisible’ whilst allowing its subviews to behave normally. Being invisible, you may also want to tell it to inherit it’s superview’s color, so to reduce the need for layer blending (better performance)

I present the updated HSPassthroughView:

#import <UIKit/UIKit.h>

IB_DESIGNABLE
@interface HSPassthroughView : UIView

@property (nonatomic, assign) IBInspectable BOOL inheritsBackgroundColor;  // defaults to NO

@end

@implementation HSPassthroughView

- (UIView*)hitTest:(CGPoint)point withEvent:(UIEvent *)event
{
    UIView *view = [super hitTest:point withEvent:event];
    if (view == self)
    {
        NSLog(@"A view was asked for a view, but this is a QLPassthroughView.  If you see this message but expect a touch to be found, look here.");
        return nil;
    }   
    return view;  //ensure this view will never register a touch!
}
- (void)awakeFromNib
{   
    if (self.inheritsBackgroundColor && self.superview) {
        self.backgroundColor = self.superview.backgroundColor;
    }
}
- (void)willMoveToSuperview:(UIView *)newSuperview
{
    if (self.inheritsBackgroundColor) {
        self.backgroundColor = newSuperview.backgroundColor;
    }
    [super willMoveToSuperview:newSuperview];
}
@end

This helped solve a problem I had that was on StackOverflow.

UINavigationBar that Scrolls Away (Revised)

On this blog one of my most searched for posts is the one about a UINavigationBar that scrolls away.

That was written a while back.  I’ve recently had to revisit this topic again, so I thought I’d revise my implementation, which aims to remove many caveats and just make it easy to drop into your code and you’re done.

So I redid that code and made it slightly less hacky, and implemented it as a category on UIVIewController. If it doesn’t work for you the only thing I can think of are the new properties on UIViewController that pertain to layout. Mine had automaticallyAdjustScrollViewInsets to YES, and extend edges under top bars.

//  UIViewController+ScrollyNavBar.h
//
//  Created by Stephen O'Connor on 24/03/16.
//  MIT License
//

/*
 
 How to use this:
 
 import this into your (probably) table view controller
 
 make sure you set HS_navigationBarLayerDefaultPosition in viewDidLoad:
 
 self.HS_navigationBarLayerDefaultPosition = self.navigationController.navigationBar.layer.position;
 
 optionally set HS_scrollingNavigationBarThresholdHeight if you want to be able to scroll a bit before 
 the nav bar starts scrolling with it.  A typical use case would be if you want the bar to start
 scrolling with your first table view section, and not with the tableViewHeader.
 
 in viewWillAppear:, call:
 
 - (void)HS_updateNavigationBarPositionUsingScrollView:(UIScrollView*)scroller
 
 and, assuming your table view controller is still the UITableView's delegate, it's also
 a scroll view delegate.  In -scrollViewDidScroll:, call:
 
 - (void)HS_updateNavigationBarPositionUsingScrollView:(UIScrollView*)scroller
 
 as well.
 
 Done!
 
 
 */


#import <UIKit/UIKit.h>

@interface UIViewController (ScrollyNavBar)

@property (nonatomic, assign) CGFloat HS_scrollingNavigationBarThresholdHeight;  // defaults to 0.  I.e. think about tableViewHeader's height
@property (nonatomic, assign) CGPoint HS_navigationBarLayerDefaultPosition;

- (void)HS_updateNavigationBarPositionUsingScrollView:(UIScrollView*)scroller;

@end

Then then .m file:

// some theoretical knowledge here:  http://nshipster.com/associated-objects/

#import "UIViewController+ScrollyNavBar.h"
#import <objc/runtime.h>


@implementation UIViewController (ScrollyNavBar)

@dynamic HS_scrollingNavigationBarThresholdHeight;
@dynamic HS_navigationBarLayerDefaultPosition;

- (void)setHS_navigationBarLayerDefaultPosition:(CGPoint)HS_navigationBarLayerDefaultPosition {
    objc_setAssociatedObject(self,
                             @selector(HS_navigationBarLayerDefaultPosition),
                             [NSValue valueWithCGPoint:HS_navigationBarLayerDefaultPosition],
                             OBJC_ASSOCIATION_RETAIN_NONATOMIC);
}

- (CGPoint)HS_navigationBarLayerDefaultPosition {
    return [(NSValue*)objc_getAssociatedObject(self, @selector(HS_navigationBarLayerDefaultPosition)) CGPointValue];
}

- (void)setHS_scrollingNavigationBarThresholdHeight:(CGFloat)HS_scrollingNavigationBarThresholdHeight {
    objc_setAssociatedObject(self,
                             @selector(HS_scrollingNavigationBarThresholdHeight),
                             @(HS_scrollingNavigationBarThresholdHeight),
                             OBJC_ASSOCIATION_RETAIN_NONATOMIC);
}

- (CGFloat)HS_scrollingNavigationBarThresholdHeight {
    return [(NSNumber*)objc_getAssociatedObject(self, @selector(HS_scrollingNavigationBarThresholdHeight)) floatValue];
}

- (void)HS_updateNavigationBarPositionUsingScrollView:(UIScrollView*)scroller
{
    // get the navigation bar's underlying CALayer object
    CALayer *layer = self.navigationController.navigationBar.layer;
    CGFloat contentOffsetY = scroller.contentOffset.y;
    CGPoint defaultBarPosition = self.HS_navigationBarLayerDefaultPosition;
    CGFloat scrollingThresholdHeight = self.HS_scrollingNavigationBarThresholdHeight;
    
    // if the scrolling is not at the top and has passed the threshold, then set the navigationBar layer's position accordingly.
    if (contentOffsetY > -scroller.contentInset.top + scrollingThresholdHeight) {
        
        CGPoint newPos;
        newPos.x = layer.position.x;
        newPos.y = defaultBarPosition.y;
        newPos.y = newPos.y - MIN(contentOffsetY + scroller.contentInset.top - scrollingThresholdHeight, scroller.contentInset.top);
        
        layer.position = newPos;
        
    }
    else
    {
        layer.position = defaultBarPosition;  // otherwise we are at the top and the navigation bar should be seen as if it can't scroll away.
    }
}

@end

Boom! Pretty straightforward.

Note however, that I don’t really recommend this functionality because it’s prone to error, and it’s sort of hacking UINavigationBar.  It has a few related consequences:

  • UITableView section headers will still ‘stick’ to the bottom of the now invisible navigation bar.
  • You must use a translucent UINavigationBar for this to really work properly.

Now, for the first of those two points, I don’t have a solution and anyone who does, please leave me something in the comments.

For the second one, if you read the API docs of UINavigationBar closely, you’ll see:

@property(nonatomic, assign, getter=isTranslucent) BOOL translucent

Discussion

The default value is YES. If the navigation bar has a custom background image, the default is YES if any pixel of the image has an alpha value of less than 1.0, and NO otherwise.

So, with a little trickery, we can just change the Class on a UINavigationController to use a custom UINavigationBar class that sets an *almost* opaque image as the background image any time you change the barTintColor:


#import "UIImage+NotQuiteOpaque.h"

@interface HSNavigationBar : UINavigationBar
@end

@implementation HSNavigationBar

- (void)awakeFromNib
{
    [self setBarTintColor:self.barTintColor];
}

- (void)setTranslucent:(BOOL)translucent
{
    NSLog(@"This HSNavigationBar must remain translucent!");
    [super setTranslucent:YES];
}

- (void)setBarTintColor:(UIColor *)barTintColor
{
    UIImage *bgImage = [UIImage HS_stretchableImageWithColor:barTintColor];
    [self setBackgroundImage:bgImage forBarMetrics:UIBarMetricsDefault];
}

@end

And you’ll see here that the real trick is this category on UIImage that generates a stretchable image of the color specified, but it sets the top right corner’s pixel alpha value to 0.99. I assume that nobody will notice that slight translucency in one pixel at the top right of the screen.

@implementation UIImage (NotQuiteOpaque)

+ (UIImage*)HS_stretchableImageWithColor:(UIColor *)color
{
    
    UIImage *result;
    
    CGSize size = {5,5};
    CGFloat scale = 1;
    
    CGFloat width = size.width * scale;
    CGFloat height = size.height * scale;
    CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
    
    size_t bitsPerComponent = 8;
    size_t bytesPerPixel    = 4;
    size_t bytesPerRow      = (width * bitsPerComponent * bytesPerPixel + 7) / 8;
    size_t dataSize         = bytesPerRow * height;
    
    unsigned char *data = malloc(dataSize);
    memset(data, 0, dataSize);
    
    CGContextRef context = CGBitmapContextCreate(data, width, height,
                                                 bitsPerComponent,
                                                 bytesPerRow, colorSpace,
                                                 (CGBitmapInfo)kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big);
    
    CGFloat r, g, b, a;
    UIColor *colorAtPixel = color;
    
    r = 0, g = 0, b = 0, a = 0;
    
    for (int x = 0; x < (int)width; x++)
    {
        for (int y = 0; y < (int)height; y++)
        {
            if (x == (int)width - 1 && y == 0) {
                colorAtPixel = [color colorWithAlphaComponent:0.99f];  // top right
            }
            
            [colorAtPixel getRed:&r green:&g blue:&b alpha:&a];
            
            
            int byteIndex = (int)((bytesPerRow * y) + x * bytesPerPixel);
            data[byteIndex + 0] = (int)roundf(r * 255);    // R
            data[byteIndex + 1] = (int)roundf(g * 255);  // G
            data[byteIndex + 2] = (int)roundf(b * 255);  // B
            data[byteIndex + 3] = (int)roundf(a * 255);  // A
            
            colorAtPixel = color;
        }
    }
    
    CGColorSpaceRelease(colorSpace);
    CGImageRef imageRef = CGBitmapContextCreateImage(context);
    result = [UIImage imageWithCGImage:imageRef scale:scale orientation:UIImageOrientationUp];
    CGImageRelease(imageRef);
    CGContextRelease(context);
    free(data);

    result = [result resizableImageWithCapInsets:UIEdgeInsetsMake(2, 2, 2, 2) resizingMode:UIImageResizingModeStretch];
    
    return result;
    
}

@end

So, there it is. It works, yes, but not perfectly, and the whole thing feels a bit hacky. I wonder if there’s a better way to do this, or if in the future Apple will start to update this code. Seeing as we see collapsing address bars on WebView controllers like in Safari, perhaps they might abstract this further to support UINavigationControllers.

Stretchy Header UITableView (and how I hate hacks)

I really dislike using a UIViewController subclass to make fundamental functionality of a UIView work.  That said, I will do what needs doing to get the job done.  Sometimes there are no other obvious ways to do something non-typical.

Recently I looked for code that could help me recreate “stretchy header” functionality.  And I found some here.  It wasn’t a bad approach.  It worked.  But somehow seemed a bit brittle, or for a very specific use-case.  It was adjusting contentInset depending on contentOffset value.  That seemed sub-optimal.

I’m currently working on a UITableViewController subclass that should be configurable to have stretchy headers, expandable section headers (see previous post), and scrollable navigation bars (also a post of mine from 2012… will finally (soon) get a fresh coat of paint).

Anyway, I found the easiest way to make stretchy header views.  Simply, you have to subclass UITableView and make sure your UITableViewController subclass uses an instance of it and not of a standard UITableView.  The advantage here is that you don’t need to change any view controller code, so you don’t have issues associated with class inheritance.

Enough talk.  Here’s the code.  You can try it for yourself.

//  HSStretchyHeaderTableView.h
//  TableViewSandbox
//
//  Created by Stephen O'Connor on 23/03/16.
//  MIT License.
//

#import <UIKit/UIKit.h>

IB_DESIGNABLE
@interface HSStretchyHeaderTableView : UITableView

@property (nonatomic, assign, getter=hasStretchyHeader) IBInspectable BOOL stretchyHeader;

@end

And now the .m file:

#import "HSStretchyHeaderTableView.h"

@interface HSStretchyHeaderTableView()
{
    CGFloat _headerViewHeight;
}
@end

@implementation HSStretchyHeaderTableView

- (void)awakeFromNib
{
    // NOTE, You will have to modify this solution if you don't use InterfaceBuilder!
    _headerViewHeight = self.tableHeaderView.bounds.size.height;
}

- (void)layoutSubviews
{
    [super layoutSubviews];
    
    if (self.hasStretchyHeader)
    {
        CGRect headerFrame = self.tableHeaderView.frame;
        
        if (self.contentOffset.y  _headerViewHeight)
        {
            headerFrame.origin.y = 0;
            headerFrame.size.height = _headerViewHeight;
            self.tableHeaderView.frame = headerFrame;
        }
    }
}

@end

Pretty easy! Happy coding!

Cheat Sheet – IB_DESIGNABLE Views

Not so much a cheat sheet, but a general procedure to follow. Consider this class, a UILabel that draws an outline around it that you can customize and more importantly, view from Interface Builder:

#import 

IB_DESIGNABLE
@interface HSOutlinedLabel : UILabel

@property (nonatomic, assign) IBInspectable CGFloat outlineWidth;
@property (nonatomic, assign) IBInspectable UIColor *outlineColor;
@property (nonatomic, assign) IBInspectable CGFloat cornerRadius;

@property (nonatomic, assign) IBInspectable CGPoint padding;  // between the text and outline

@end

and then the .m

#import "HSOutlinedLabel.h"

@implementation HSOutlinedLabel

- (instancetype)initWithCoder:(NSCoder *)aDecoder
{
    self = [super initWithCoder:aDecoder];
    if (self) {
        
        [self _commonInit];
    }
    return self;
}

- (void)_commonInit
{
    // gets called first (initWithCoder:), before any of the settings in IB are used.
    self.layer.masksToBounds = YES;
    _outlineWidth = 0;
    _outlineColor = nil;
    _cornerRadius = 5;
    _padding = CGPointZero;
    self.layer.cornerRadius = _cornerRadius;
    
}

- (void)prepareForInterfaceBuilder
{
    // careful!  this will overwrite any settings in Interface Builder.
    // it's meant for setting values that perhaps aren't IBInspectable
    [super prepareForInterfaceBuilder];
}

- (void)awakeFromNib
{
    if (_outlineWidth > 0) {
        self.layer.borderWidth = _outlineWidth;
        
        if (_outlineWidth > 0) {
            self.layer.borderColor = _outlineColor ? _outlineColor.CGColor : NULL;
        }
        else
        {
            self.layer.borderColor = NULL;
        }
    }
}

#pragma mark - Setters (Are used by Interface Builder)

// NOTE:  Interface Builder calls setValue:forKey: when you change
// an inspectable value.  If you are purely drawing your UIView subclass
// with -drawRect: then these changes update.
// However, if you see the setters below, I use the IBInspectables
// to ultimately wrap CALayer properties.  If you want your view to
// draw correctly,  you need to write accessors for any IBInspectable
// that triggers changes to any object that won't necessarily be done
// in drawRect:

- (void)setOutlineWidth:(CGFloat)outlineWidth
{
    if (_outlineWidth != outlineWidth) {
        _outlineWidth = outlineWidth;
        self.layer.borderWidth = outlineWidth;
    }
}

- (void)setOutlineColor:(UIColor *)outlineColor
{
    if (_outlineColor != outlineColor) {
        _outlineColor = outlineColor;
        self.layer.borderColor = outlineColor.CGColor;
    }
}

- (void)setCornerRadius:(CGFloat)cornerRadius
{
    if (_cornerRadius != cornerRadius) {
        _cornerRadius = cornerRadius;
        self.layer.cornerRadius = cornerRadius;
    }
}

- (void)setPadding:(CGPoint)padding
{
    if (!CGPointEqualToPoint(_padding, padding)) {
        _padding = padding;
        [self invalidateIntrinsicContentSize];
    }
}

- (CGSize)intrinsicContentSize
{
    CGSize size = [super intrinsicContentSize];
    size.width += 2 * _padding.x;
    size.height += 2 * _padding.y;
    
    return size;
}

@end

I just meant this to be a starting point for your own work. And actually a reminder for myself.

UITableView with Animating Section Header

So, I’ve been scratching my head on an issue I’ve been having:

I want to have a UITableView with a section header, because I want it to stick to the top of the screen while scrolling.  The thing is, it’s supposed to have a search bar that expands when you enter “search mode”.

What you see in the video is my prototype.  Tapping a table cell is supposed to toggle this search mode on and off.  In the video above you see that that table cell layout updates and expands, but the section header seems to be “one click behind” and expands when the cell layouts push up because they think the header is shorter.

This behaviour happened via the standard posts on stack overflow.  Here, for example.

Now, perhaps my issue is because I also have a stretchy section header, which I based off of this post:

Anyway, I found the solution involved a slightly complicated solution, but once it’s in place, there’s little to know (i, ii, iii, …) and do (A, B, C, D, …) :

i)  I assume you will have one section on your table view
A) Define an associated view on your view controller, which will be your “expandableHeaderView” (more on the specifics later)
Screenshot 2016-03-17 14.03.04

B) Define your class to have such properties and methods:

IB_DESIGNABLE
@interface QLExpandableSectionHeaderTableViewController : UITableViewController

@property (nonatomic, assign) IBInspectable NSInteger expandableSectionHeaderInactiveHeight;  // defaults to 44
@property (nonatomic, assign) IBInspectable NSInteger expandableSectionHeaderActiveHeight; // defaults to 88

@property (nonatomic, strong) IBOutlet UIView *expandableHeaderView;

@property (nonatomic, readwrite, getter=isHeaderExpanded) BOOL headerExpanded;

- (void)setSectionHeaderHeightExpanded:(BOOL)expanded animated:(BOOL)animated;

@end


@implementation QLExpandableSectionHeaderTableViewController

- (instancetype)initWithCoder:(NSCoder *)aDecoder
{
    self = [super initWithCoder:aDecoder];
    if (self) {
        _expandableSectionHeaderInactiveHeight = 44.f;
        _expandableSectionHeaderActiveHeight = 88.0f;
    }
    return self;
}

- (void)viewDidLoad {
    [super viewDidLoad];
    
    if (!self.expandableHeaderView) {
        NSLog(@"WARNING: You haven't provided an associated header view you want to use when toggling section header height!");
    }
    else
    {
        // this has to be clear, since animation doesn't quite work as desired.
        self.expandableHeaderView.backgroundColor = [UIColor clearColor];
    }
}


- (CGFloat)tableView:(UITableView *)tableView heightForHeaderInSection:(NSInteger)section
{
    if (section == 0) {
        if (self.isHeaderExpanded) {
            return self.expandableSectionHeaderActiveHeight;
        }
        return self.expandableSectionHeaderInactiveHeight;
    }
    
    return 0;
}

- (UIView*)tableView:(UITableView *)tableView viewForHeaderInSection:(NSInteger)section
{
    if (section == 0) {
        
        if (self.expandableHeaderView) {
            return self.expandableHeaderView;
        }
        else
        {
            // will probably never get used
            UIView *header = [UIView new];
            header.backgroundColor = [UIColor redColor];
            header.frame = CGRectMake(0, 0, self.tableView.bounds.size.width, self.expandableSectionHeaderInactiveHeight);
            return header;
        }
    }
    

    return nil;
}

- (void)toggleSectionHeader:(UIButton*)button
{
    if (self.isHeaderExpanded) {
        [self setSectionHeaderHeightExpanded:NO animated:YES];
    }
    else {
        [self setSectionHeaderHeightExpanded:YES animated:YES];
    }
}

- (void)setSectionHeaderHeightExpanded:(BOOL)expanded animated:(BOOL)animated
{
    if (self.isHeaderExpanded && expanded) {
        return;  // nothing to do!
    }
    
    self.headerExpanded = expanded;
    [self.tableView beginUpdates];
    [self.tableView endUpdates];
    
    //NSLog(@"%@", self.searchHeaderView.constraints);
    __block NSLayoutConstraint *headerHeightConstraint = nil;
    [self.expandableHeaderView.constraints enumerateObjectsUsingBlock:^(__kindof NSLayoutConstraint * _Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {
        
        // I determined this name by logging the self.searchHeaderView.constraints and noticed
        // it had a constant value that was one of my searchBar(In)activeHeight values.
        if ([obj.identifier isEqualToString:@"UIView-Encapsulated-Layout-Height"]) {
            headerHeightConstraint = obj;
            *stop = YES;
        }
    }];
    
    CGFloat newHeight = expanded ? self.expandableSectionHeaderActiveHeight : self.expandableSectionHeaderInactiveHeight;
    headerHeightConstraint.constant = newHeight;
    
    // after the animation completes, the expandableHeaderView's frame doesn't change until a layout update
    // , which only happens after you start scrolling.  This will ensure it has the right size as well.
    CGRect frame = self.expandableHeaderView.frame;
    frame.size.height = newHeight;
    
    [UIView animateWithDuration:animated ? 0.3f : 0.0f
                          delay:0.0f
                        options:UIViewAnimationOptionCurveEaseInOut
                     animations:^{
                         [self.tableView layoutIfNeeded];
                     } completion:^(BOOL finished) {
                         self.expandableHeaderView.frame = frame;
                     }];
    
}

The code above will handle animation.  There is still some weirdness happening on the UIKit side of things, because the the header view’s subviews animate according to auto-layout, but the self.expandableHeaderView doesn’t visually change size until a layout update occurs.  And this only occurs once you start scrolling.  So we set that frame to the size it’s supposed to have, and that sorts it all out. As a result, we have to set the self.expandableHeaderView.backgroundColor = [UIColor clearColor];

And that solved the problem! It’s a bit hacky, but I found no other way to accomplish this that isn’t THAT ugly.

And here’s the result: