OKit

Easy to use application framework for Swift, to create apps based on models and storyboards with (almost) no code.

Core Features:

• Models and Entities
• JSON storage (file, http)
• Partials (partitions)
• References
• Complex Bindings
• Invalidation
• Data and Images (incl. inline)
• Encryption
• Application Shell
• Slide-in menu
• Settings
• Face ID
• Protection + Timeout
• Theming (incl. dark theme)
• Backups (secured)
• Help Views
• Re-use cells
• Auto-key generation

Core Technologies:

• Storyboard: Application flow is designed with storyboards using model controllers and model controls
• Model: Models are named data object and inherit from Model
• Model Entity: Model entities are part of a model and inherit from ModelEntity
• Codable: Models and model entities are automatically (de)serialized using Codable protocol
• Context: Models and model entities can be used as context in model controllers and model controls
• Binding: Model controller and model control properties can be bound to model binding paths
• KVC: Key value coding is used to update model objects using @objc annotation
• Controller: Model controllers are enabled for bindings and inherit from ModelListTableController, ModelDetailTableController or subclasses
• Control: Model controls and model cells are enabled for bindings, where latter inherits from ModelTableCell or subclasses
• Inspectable: Model controllers and model control are extended with @IBInspectable properties, maintainable in Interface Builder

Usage

Installation: CocoaPods

OKit is available through CocoaPods. To install it, add the following lines to your Podfile:

  use_frameworks!
  pod 'OKit'

Reference Example: Bookshop

The full-fledged OKit example project Bookshop is available, showcasing every feature of the OKit framework.

Model

Model Definition

The model definition is based on Swift classes, inheriting from Model, possibly including nested entities inheriting from ModelEntity. Model implicitly is also a (root) Model Entity and inherits all binding functionality.

The following Model types exists:

• Model: Model is read/stored as JSON to filesystem into okit/data folder of document directory using model name with .json extension
• ModelTransient: Model is not read/stored (therefore handled transiently)
• ModelEncrypted: Model is read/stored as encrypted binary to filesystem into okit/data folder of document directory using model name with .json extension
• ModelHttp: Model is read/stored as JSON via HTTP to configured endpoint (endpoint URL can be configured in Info.plist with key OKitModelEndpointUrl)
• ModelEncryptedHttp: Model is read/stored as encrypted binary via HTTP to configured endpoint (endpoint URL can be configured in Info.plist with key OKitModelEndpointUrl)

Example:

@objc(Shop)
class Shop: Model, Codable {
    var id: String!
    var books: [Book] = []
}

@objc(Book)
class Book: ModelEntity, Codable {
    var id: String!
    var name: String = ""
    var date: Date = Date()
    var marked: Bool = false
    var icon: ModelImage?
    var authors: [Author] = []
}

@objc(Author)
class Author: ModelEntity, Codable {
    var id: String!
    var name: String = "<New Author>"
}

Explanations:

• @objc keyword shall be used, in order to allow dynamic instantiation and key-value-observing (KVO) by model controllers in Swift to support binding.
• Models and model entities that shall be de(serialized) to JSON must conform to Codable protocol
• Automatic JSON de(serialization) with Codable protocol does not work for inherited properties and need to be handled manually using Encoder and Decoder protocols
• Property var id: String! is filled automatically with a UUID by framework, and is mandatory for supporting references to the model entities

Model Registration

A model can be registered with the Model class and an optional name:

Model.initialize(window, secure: true) {
    self.shop = Model.register(Shop.self)
    self.catalog = Model.register(Catalog.self, "catalog")
}

If name is omitted, the model is registered as default model with the implicit name default. The registration shall be done in application:didFinishLaunchingWithOptions of AppDelegate. Model instances can be stored in the application context for later access.

Store Model

A model can be stored calling Model.store(...) on the model instance:

Model.store(self.shop)

Define Model State

In order to update all models together within a state, the following is registered:

Model.state() {
    Model.store(self.shop)
    Model.store(self.settings)
}

The state definition shall be done in application:didFinishLaunchingWithOptions of AppDelegate. This supports switching between encrypted/non-encrypted persistence and enables backup/import functionality.

Store Model State

The models state can be stored with:

Model.storeState()

Storing can be done e.g. in applicationDidEnterBackground of AppDelegate.

Restore Model State

The models state can be restored with:

Model.restoreState()

Storing can be done e.g. in applicationWillEnterForeground of AppDelegate.

Model Entity

Model entities define the properties and corresponding types to be stored. Model entities conformable to Codable are serialized to and deserialized from JSON.
Model entities can again recursively contain array, map, set or single references of model entities again. Binding is supported for model entities to controllers and controls.

Model Binding

UI controllers and UI controls can be bound to model entities (context) using the following binding definitions:

A complex binding example looks as follows:

