GitHub/Cicerone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #178 from adpops/master

Browse Source 
Edited Readme
This commit is contained in:
Konstantin
2023-05-15 13:35:24 +02:00
committed by GitHub
parent e210e45c36 bd9ac36efc
commit 9e1436a223
1 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+30 -30
View File
@@ -31,27 +31,27 @@
</tr> </tr>
</table> </table>
Cicerone (means - a guide, one who conducts sightseers) is a lightweight library that makes the navigation in an Android app easy. Cicerone (a guide who gives information about antiquities and places of interest to sightseers) is a lightweight library that makes the navigation in an Android app easy.
It was designed to be used with the MVP/MVVM/MVI patterns but will work great with any architecture. It was designed to be used with the MVP/MVVM/MVI patterns but will work great with any architecture.
## Main advantages ## Main advantages
+ is not tied to Fragments + Is not tied to Fragments
+ not a framework (very lightweight) + Not a framework (very lightweight)
+ short navigation calls (no builders) + Short navigation calls (no builders)
+ static typed checks for screen parameters! + Static typed checks for screen parameters!
+ lifecycle-safe! + Lifecycle-safe!
+ functionality is simple to extend + Functionality is simple to extend
+ suitable for Unit Testing + Suitable for Unit Testing
## Additional features ## Additional features
+ opening several screens inside single call (for example: deeplink) + Opening several screens inside single call (for example: deeplink)
+ provides `FragmentFactory` if it needed + Provides `FragmentFactory` if it needed
+ `add` or `replace` strategy for opening next screen (see `router.navigateTo` last parameter) + `add` or `replace` strategy for opening next screen (see `router.navigateTo` last parameter)
+ implementation of parallel navigation (Instagram like) + Implementation of parallel navigation (Instagram like)
+ predefined navigator ready for Single-Activity apps + Predefined navigator ready for Single-Activity apps
+ predefined navigator ready for setup transition animation + Predefined navigator ready for setup transition animation
## How to add ## How to add Cicerone to your application
Add the dependency in your build.gradle: Add the dependency in your build.gradle:
```kotlin ```kotlin
dependencies { dependencies {
@@ -79,10 +79,10 @@ class App : Application() {
} }
``` ```
## How it works? ## How does it work?
<img src="https://github.com/terrakok/Cicerone/blob/master/media/CiceroneDiagram.png" alt="CiceroneDiagram.png" width="800"/> <img src="https://github.com/terrakok/Cicerone/blob/master/media/CiceroneDiagram.png" alt="CiceroneDiagram.png" width="800"/>
Presenter calls navigation method of Router. The `Presenter` calls the navigation method of `Router`.
```kotlin ```kotlin
class SamplePresenter( class SamplePresenter(
@@ -99,11 +99,11 @@ class SamplePresenter(
} }
``` ```
Router converts the navigation call to the set of Commands and sends them to CommandBuffer. `Router` converts the navigation call to the set of commands and sends them to `CommandBuffer`.
CommandBuffer checks whether there are _"active"_ Navigator: `CommandBuffer` checks whether there are the `_"active"_ Navigator`:
- If yes, it passes the commands to the Navigator. Navigator will process them to achive the desired transition. - If yes, it passes the commands to the Navigator. `Navigator` will process them to achive the desired transition.
- If no, then CommandBuffer saves the commands in a queue, and will apply them as soon as new _"active"_ Navigator will appear. - If no, then `CommandBuffer` saves the commands in a queue, and will apply them as soon as a new `_"active"_ Navigator` will appear.
```kotlin ```kotlin
fun executeCommands(commands: Array<out Command>) { fun executeCommands(commands: Array<out Command>) {
@@ -111,10 +111,10 @@ fun executeCommands(commands: Array<out Command>) {
} }
``` ```
Navigator processes the navigation commands. Usually it is an anonymous class inside the Activity. `Navigator` processes the navigation commands. Usually it is an anonymous class inside `Activity`.
Activity provides Navigator to the CommandBuffer in _onResume_ and removes it in _onPause_. `Activity` provides `Navigator` to the `CommandBuffer` in `_onResume_` and removes it in `_onPause_`.
**Attention**: Use _onResumeFragments()_ with FragmentActivity ([more info](https://developer.android.com/reference/android/support/v4/app/FragmentActivity.html#onResume())) **Attention**: Use `_onResumeFragments()_` with `FragmentActivity` ([more info](https://developer.android.com/reference/android/support/v4/app/FragmentActivity.html#onResume()))
```kotlin ```kotlin
private val navigator = AppNavigator(this, R.id.container) private val navigator = AppNavigator(this, R.id.container)
@@ -131,7 +131,7 @@ override fun onPause() {
``` ```
## Navigation commands ## Navigation commands
This commands set will fulfill the needs of the most applications. But if you need something special - just add it! These commands will fulfill the needs of the most applications. But if you need something special - just add it!
+ Forward - Opens new screen + Forward - Opens new screen
![](https://github.com/terrakok/Cicerone/raw/master/media/forward_img.png) ![](https://github.com/terrakok/Cicerone/raw/master/media/forward_img.png)
+ Back - Rolls back the last transition + Back - Rolls back the last transition
@@ -148,7 +148,7 @@ To use, just provide it with the container and _FragmentManager_.
private val navigator = AppNavigator(this, R.id.container) private val navigator = AppNavigator(this, R.id.container)
``` ```
Custom navigator can be useful sometimes: A custom navigator can be useful sometimes:
```kotlin ```kotlin
private val navigator = object : AppNavigator(this, R.id.container) { private val navigator = object : AppNavigator(this, R.id.container) {
override fun setupFragmentTransaction( override fun setupFragmentTransaction(
@@ -168,7 +168,7 @@ private val navigator = object : AppNavigator(this, R.id.container) {
``` ```
## Screens ## Screens
Describe your screens as you like e.g. create Kotlin `object` with all application screens: Describe your screens as you like e.g. create a Kotlin `object` with all application screens:
```kotlin ```kotlin
object Screens { object Screens {
fun Main() = FragmentScreen { MainFragment() } fun Main() = FragmentScreen { MainFragment() }
@@ -208,12 +208,12 @@ fun onPhotoClick(photo: Bitmap) {
``` ```
## Sample ## Sample
To see how to add, initialize and use the library and predefined navigators see **sample project** To see how to add, initialize and use the library and predefined navigators see the **sample project**
(thank you [@Javernaut](https://github.com/Javernaut) for support new library version and migrate sample project to Kotlin!) (thank you [@Javernaut](https://github.com/Javernaut) for support new library version and migrate sample project to Kotlin!)
For more complex use case check out the [GitFox (Android GitLab client)](https://gitlab.com/terrakok/gitlab-client) For more complex use case check out the [GitFox (Android GitLab client)](https://gitlab.com/terrakok/gitlab-client)
## Applications with Cicerone inside ## Applications that use Cicerone
<a href="https://play.google.com/store/apps/details?id=ru.foodfox.client"><img src="https://play-lh.googleusercontent.com/gWYedIqy8QujCQOn0kzEIBEkGLBSpuKvFm-fMcfkWnJ1Oirtv847xAE4OyhAaohdcp5V=s360" width="64" /> Яндекс.Еда — доставка еды/продуктов. Food delivery</a><br> <a href="https://play.google.com/store/apps/details?id=ru.foodfox.client"><img src="https://play-lh.googleusercontent.com/gWYedIqy8QujCQOn0kzEIBEkGLBSpuKvFm-fMcfkWnJ1Oirtv847xAE4OyhAaohdcp5V=s360" width="64" /> Яндекс.Еда — доставка еды/продуктов. Food delivery</a><br>
<a href="https://play.google.com/store/apps/details?id=com.kms.me"><img src="https://play-lh.googleusercontent.com/IBzu0tlHd_amw2HbjBLOZiCfK-0tn0CnwkMdOd1toP23rdHUV-i7L2ViNKgIg687=s360" width="64" /> Kaspersky Internet Security</a><br> <a href="https://play.google.com/store/apps/details?id=com.kms.me"><img src="https://play-lh.googleusercontent.com/IBzu0tlHd_amw2HbjBLOZiCfK-0tn0CnwkMdOd1toP23rdHUV-i7L2ViNKgIg687=s360" width="64" /> Kaspersky Internet Security</a><br>
<a href="https://play.google.com/store/apps/details?id=com.deliveryclub"><img src="https://play-lh.googleusercontent.com/m6-gFunvj7aQD5fdv8EdJZBN5M4REIobTaPZPYS0K5Td7CNYnazN7fOKiPwwaY3hJw=s360" width="64" /> Delivery Club – Доставка еды и продуктов</a><br> <a href="https://play.google.com/store/apps/details?id=com.deliveryclub"><img src="https://play-lh.googleusercontent.com/m6-gFunvj7aQD5fdv8EdJZBN5M4REIobTaPZPYS0K5Td7CNYnazN7fOKiPwwaY3hJw=s360" width="64" /> Delivery Club – Доставка еды и продуктов</a><br>
@@ -228,8 +228,8 @@ For more complex use case check out the [GitFox (Android GitLab client)](https:/
<a href="https://play.google.com/store/apps/details?id=ru.zakaz.android"><img src="https://play-lh.googleusercontent.com/jj18yK2dB2MHZ_QdO21aXyznGXteIF2q4mgxY4ubLhFv9gwZqHVDeu1i2FmanS-0Furm=s360" width="64" /> Zakaz.ru</a><br> <a href="https://play.google.com/store/apps/details?id=ru.zakaz.android"><img src="https://play-lh.googleusercontent.com/jj18yK2dB2MHZ_QdO21aXyznGXteIF2q4mgxY4ubLhFv9gwZqHVDeu1i2FmanS-0Furm=s360" width="64" /> Zakaz.ru</a><br>
## Participants ## Participants
+ idea and code - Konstantin Tskhovrebov (@terrakok) + Idea and code - Konstantin Tskhovrebov (@terrakok)
+ architecture advice, documentation and publication - Vasili Chyrvon (@Jeevuz) + Architecture advice, documentation and publication - Vasili Chyrvon (@Jeevuz)
## License ## License
``` ```