From 75e0059dd6b2ef36d3a5b324f8f005b11cf028e7 Mon Sep 17 00:00:00 2001 From: Guillaume Lung Date: Wed, 21 Dec 2016 12:19:50 +0100 Subject: [PATCH] Update README.md (#89) Point out to the website. --- README.md | 142 +----------------------------------------------------- 1 file changed, 2 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index f6c5e5e..3419872 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,18 @@ # LightCycle -[![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0) [![Platform](https://img.shields.io/badge/platform-android-green.svg)](http://developer.android.com/index.html) +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.soundcloud.lightcycle/lightcycle-lib/badge.png)](https://maven-badges.herokuapp.com/maven-central/com.soundcloud.lightcycle/lightcycle-lib) [![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0) [![Platform](https://img.shields.io/badge/platform-android-green.svg)](http://developer.android.com/index.html) LightCycle is an Android library that helps break logic out of `Activity` and `Fragment` classes into small, self-contained components called LightCycles. Fields that are annotated `@LightCycle` and implement the LightCycle API within a `LightCycleActivity` or `LightCycleFragment` will be bound to that `Activity` or `Fragment` lifecycle. -## Usage - -```java -public class MyActivity extends LightCycleAppCompatActivity { - @LightCycle MyController controller = new MyController(); - - @Override - protected void setActivityContentView() { - setContentView(R.layout.main); - } -} -``` - -```java -public class MyController extends DefaultActivityLightCycle { - - @Override - public void onPause(MyActivity activity) { - // MyActivity was paused - } - - [...] - - @Override - public void onResume(MyActivity activity) { - // MyActivity was resumed - } -} -``` - -## Philosophy - -LightCycle lets self-contained classes respond to Android’s lifecycle events. This supports composition over inheritance and promotes components that follow the single responsibility principle. We believe it helps us write more readable, maintainable and testable code. It works particularly well alongside dependency injection. - -- `Activity` & `Fragment` classes: - - Inflate layouts and configure Android specifics - - Declare LightCycles -- A LightCycle component is responsible for an isolated chunk of logic (such as presentation, tracking etc.) - -A LightCycle doesn't know about other LightCycles. There is no guarantee for ordering when multiple LightCycles receive the same lifecycle callback. +For more information please see the [website](http://soundcloud.github.io/lightcycle/). ## Examples - [basic](https://github.com/soundcloud/lightcycle/tree/master/examples/basic) - ["real world"](https://github.com/soundcloud/lightcycle/tree/master/examples/real-world) -## Documentation - -### LightCycle - -There are 3 types of LightCycles - the API is comparable to the [`ActivityLifecycleCallbacks`](http://developer.android.com/reference/android/app/Application.ActivityLifecycleCallbacks.html) from the Android SDK: -- `ActivityLightCycle` -- `FragmentLightCycle` -- `SupportFragmentLightCycle` - -For convenience, default implementations are provided: -- `DefaultActivityLightCycle` -- `DefaultFragmentLightCycle` -- `DefaultSupportFragmentLightCycle` - -### Dispatcher - -This dispatches an `Activity` or `Fragment` lifecycle callback to attached LightCycles. The API defines a single `bind` method. See the `LightCycleDispatcher` interface. - -#### Built-in dispatchers - -Three types of dispatchers are provided: -- `ActivityLightCycleDispatcher` -- `FragmentLightCycleDispatcher` -- `SupportFragmentLightCycleDispatcher` - -Note: these built-in classes are both dispatchers and LightCycles, meaning that you can nest LightCycles. - -```java -public class MyActivity extends LightCycleAppCompatActivity { - @LightCycle MyController controller = new MyController(); - - @Override - protected void setActivityContentView() { - setContentView(R.layout.main); - } -} -``` - -```java -public class MyController extends ActivityLightCycleDispatcher { - @LightCycle MySubController1 controller = new MyController1(); - @LightCycle MySubController2 controller = new MyController2(); - - @Override - public void onCreate(Bundle savedInstanceState) { - [...] // <- specific init - super.onCreate(savedInstanceState) // <- call super to dispatch. - } -} -``` - -#### Provided base class dispatchers - -The following base activities are provided so far: -- `LightCycleActionBarActivity` -- `LightCycleAppCompatActivity` -- `LightCycleFragment` -- `LightCycleSupportFragment` - -#### Adding LightCycle to your own base `Activity` or `Fragment` - -/!\ Please, read carefully the following steps (item 2 in particular). - -To add LightCycles to your `MyBaseActivity`, your `Activity` must: -- Implement the `LightCycleDispatcher` interface. _Note: The processor needs to know the exact type being dispatched, so if your base activity is templated then the activities inheriting from it must explicitly `implements LightCycleDispatcher>`_ (for more details, refer to https://github.com/soundcloud/lightcycle/issues/49) -- Dispatch all the lifecycle methods -- Bind fields annotated `@LightCycle` with `LightCycles.bind(this)` - -The same technique applies for `Fragment`. - -```java -public class MyBaseActivity extends Activity implements LightCycleDispatcher> { - - private final ActivityLightCycleDispatcher lightCycleDispatcher; - - @Override - public void bind(ActivityLightCycle lightCycle) { - lightCycleDispatcher.bind(lightCycle); - } - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - LightCycles.bind(this); - lightCycleDispatcher.onCreate((MyBaseActivity) this, savedInstanceState); - } - - [...] - - @Override - protected void onDestroy() { - lightCycleDispatcher.onDestroy((MyBaseActivity) this); - super.onDestroy(); - } -} -``` - -See for example [LightCycleActionBarActivity](lightcycle-lib/src/main/java/com/soundcloud/lightcycle/LightCycleActionBarActivity.java) or [LightCycleSupportFragment](lightcycle-lib/src/main/java/com/soundcloud/lightcycle/LightCycleSupportFragment.java). - ## Build integration Gradle: