iOS Core Data Database Update

The Core Data database is the most commonly used as a data store for iOS apps. Nobody could design the database once and never change it again. I occasionally need to make some changes or update my Core Data database.

When the database scheme is changed, for example, adding a new entity, removing an entity, or changing entity fields, how could such kinds of changes affect your app? Would your app users lose all the data if any changes are made?

If you don't set up your database correctly, you may cause users frustration or pain. Fortunately, Apple provides a very solid and complete core data framework to allow you to migrate database changes during your app's life time without losing any data. In most cases, you would not need to do anything in particular. In some cases, you may need to write some codes to update data since you know what should be done.

Here are some notes regarding this issue.

Set the Correct Core Data Store Options

For the time being, in iOS 10.*, a Core Data store is created and managed by means of NSPersistentContainer. At the time this container is created, some critical options have to be set so that future updates or changes will be migrated smoothly without losing data.

The following is an example of how to set up the container with important options. If you don't set those, any changes to the database store would cause data loss because of a totally new schema.

1. let storeDesription = NSPersistentStoreDescription(url: url)
2. storeDesription.shouldInferMappingModelAutomatically = true
3. storeDesription.shouldMigrateStoreAutomatically = true
4. container.persistentStoreDescriptions = [storeDesription]
5. container.loadPersistentStores() {
6.    (storeDescription, error) in
7.    if let error = error as NSError? {
8.        // Handle errors here
9.    }
10. }

Add a New Version of the Database

In Xcode 9.4, if you need to change your database schema, don't make the change directly to the database model. Instead, add a new version to your database model and make the new version the active model.

From the menu of Editor->Add Model Version...,

Accepting the recommended model name, a new model version will be added.

In the right-hand inspector, add a new model identifier and select the new version as the current model version.

In this way, you can carry the previous database schema as-it-is to the next new version and make changes to the new version.

In most cases, all your data will be kept in the new database without any loss. Even though you have to test your app after your update to make sure it will keep or present previous database data smoothly.

Add Your Customized Updates

If you need to update your data as you know what the changes are and how to set up data correctly, you can do it at your app startup time.

For example, here is my practice of updating data at the app delegate class:

