** THIS REPO IS DEPRECATED AND IS NO LONGER BEING ACTIVELY MAINTAINED **
Ferro evolved into modules core-ui
, core-mvp
, mvp-dialog
, mvp-widjet
Surf Android Standard repository (Documentation in Russian). It contains modules, which is used for developing Android projects by mobile studio Surf.
Ferro
Simple and powerful MVP library for Android
Ferro elegantly solves two age-old problems of Android Framework related to configuration changes:
- restore screen's data
- managing background tasks
First problem is solved using permanent presenter, second - using freezing rx events (Observable doesn't unsubscribe). Also new feature was added - Ferro can freeze rx event when screen becomes invisible, and defreeze it when screen goes to foreground.
The schematic work of ferro:
Ferro is divided into 3 layers, each of one adds behavior to the previous. So you can use only part of Ferro, if you want.
The first layer:
ferro-core
This library contains base classes for Activity and Fragment (PSSActivity, PSSFragmentV4
, PSS - persistent screen scope). For each activity and fragment, based on this classes, will be created PersistentScreenScope
. You can get it by calling the method PSSActivity#getPersistentScreenScope
or PSSFragmentV4#getPersistentScreenScope
. This object isn't destroyed when configuration changed, it is only destroyed when screen is finally destroyed (e.g. after call Activity#finish()
). You can add listener, which will be called when PersistentScreenScope
destroyed. It has methods for storing and getting objects. In reality, PersistentScreenScope
is actually a retained Fragment without view.
This mechanism is perfect for storing a presenter, that is done in the next extention:
ferro-mvp
This library contains base classes for view, presenter and screen component. For each screen you need to extend ScreenComponent
, MvpPresenter
and MvpActivityView
or MvpFragmentV4View
.
The ScreenComponent
will be saved in PersistentScreenScope
and reused when view recreated. In method ScreenComponent#inject(view)
you need to insert presenter to the view. The easiest way to do it is to use dagger component as ScreenComponent
. Due to this mechanism presenter is reused after configuration change.
Method MvpPresenter#onLoad(viewRecreated)
will be called, when view is ready. Boolean parameter viewRecreated
means that view is recreated after configuration change. You should show previously loaded data via this method, it data exists.
In MvpActivityView
you should override method #onCreate()
with parameter viewRecreated
instead of default method #onCreate()
. Same for MvpFragmentV4View
and onActivityCreated
method.
If you use Dagger, this library contains two scope annotations @PerApplication
and @PerScreen
. It also contains ActivityProvider
and FragmentProvider
, which can be used for getting access to Activity or Fragment inside objects, provided by Dagger screen component (e.g. inside Navigator class).
It's lifecycle of screen's objects:
The next extention adds freeze logic for Rx events:
ferro-mvp-rx
Class MvpRxPesenter
contains freeze logic, scematic work of which shown in gif above. This class should be extended instead of MvpPresenter
.
If you subscribe to Observable
via one of MvpRxPesenter#subscribe()
methods, all rx events (onNext, onError, onComplete) would be frozen when view destroyed and unfrozen when view recreated. If option freezeEventOnPause
is enabled (it is enabled by default), all Rx events would be also frozen when screen is paused and unfrozen when screen is resumed.
When screen is finally destroyed, all subscriptions would be automatically unsubscribed.
ferro-rx
This library contains rx operators (ObservableOperatorFreeze
, MaybeOperatorFreeze
, SingleOperatorFreeze
, CompletableOperatorFreeze
, FlowableOperatorFreeze
for RxJava2 and OperatorFreeze
for RxJava1), which contains freeze logic. To apply it, you should pass this operator in method Observable#lift()
.
Conclusion
Nobody likes to do the basic logic of the project dependent on third-party libraries. So, the Ferro is, generally speaking, set of simple ideas, and you can create you own base classes by using this ideas.
Dependency
repositories {
jcenter()
}
dependencies {
//for use the full ferro (still not support RxJava2)
compile 'com.agna.ferro:ferro-mvp-rx:1.1.2'
//for use the part of ferro
compile 'com.agna.ferro:ferro-core:1.1.2'
compile 'com.agna.ferro:ferro-mvp:1.1.2'
compile 'com.agna.ferro:ferro-rx:1.0.2'
//or if you use RxJava2
compile 'com.agna.ferro:ferro-rx:2.0.0'
}
License
Copyright 2016 Maxim Tuev
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.