m1>/a/$b/../c()/d[1]/e(/a)/[email protected]

To use special binding characters in a text string, those characters could be escaped by using the unicode representation. E.g. a comma is represented by \u{002c}.

Extension Function Binding

Functions and properties of core data types (e.g. Number, String, Date...) can be accessed within a binding:

Examples:

• authors.@count/suffixPlural(#entry): The number returned by @count is suffixed by a translatable and pluralized string.
• %Price: ,price/round2, %EUR: Multiple part binding adding the currency to the price value
• name/initial: String extension to return the first character of name
• date/formatRelativeDate: Date extension to format the date as relative date

Any Swift/Obj-C type can be extended with additional function and properties, and be used in binding expressions.

Model Entity Invalidation

Updating a model entity by binding or respective get, set, call functions programatically, triggers an invalidation mechanism (unless suppressInvalidate is specified). The invalidation notifies all bound controllers and controls for updating their content.

Model Entity Reuse

• ModelRef: Reuse model entity for storing entity references
• ModelData: Reuse model entity for storing arbitrary binary data. Data is stored separately according to model type (file, http, encrypted, transient) and read lazily
• ModelImage: Reuse model entity for storing model images. Image data is stored separately according to model type (file, http, encrypted, transient) and read lazily
• ModelInlineData: Reuse model entity for storing abitrary data. Data is stored inline into model entity JSON data
• ModelInlineImage: Reuse model entity for storing model images. Image data is stored inline into model entity JSON data
• ModelSettings: Reuse model entity for storing application model settings (e.g. theme, encryption, protection, ...)

Model Entity References

A model entity can be referenced, by using model entity library ModelRef.

Example:

@objc(Book)
class Book: ModelEntity, Codable {

    var id: String!
    var name: String = ""
    var author: ModelRef = ModelRef()
    
}

Model entity Book references the model entity Author by its key (ID). Author is therefore not stored as composition, but only the reference key is stored as foreign key in Book. Both entities must be in the same model entity partial (see next section) in order be able to resolve the reference lazily via property book.author.ref.

Model Entity Partials

A model partitioning (partials) can be established by inheriting from ModelPartial and by implementing the sync and store functions.

Example:

@objc(GroupDefer)
class GroupDefer: ModelPartial, Codable {
    var id: String!
    var name: String = "" {
        didSet {
            group?.name = name
        }
    }
    var group: Group? {
        get {
            return try? retrieve(Group.self)
        }
        set {
            assign(newValue)
        }
    }

    override func sync(entity: ModelEntity) {
        name = (entity as! Group).name
    }

    override func store() {
        try? store(group)
    }
}

@objc(Group)
class Group: ModelEntity, Codable {
    var id: String!
    var name: String = ""
}

Entity Group is resolved lazily within partial GroupDefer by reading/storing from a different URL. Function sync and didSet can be used to two-way sync properties available in both entities (e.g. name). Function store is called to store the partition data.

Model Entity Lifecycle Hooks

Managed Hook

Callback function managed can be overridden to implement lifecycle hook, when model entity is part of a context, i.e. parent entity or collection property of parent entity.

open dynamic func managed(_ context: Any? = nil) {
    // ...
}

Context can be the parent entity or a collection of the parent entity.

Unmanaged Hook

Callback function unmanaged can be overridden to implement lifecycle hook, when model entity is removed from a context.

open dynamic func unmanaged(_ context: Any? = nil) {
    // ...
}

Context can be the parent entity or a collection of the parent entity.

Storyboards/Controllers

User-Interfaces are built with storyboards, using standard View Controllers and Table View Controller by setting the following model classes as custom class:

• ModelListTableController: Represents a list controller of model entities
• ModelDetailTableController: Represents the details controller of a model entity
• ModelSelectionTableController: Displays a selection list controller for selecting single or multiple model entities
• ModelApplicationController: Represents the application environment for slide-in menu and protection support
• ModelMenuTableController: Represents the menu controller visible in the slide-in menu container
• ModelSettingsTableController: Represents the settings controller, to show model settings
• ModelBackupTableController: Represents the backup controller, to create and import backups
• ModelSecureBackupTableController: Represents the secure backup controller, to create and import secure backups

Model controllers have @IBInspectable properties defined, that are interpreted by Interface Builder to enhance the Attributes Inspector side pane.

Model controllers can inherit from ModelBaseTableController to get common binding functionality. Of course, each model controller can be further sub-classed for more use-case specific functionality.

Even usage of storyboards are recommended, UIs can also be built programmatically using the model controllers directly in code.

Storyboard Identifiers

Model Cell

Always use cell identifier model for dynamic prototype cells using model classes in storyboard.

Model Segue

Always use segue identifier model for segue between model table and model detail table in storyboard.

<abstract> Model Base Table

The model base table controller contains binding logic, etc., common to all model controllers.

The following @IBInspectable properties exist on the model table ModelBaseTableController:

Model List Table

The model list table controller ModelListTableController displays a list of model entities in a table view controller.

The following @IBInspectable properties exist on the model table ModelListTableController:

Model Detail Table

The model detail table controller ModelDetailTableController displays details of one model entity in a table view controller.

The following @IBInspectable properties exist on the model table ModelDetailTableController:

Model Selection Table (Model List Table)

The model selection table controller ModelSelectionTableController displays a list of model entities for selecting a single or multiple model entities in a table view controller.

The following @IBInspectable properties exist on the model table ModelSelectionTableController:

Model Application

The model application controller ModelApplicationController displays the application environment including content and slide-in menu area. It shows the model menu table and controls content display based on storyboard identifier.

The following @IBInspectable properties exist on the model table ModelApplicationController:

Protection

Application can be protected by Face ID, if activated in the model settings. When protection is active a protection cover is shown, to hide sensitive application data below, when leaving the application. The protection timeout specified in minutes, if a re-authentication with Face ID is needed to suspend protection cover.

Model Menu Table (Model List Table)

The model menu table controller ModelMenuTableController displays the menu in the model application controller. It is used to show content via storyboard identifier, depending on the menu selection.

The following @IBInspectable properties exist on the model table ModelMenuTableController:

Model Menu Bar Button Item

A UIBarButtonItem representing a menu button (incl. burger icon), that can be used out-of-the box.

Menu Settings Table (Model Detail Table)

The model settings table controller ModelSettingsTableController displays the model settings in the model application controller. Model detail table controller bindings against the ModelSettings entity shall use ModelSettingsTableController base class, as settings invalidation for theme, encryption, protection, etc. is then handled automatically.

Model Backup Table

The model backup table ModelBackupTableController displays a list of model backups. Furthermore, new backups can be created, or existing backups can be deleted. During backup all models are exported. Selecting a backup triggers the import of an existing backup, which overrides the current models after showing a confirmation popup.

Backups are stored in okit/backup folder of document directory.

Model Secure Backup Table

The model secure backup table ModelSecureBackupTableController enables a security popup, for entering the passcode for backup creation and backup import:

open func dataToBackup(sourceURL: URL, targetURL: URL, name: String, password: String) throws -> Bool

Function dataToBackup e.g. can be overridden in sub-class to create and copy a password-protected zip file.

open func backupToData(sourceURL: URL, targetURL: URL, name: String, password: String) throws -> Bool

Exports are temporarily stored in okit/export folder of document directory, to be further processed by backup logic. Function backupToData e.g. can be overridden in sub-class to extract password-protected zip file and copy to target.

Model Theming

A built-in theming concept is available. Central class is ModelTheme. There are two out-of-the box themes:

• ModelTheme.defaultTheme: iOS default theme
• ModelTheme.darkTheme: A default dark theme provided by framework

Custom Theme

Own custom themes can be created and registered in the ModelTheme class with function:

public static func register(theme: ModelTheme, name: String)

Themes can be set at the model application using model binding or by explicitly using func applyTheme(_ theme: ModelTheme?).

Model Controls

<abstract> Model View

Abstract base class for view-based controls, supporting model binding.

Model Help View

A help view can be connected to IBOutlet helpView for list and detail model controller. It handles displaying of modal help view and discarding. Help view content can be statically modeled in storyboard or dynamically by sub-classing model help view.

Model Label

Bindable representation of an UILabel The following @IBInspectable properties exist:

Model Button

Bindable representation of an UIButton The following @IBInspectable properties exist:

Model Bar Button Item

Bindable representation of an UIBarButtonItem. The following @IBInspectable properties exist:

Model Menu Bar Button Item

A UIBarButtonItem representing a menu button (inc. burger icon), that can be used out-of-the box.

Model Cells

Table Cell

Bindable representation of an UITableViewCell. The following @IBInspectable properties exist:

<abstract> Edit Cell (Table Cell)

Bindable representation of an editable UITableViewCell. The following @IBInspectable properties exist:

Switch Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UISwitch control. The following @IBInspectable properties exist:

Text Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UITextField control. The following @IBInspectable properties exist:

Date Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UIDatePicker control. The following @IBInspectable properties exist:

Multiline Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UITextView control. The following @IBInspectable properties exist:

Segment Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UISegmentedControl control. The following @IBInspectable properties exist:

Picker Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UIPickerView control. The following @IBInspectable properties exist:

Slider Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UISlider control. The following @IBInspectable properties exist:

Stepper Cell (Edit Cell)

Bindable representation of an UITableViewCell containing an UIStepper control. The following @IBInspectable properties exist:

Model Help View

A help view can be connected to IBOutlet helpView.

Model Inheritance

Any model entities, controllers and controller can be inherited and functions overridden to change default behavior, as most definitions are marked as open and public.