The framework includes the ChildAware interface which comes with a powerful API.
It allows you to scope communication with (or between) dynamically available child nodes easily.
+In the next examples:
+SomeNode can host multiple child nodes: Child1, Child2, etc.SomeInteractor belongs to SomeNode and is passed as a Plugin
+ to itSomeInteractor extends the Interactor helper class from the framework:NodeLifecycleAware, which makes sure it will receive the onCreate callback
+ from the frameworkChildAware, which unlocks the DSL we'll see in the following
+ snippetsimport androidx.lifecycle.Lifecycle
+import com.bumble.appyx.core.children.whenChildAttached
+import com.bumble.appyx.core.children.whenChildrenAttached
+import com.bumble.appyx.core.clienthelper.interactor.Interactor
+
+
+class SomeInteractor : Interactor<SomeNode>() {
+
+ override fun onCreate(lifecycle: Lifecycle) {
+ lifecycle.subscribe(onCreate = {
+
+ // This lambda is executed every time a node of type Child1Node is attached:
+ whenChildAttached { commonLifecycle: Lifecycle, child1: Child1Node ->
+ // TODO:
+ // - establish communication with child1
+ // - use commonLifecycle for scoping
+ // - it will be capped by the lifecycles of child1 and the parent
+ }
+ })
+ }
+}
+import androidx.lifecycle.Lifecycle
+import com.bumble.appyx.core.children.whenChildAttached
+import com.bumble.appyx.core.children.whenChildrenAttached
+import com.bumble.appyx.core.clienthelper.interactor.Interactor
+
+
+class SomeInteractor : Interactor<SomeNode>() {
+
+ override fun onCreate(lifecycle: Lifecycle) {
+ lifecycle.subscribe(onCreate = {
+
+ // This lambda is executed every time these two nodes are attached at the same time:
+ whenChildrenAttached { commonLifecycle: Lifecycle, child1: Child1Node, child2: Child2Node ->
+ // TODO
+ // - establish communication between child1 & child2
+ // - use commonLifecycle for scoping
+ // - it will be capped by the lifecycles of child1, child2 and the parent
+ }
+ })
+ }
+}
+To retain objects during configuration change you can use the RetainedInstanceStore class.
The RetainedInstanceStore stores the objects within a singleton. The node manages whether the content should be removed by checking whether the Activity is being recreated due to a configuration change or not.
These are the following scenarios:
+- If the Activity is recreated: the retained instance is returned instead of a new instance.
+- If the Activity is destroyed: the retained instance is removed and disposed.
Here is an example of how you can use the RetainedInstanceStore:
import com.bumble.appyx.core.builder.Builder
+import com.bumble.appyx.core.modality.BuildContext
+import com.bumble.appyx.core.node.Node
+import com.bumble.appyx.core.store.getRetainedInstance
+import com.bumble.appyx.interop.rx2.store.getRetainedDisposable
+
+class RetainedInstancesBuilder : Builder<String>() {
+
+ override fun build(buildContext: BuildContext, payload: String): Node {
+ val retainedNonDisposable = buildContext.getRetainedInstance(
+ factory = { NonDisposableClass(payload) },
+ disposer = { feature.cleanUp() }
+ )
+ val retainedFeature = buildContext.getRetainedDisposable {
+ RetainedInstancesFeature(payload)
+ }
+
+ val view = RetainedInstancesViewImpl()
+ val interactor = RetainedInstancesInteractor(
+ feature = retainedFeature,
+ nonDisposable = retainedNonDisposable,
+ view = view
+ )
+
+ return RetainedInstancesNode(
+ buildContext = buildContext,
+ view = view,
+ plugins = listOf(interactor)
+ )
+ }
+}
+Nodes have their own lifecycles, directly using the related classes of androidx.lifecycle.
No node can be in a higher lifecycle state than any of its parents or the Android Activity it lives in.
+NavModel controls which children should be rendered on the screen and which should not with NavModel.screenState.
+The behaviour is customisable in BaseNavModel via OnScreenStateResolver.
When a NavElement of the node is marked as on-screen, its lifecycle follows the parent node's lifecycle.
+The rendering status does not affect it – the node might not be added to Compose view and still be in a RESUMED state.
When a NavElement of the node is marked as off-screen, the following might happen:
CREATED (or STOPPED) in case of ChildEntry.KeepMode.KEEP. ChildEntry.KeepMode.SUSPEND.ChildEntry.KeepMode settings can be configured for each ParentNode individually or globally via Appyx.defaultChildKeepMode.
When a node is removed completely from NavModel, it will be in DESTROYED state.
The lifecycle state can be affected by:
+Nodes and changing their on-screen status)An example demonstrating the above:
+
Note that NavModels might have their slight differences (e.g. whether their operations remove a Node only from the view, or completely destroy it).
In the case of the back stack:
+Push operation adds a new element and stashes the currently active one – the stashed one will be removed from the view & STOPPEDPop operation removes an element, the child Node will be DESTROYEDNodes are meant to be simple structural elements, and should be kept lean.
To keep the framework agnostic of any specific approach / pattern you want to use, there aren't any fixed parts. Rather, the Node offers an extension point using Plugins in its constructor:
abstract class Node(
+ buildContext: BuildContext,
+ val view: NodeView = EmptyNodeView,
+ plugins: List<Plugin> = emptyList() // <--
+)
+So what is a Plugin?
A Plugin is an empty interface extended by many actual ones:
interface Plugin
+interface NodeLifecycleAware : Plugin {
+ fun onCreate(lifecycle: Lifecycle) {}
+}
+
+fun interface Destroyable : Plugin {
+ fun destroy()
+}
+Sometimes you need to grab a reference to the component as a whole, either as an interface, or its implementation, the Node.
This will come especially handy when working with workflows.
+interface NodeAware : Plugin {
+ val node: Node<*>
+
+ fun init(node: Node<*>) {}
+}
+There are helper classes found in the library, so you don't have to implement the above interfaces, you can just use delegation:
+class SomeClass(
+ private val nodeAware: NodeAware = NodeAwareImpl()
+) : NodeAware by nodeAware {
+
+ fun foo() {
+ // [node] is an automatically available property coming from the NodeAware interface
+ // the reference is automatically set for you by the framework + the NodeAwareImpl class
+ // so you can use it right away:
+ node.doSomething()
+ }
+}
+⚠️ Note: the reference to node is set by Node automatically, and isn't available immediately after constructing your object, but only after the construction of the Node itself.
In case if you need to control navigation behaviour, you can use these plugins:
+interface UpNavigationHandler : Plugin {
+ fun handleUpNavigation(): Boolean = false
+}
+
+interface BackPressHandler : Plugin {
+ val onBackPressedCallback: OnBackPressedCallback? get() = null
+}
+UpNavigationHandler controls Node.navigateUp behaviour and allows to intercept its invocation.
BackPressHandler controls device back press behaviour via androidx.activity.OnBackPressedCallback.
+You can read more about it here.
⚠️ Note: OnBackPressedCallback are invoked in the following order:
+1. From children to parents. Render order of children matters! The last rendered child will be the first to handle back press.
+2. Direct order of plugins within a node. Plugins are invoked in order they appears in Node(plugins = ...) before the NavModel.
All plugins are designed to have empty {} default implementations (or other sensible defaults when a return value is defined), so it's convenient to implement them only if you need.
Don't forget to pass your Plugins to your Node:
internal class MyNode(
+ // ...
+ plugins: List<Plugins> = emptyList()
+ // ...
+) : Node<Nothing>(
+ // ...
+ plugins = plugins
+ // ...
+)
+⚠️ Note: plugins is a List, as the order matters here. All Plugin instances are invoked in the order they appear in the list.
As seen in Composable navigation, you can make NavModels composable.
To achieve this, Appyx offers the Node class as the structural element.
In many of the examples you'll see this panel as an illustration of a very simple Node – it has some local state (id, colour, and a counter).
If you launch the sample app in the :app module, you can also change its state (colour) by tapping it. Its counter is stepped automatically. This is to illustrate that it has its own state, persisted and restored.
You can think of a Node as a standalone component with:
@Composable viewParentNodes can have other Nodes as children. This means you can represent your whole application as a tree of Appyx nodes.
You can go as granular or as high-level as it fits you. This allows to keep the complexity low in individual Nodes by extracting responsibilities to children, as well as composing other components to build more complex functionality.
Nodes offer the structure – NavModels add dynamism to it.
Read more in Composable navigation
+Nodes have their own lifecycles, directly using the related classes of androidx.lifecycle.
Read more in Lifecycle
+React to dynamically added child nodes in the tree: ChildAware API
+A summary of Appyx's approach to structuring applications:
+Nodes with their own lifecycles and stateNavModelsNavModels