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).
| Main Goals | |
|---|---|
| 😅 | Safety: minimize bad coding practices as much as possible |
| 🔧 | Feature-Oriented: adding and maintaining features is easy and, yes, safe |
| 🔠 | Component-Oriented: each visual feature you want to add to your app is a Component (smart or dumb) |
| ✂️ | fine-grained Separation of Concerns, which means: |
| 👯 | Much less merge conflicts |
| 😎 | A better understanding of your code |
Smart components are composed of:
ComponentViewControllerComponentViewModelComponentDisplayable
(New in 0.19!) Dumb components are simply composed of a Displayable and do not have an associated ViewModel.
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.
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 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 represents a component who has a state defining its rendering:
- State is represented using
ComponentViewModel. - UI is represented using
ComponentDisplayable.
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
}
}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 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
}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 {
}
}Akane supports displaying collections of objects in UITableViews and UICollectionViews.
Please read the Collections.md documentation to know more.
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!
Akane supports installation via CocoaPods and Carthage.
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'Add github "akane/Akane" to your Cartfile.
In order to use Akane Bindings and Akane Collections, you should also append github "ReactiveKit/Bond".
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.
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.
Akane is released under the MIT License. Please see the LICENSE file for details.