Akane

Akane is a iOS framework that helps you building better native apps by adopting an MVVM design pattern.

Head up to our example if you want to see a framework real use-case.

NOTE: Current version (0.30) is in beta. Click here if you want documentation for latest stable release (0.20.0).

Smart components are composed of:

• ComponentViewController
• ComponentViewModel
• ComponentDisplayable

(New in 0.19!) Dumb components are simply composed of a Displayable and do not have an associated ViewModel.

Why Akane, Or MVVM versus iOS MVC

iOS developers tend to write all their code into a unique and dedicated ViewController class. While this may have been OK some years ago, today's app codebases grow bigger and bigger. Maintaining a single, huge, ViewController file is a dangerous operation which often results in unpredictable side effects.

Akane makes you split your code into small components which are composed of multiple classes.

Model

The Model is the layer containing the classes that model your application business.

Songs, Movies, Books: all those classes or structs belong to this layer. They should contain no reference to any UIKit or Akane component.

struct User {
  enum Title: String {
    case sir
    case master
  }

  let username: String
  let title: Title
}

Dumb component

Dumb component is not bound to a specific state but can still be updated with raw data.

It is represented by Displayable protocol.

class UserView: UIView, Displayable {
   @IBOutlet var title: UILabel!

   func bindings(_ observer: ViewObserver, params user: User) {
     self.title = UserFullNameConverter().convert(user)
   }
}

Smart component

Smart component represents a component who has a state defining its rendering:

• State is represented using ComponentViewModel.
• UI is represented using ComponentDisplayable.

ViewModel

The ViewModel is where all your business logic should be implemented.

Please, Keep it agnostic: no reference to any View or ViewController should be present in your ViewModel. Also, Prefer ViewModel composition over inheritance: split your code into multiple ViewModel, each one dealing with one business case and then create another ViewModel to aggregate all those logics.

import Akane

class UserViewModel : ComponentViewModel {
  let user: Observable<User>?
  var disconnect: Command! = nil

  init(user: User) {
    self.user = Observable(user)
    self.disconnect = RelayCommand() { [unowned self] in
      self.user.next(nil)
    }
  }

  func isConnected() -> Bool {
    return self.user != nil
  }
}

ComponentDisplayable

Data flow between a ViewModel and its ComponentDisplayable is bidirectional:

• View <- ViewModel for data, through bindings
• View -> ViewModel for actions, through commands: for instance, send a message or order a product.

import Akane

class LoggedUserView : UIView, ComponentDisplayable {
  @IBOutlet var userView: UserView!
  @IBOutlet var buttonDisconnect: UIButton!

  func bindings(observer: ViewObserver, params viewModel: UserViewModel) {
    observer.observe(viewModel.user).bind(to: self.userView)

    // bind 'disconnect' command with 'buttonDisconnect'
    observer.observe(viewModel.disconnect)
            .bind(to: self.buttonDisconnect)
  }
}

ComponentController

ComponentController protocol, makes the link between ComponentViewModel and its ComponentDisplayable.

Pass your ComponentViewModel to your ViewController to bind it to its view. You'll also need to declare your ComponentDisplayable as being Wrapped.

class LoggedUserViewController : UIViewController, ComponentController {
  typealias ViewType = LoggedUserView

  func didLoadComponent() {
    print("User component loaded")
    // here you can access self.viewModel
  }
}

extension LoggedUserView : Wrapped {
  typealias Wrapper = LoggedUserViewController
}

SceneController

ComponentController is unable to receive a ComponentViewModel from the "outside". So how to initialize a view hierarchy when, say, you push a view controller? That's the role of SceneController.

class HomeViewController : UIViewController, SceneController {
  typealias ViewType = HomeView
}

class AppDelegate {
  let context = MyContext() // In 0.30 beta, you have to create your own custom Context class

  application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject : AnyObject]?) -> Bool {  
    let homeViewController = self.window.rootViewController as! HomeViewController
    homeViewController.renderScene(HomeViewModel(), context: self.context)

    return true
  }

  class MyContext : Context {
  }
}

Advanced usage

Collections

Akane supports displaying collections of objects in UITableViews and UICollectionViews. Please read the Collections.md documentation to know more.

Navbar

Navbars like views can be customized in Akane. All you have to do is to create a (Component)Displayable class and bind it to your navbar. Sounds complicated? Head over the example to see how you can do it easily!

Installation

Akane supports installation via CocoaPods and Carthage.

CocoaPods

pod 'Akane'

Akane builds on top of Bond for managing bindings. If you do want to use your own library (like RxSwift), you can use Akane core only:

pod 'Akane/Core'

Carthage

Add github "akane/Akane" to your Cartfile. In order to use Akane Bindings and Akane Collections, you should also append github "ReactiveKit/Bond".

United We Stand

Akane works great by itself but is even better when combined with our other tools:

• Gaikan, declarative view styling in Swift. Inspired by CSS modules.
• Magellan, routing solution to decouple UI from navigation logic.

Contributing

This project was first developed by Xebia IT Architects and has been open-sourced since. We are committed to keeping on working and investing our time in Akane.

We encourage the community to contribute to the project by opening tickets and/or pull requests.

License

Akane is released under the MIT License. Please see the LICENSE file for details.