1. @UIApplicationMain
2. class AppDelegate : UIResponder, UIApplicationDelegate {
3.  func application(_ application: UIApplication,
4.    didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
5.    {
6.       // Override point for customization after application launch.
7.       MyUserDefaults.shared.setupDefaults()
8.       AppDatabase.shared.updateDatabase()
9.       return true
10.    }
11. ...
12. }

I use UserDefaults, i.e., app settings, as a place to save app and database versions and load those versions at the app's startup time. Then in the updateDatabase() method, I'll check if the previous app and database versions are older than a given version. If so, then some updates will be made so that the data will be kept up to date. Here is my example case:

1. class AppDatabase {
2.  static var shared: AppDatabase {
3.    struct local {
4.      static let instance = AppDatabase()
5.    }
6.    return local.instance
7.  }
9.  func updateDatabase() {
10.     guard VersionManager.shared.isOlderThan(.database_v1_2_0) else { return }
11.     cleanUpDataBase()      // do some cleanup missed in old db
12.     updateSortProperties() // set sort values for the new fields
13.  }
14.  ...
15. }

References

• Apple Developer Documentation: Using Lightweight Migration

Read More...

Collapse...

Building a Bridge between Swift and JS

This was a challenge for me to make Swift talk to JS or JS to Swift. I have been working on an iOS app for years. With so many years of practice, I think I am very good at a deep technical level. I have also done a lot of html and JS programming. What I know about JS is mainly based on what I need to do on my blog.

In my app updates, what I need to do is to provide some information to users about how to use the app. An HTML view is a good choice for this purpose. However, I encountered a challenge that some of the information HTML needs is actually available easily on the Swift side. How can I let JS make a request to Swift, and then Swift pass the requested information back to JS?

This is what I mean by a bridge between Swift and JS.

Working Environment

In my project, I use a simple ViewController with a WKWebView UI component. The class is a very simple one. In the viewDidLoad event, an html file will be loaded into WKWebView. The content defined in the html file will be displayed on the view screen.

1. class MyWebViewController: UIViewController
2. {
3.   @IBOutlet weak var webView: WKWebView!
4.   {
5.     didSet {
6.       setup() // Place 1: magic will be injected from here.
7.     }
8.   }
9.   var htmlUrl: URL? = nil
11.   override func viewDidLoad()
12.   {
13.      super.viewDidLoad()
14.      guard let url = htmlUrl else { return }
15.      webView.loadFileURL(
16.            url
17.            allowingReadAccessTo: url)
18.      let request = URLRequest(url: url)
19.      webView.load(request)
20.   }
22.    override func viewWillDisappear(_ animated: Bool)
23.    {
24.        super.viewWillDisappear(animated)
25.        // Place 2: some codes to be added here.
26.    }
27. }

My html file contains information about how JS is loaded. Normally, a JS script file is defined in the head section. For example,

1. <head>
2.   <meta charset='UTF-8'/>
3.   <!-- JS functions used in html  -->
4.   <script type="text/javascript" src="../myScriptFile.js"></script>
5.   ...
6. </head>

As you can see from the above structure, I have a view controller with a web viewer, in Swift code to present html content. The JS files which will be referenced from html are in my project bundle. This is my working environment.

A Case Study

Here is my case. In my html content, there is one element for displaying my app version.

<h2 class="center">Version <span id="appVersion">to be filed</span></h2>

This could be easily done by using a JS function like this:

1. function swift2JSCallFor(appVersion) {
2.    let e = document.getElementById("appVersion");
3.    e.innerHTML = appVersion;
4. }

The version string can be easily obtained in Swift code. How can I make a call from Swift to this JS function with version information?

WKScriptMessageHandler as a Gateway

Fortunately, Apple provides an API for the case of my view controller with WKWebView. WKScriptMessageHandler is the name of this API. This handler protocol can be implemented as a message channel gateway between Swift and JS.

This gateway could be implemented in my view controller class. There are some codes required to set it up. The disadvantage of doing this in my view controller is that I would have to repeat a block of similar code again and again in other view controller classes if I needed to do a similar thing. Another point is that adding some codes just for this kind of gateway would pollute my view controller class and make it harder to read and maintain.

Build My Gateway Class

After my thorough study and tests of this framework and a good understanding of what is required, I decided to create a new class to encapsulate the business logic or structure outline inside my class and expose the necessary settings for customizing.

1. import WebKit
3. typealias ScriptMessageHandlerBlock =
4.    ((WKUserContentController,
5.      WKScriptMessage) -> ())
7. class MyWKScriptBridgeHelper: NSObject
8. {
9.    init(
10.        observer: String,
11.        scriptMessageHandlerBlock: ScriptMessageHandlerBlock?
12.    )
13.    {
14.        webObserver = observer
15.        wKScriptMessageHandlerBlock = scriptMessageHandlerBlock
16.    }
18.    private var webObserver: String = ""
20.    private var wKScriptMessageHandlerBlock:
21.    ScriptMessageHandlerBlock? = nil
23.    var webObserverName: String {
24.        return webObserver
25.    }
26. }
28. extension WKScriptMessageHandler: WKScriptMessageHandler
29. {
30.    func userContentController(
31.        _ userContentController: WKUserContentController,
32.        didReceive message: WKScriptMessage)
33.    {
34.        guard let block = wKScriptMessageHandlerBlock else
35.        {
36.            return
37.        }
39.        block(userContentController, message)
40.    }
41. }

The class logic is simple. Only two parameters are required to create an instance of this class. One is a webObserver name, which will be called from JS to Swift to the gateway implemented in this class. Another one is a block of code where Swift information will be gethered or prepared and JS functions will be called.

Set it up on the Swift Side

OK, so far so good. It is time to put it all together in practice!

In my view controller class, there are two places where I will put some code. The first place is to set up my gateway instance of the MyWKScriptBridgeHelper class.

1. class MyViewController
2. {
3.  private var scriptHelper: MyWKScriptBridgeHelper!
4.    ...
5.  private func setup()
6.  {
7.    let webObserver = "appVersion"
8.    let block: ScriptMessageHandlerBlock
9.        = {
10.            [weak self] (userController, message) in
11.            guard let this = self else {
12.                return
13.            }
15.            // Make sure that it is html js function callback
16.            guard message.name ==
17.                    webObserver else {
18.                return
19.            }
20.            // get app version string
21.            let v = ... // get app version
22.            let jsFunc = String(
23.                format: "swift2JSCallFor('%@')",
24.                v)
25.            // Sends back app version to hml js function
26.            this.webView.evaluateJavaScript(
27.                jsFunc,
28.                completionHandler: nil)
29.        }
30.        scriptHelper = MyWKScriptBridgeHelper(
31.            observer: webObserver,
32.            scriptMessageHandlerBlock: block)
33.  }
34.  ...
35. }

In this setup(), two parameters are prepared for creating the instance of MyWKScriptBridgeHelper. One is the name of "webObserver" as the message name of the gateway. Another one is the block to verify the right message is received, to prepare the app version, and finally call a JS function "swift2JSCallFor()" to send the app version to the JS side.

The second location is in the view controller disappear event, where you should perform some cleaning by removing any message handlers and deallocating scriptHelper to avoid memory leaks.

1. override func viewWillDisappear(_ animated: Bool)
2. {
3.   super.viewWillDisappear(animated)
4.   guard let sh = scriptHelper else { return }
6.   // Clear message handler from script helper
7.   webView.configuration.userContentController.removeScriptMessageHandler(
8.       forName: sh.webObserverName)
9.   scriptHelper = nil
10. }

That's all I need to do to set my gateway up. First, the gateway will handle a message requesting the app version from the JS side. Then it will call a JS function to pass the app version to JS.

HTML and JS Configuration

On the html and JS side, the first step is to make a request to Swift for the app version. This can be done by calling a JS function on html body element's onload attribute.

1. <body onload="updateVersion()">
2. ...
3. <h2 class="center">Version
4. <span id="appVersion">to be updated...</span></h2>
5. ...
6. </body>

The second step is to set up Javascript functions to make a request and to handle Swift calls.

1. function updateVersion()
2. {
3.  try {
4.    var msg = {}; // for empty parameter, it has to be {}
5.    // "appVersion" is the request message name on Swift side
6.    window.webkit.messageHandlers.appVersion.postMessage(msg);
7.  } catch(err) {}
8. }
10. // function to be called from Swift to pass app version
11. // to JS.
12. function swift2JSCallFor(appVersion) {
13.  let e = document.getElementById("appVersion");
14.  e.innerHTML = appVersion;
15. }

The comment description in the Javascript explains everything. That's all. With the above configuration, Swift and JS can talk to each other and pass the required information as needed.

Here is a snapshot of my html view with the correct version updated. I am so happy that this update will be automatically done and I don't need to touch the html file in future updates.

I have a short summary at the conclusion of this blog. Swift-JS communication was new to me. I spent more than one week investigating and doing my tests. The above strategy is based on other resources (see references) and my effort. This is not the best and complete solution. I may miss something. Please leave comments and provide your better solutions. Critics are welcome.

References

• Blog: Web to native code communication on iOS using WKScriptMessageHandler
• Blog: Using WebKit to call WKWebView JavaScript from Swift and Swift from JavaScript
• SO: My comments on this SO question
• You may love my creative iOS app. Record your life notes just by tapping your mobile device. Keep your memory fresh when you review those taps with the time, location, and notes you add: TapMyNotes app
• My work tool is Xcode ver 13.4 and Swift ver 5.

Read More...

Collapse...

HTML Head Settings

Recently, I have been busy working on my iOS updates. One feature I want to add is to provide some information views in the app.

There are many ways to present information on display in an app. I could use a rich-text component or a text view with attributed strings. However, compared to HTML, I prefer to use a web viewer to display HTML content. The most recent update and recommended strategy by Apple is WKWebView. This component fully supports HTML5 features with extensive Apple support for iOS devices, such as dynamic text size, zooming and pinch support, accessibility support, and more.

ViewController With WKWebView

With the HTML strategy, I could use HTML to format my information content with css styles, images, and js scripts. The way it works is just like a web server/client fully functional environment. My project acts like a web server. I place all my HTML files, images, css files, and js files into groups. Add a view controller class with WKWebView as the main container.

1. class MyHTML1ViewController: UIViewController {
2.   private var webView: WKWebView!
3.   var htmlFile: String = "" // default value, can be changed
4.   override func viewDidLoad() {
5.    super.viewDidLoad()
6.    let url = Bundle.main.url(
7.            forResource: htmlFile,
8.            withExtension: "html")
10.    let request = URLRequest(url: url)
11.    webViewBase.load(request)
12.  }
13. ...
14. }

Then an html file can be loaded into the view, and the content is displayed in a way similar to a web browser.

Localization

In my project, Xcode provides support for localization. All HTML files, image files, and css files can be localised based on language support in my project. Currently, I have 3 languages to support, plus a base. A total of 4 sets of files are automatically created for me in my project. Taking an HTML file as an example, 4 HTML files are created for each language, and they are placed into a subfolder named by its language identifier. The same is true for images and css files.

Here is a snapshot of my project for groups of HTML-supported files. I group them into js, css, images, and html group names.

As you can see, each localizable item has a list of supported languages. With this visual layout, I can easily pick a language file and do my translation work.

The file structure is very different from the visual view of the project. Actually, all files are in the same root folder of projects. It is really hard to find them if I want to open Finder to find a file. That's why I named all HTML-supported files with a prefix of html_.

Further investigation, I found that within my app main bundle, all HTML supported localizable files within the project are placed in subfolders by the name of language identifiers. In other words, in my app bundle, all localised files are placed in a subfolder named as the language identifier. For example, for English, "en.lproj" subfolder contains all localised files, including my HTML-supported files. One level up from language subfolders is the root path, where all none-localized files sit. For example, js files are at the root level.

As I present all this in the above pictures, I will try to explain my understanding of how web server/client works within my app project. This picture of file layout is the web server's path structure. When an html file is loaded into WKWebViewer, all related images and css files are in the same path as the html file. Up one level is the place where js files are located.

With this understanding, I can edit my html files to refer to other source files and components easily. WKWebView is something like a browser to present HTML content and let users review and interact with it. As a client, the viewer has knowledge about where to get those sources and components from my project. I call it a server.

Keep in mind, I integrated WKWebView views into my project is based on HTML support and functionality. However, my app, built by my project, does not provide any end points for external web clients to access. My app is a native iOS app running on an iOS device.

Duplication of Settings in the head Section

I have several HMTL files to be presented by a number of view controllers with WKWebView, currently about, information and setttings. There will be expanded to more, let's say n HTML contents. Four language sets are supported in my project, and might be increased to more, m languages supported. You can imagine that n x m HTML files are in my project.

One thing I realise is that within an HTML file, in the document.head section, there are many settings. For example, common and specific css source files, common and specific js libray files, and meta configuration for various settings such as view point. Some of them are the same or repeated in all HTML files.

I realised there would be a maintenance issue. If any of these common parts are changed, as I will find some interesting feature support, I have to edit all those HTML files to do just copy and paste work. Is there any better way to do the maintenance job? Actually, I had encountered some issues where I forgot to update some languages, and those language displays did not work in the way I expected.

Seeking Help from SO

StackOverflow is a community of IT programmers' participation network. There are many talented people there to support others with all kinds of questions. After struggling to find a solution, I posted my question there. I was hoping to get advice from talented people.

Before I posted my Q, I tried various ways, including using Swift within my project. There is one way to open an HMTL url from my project. Then I could do parameter replacement of the content of the HTML file as a string. However, I remembered that I tried this method before. I just could not change any files within my application bundle!

The short story is that I tried to use a plist file within my project to save some setting changes. No errors are thrown out when some new changes are saved to the plist file. However, when the settings were read out later, they were back to their original values. I had been struggling for days to find out why, and finally I found that the plist file in the project bondle cannot be changed!

I resolved the issue by copying the plist file to the application sandbox supported folder. The plist file can be edited and saved there. After that, I come to my explanation: it may be a security reason that files within the app bundle cannot be changed.

I could copy the HTML file to outside of the bondle path and make changes there. What about other HTML sources and library files? It just defeats the language support naturally provided by the iOS framework if I have to find out or identify which language is supported, and then copy all those files from specific language subfolders out.

I knew there is another way to load an HTML string directly into WKWebView. The string can be changed with a parameter replacement. This would display HTML content. However, the same issue comes back to me again. How about linking other sources and library files if I load the view with a string? No path information from the string

Since I am using HTML technology, naturally I should find a way in HTML or js to inject common head settings into my loading HTML file.

Partial Working Solution

Within about a day of my post, I got two answers. One is using js to inject common settings from a js function. I tried it immediately. It did not work at first.

When I went back to my Q, my Q was marked as [losed] by a senior member of SO. The reason is that my working environment was not explained clearly. More explanation is required.

With [losed] status, no more answers are allowed. This actually turns many people away. The only way I could ask for help and get attention was to update my Q and add comments. As you can see, I have done several updates, and the Q is quite lengthy. Anyway, I think I have done enough to clarify my Q on SO.

If you read my Q, you will see a solution in it. Based on the only post's answer with codes, I made some changes, and took the meta setting for charset out of my common settings. It works now in my project, just as I expected, to inject the common settings into the head section.

Even though my solution is working, I still have questions about it, and I would like to see if there is any other better solution or advice on this issue.

Since SO is a member participation and support community, I need to get some people's help to turn off the [close] status. What is required is to have 2 more requests at the link of reopen, at the end of my Q.

References

• OS quetion: Anyway to include file in HTML for meta settings?
• As a prof that my iOS is a native app, see my app blog.

Read More...

Collapse...