The Hero
architecture for iOS is a way to avoid large UIViewController
implementations and simultaneously separate the responsibilities. This separation is achieved by creating modules and workflows.
Each component of a module has a specific job.
The View Layer
is responsable for displaying what the user sees. It takes all of the users inputs, directs it to the Coordinator
and displays its outputs.
No database entities shall be used in this component. Only use PONSO
s (Plain Old NSObject) to give the view data to display.
The ViewController implements the ViewInput
protocol to handle view updates and optionally the ViewDelegate
.
- (void)updateSuperHeroProfile:(HEROProfilePonso*)profile;
The Router
component is a module's connection to a workflow. No database entities or PONSO
s shall be used in this component.
Use this component to connect to a workflow using the WorkflowInput
which has to be implemented by the chosen workflow.
The Router
component implements a single protocol:
RouterInput
- (void)didFinishEditingSuperHeroOnRouter:(HEROBaseRouter*)router;
The Coordinator
is an abstraction layer separating the view layer, use case and the router from each other. It contains no logic.
It implements 3 protocols:
ViewOutput
UseCaseOutput
RouterOutput
- (void)favoritedSuperHero:(HEROProfilePonso*)profile;
The UseCase
component is responsable for the business logic of your app.
Use this component to create your PONSO
(Plain Old NSObject) from your entities or update the entities using new data. It also responds, saves or handles user input, and sends update messages to the Coordinator
using the UseCaseOutput
protocol.
A use case implements a single protocol: UseCaseInput
.
- (void)favoritedSuperHero:(HEROProfilePonso*)profile;
- Xcode 9+
- iOS 9+
HeroArchitecture is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'HeroArchitecture'
This pod provides the base implementation for the Hero
architecture. These classes are needed to provide you with a quick and easy way to build your next app using the Hero
architecture.
The Hero
architecture is based on modules, which are defined by use cases, and workflows to determine the next screen/workflow.
There are two options to create modules based on this pod:
- Automatically generate a module using 'Generamba'
- Manually subclass each component
This is the fastest way to create a Hero
module. You can use the provided templates or create your own template.
Run the command gem install generamba
.
To setup Generamba
simply run the command generamba setup
and follow the steps.
Open the Rambafile
and add the following lines:
# a shared template catalog
catalogs:
- 'https://github.com/fluidmobile/heroTemplates'
# add template by name
templates:
- {name: HeroModule}
After adding the template source run the command generamba template install
to install the template.
Once Generamba
is set up correctly just run the command generamba gen [MODULE_NAME] [TEMPLATE_NAME]
to create your module from the template.
generamba gen Login HeroModule
Creating a workflow can be done the same way. However if your module has a workflow you need to add the router to workflow protocol manually.
If you choose to create your modules manually, you have to subclass these classes to create a module:
- View Layer
HEROBaseViewController
HEROBaseView
- Coordinator
HEROBaseCoordinator
- Router
HEROBaseRouter
- UseCase
HEROBaseUsecase
Additionally you need to add a single header file to declare your View-, Router-, UseCase-Inputs and Output protocols and override the base classes base protocol methods.
Creating a workflow can be done the same way. However if your module has a workflow you need to add the router to workflow protocol manually.
Detailed documentation is available here.
To run the example project, clone the repo, and run pod install
from the Example directory first.
fluidmobile GmbH, hello@fluidmobile.de
HeroArchitecture is available under the MIT license. See the LICENSE file for more info.