Skip to content

Commit

Permalink
Review Doc after #839
Browse files Browse the repository at this point in the history
  • Loading branch information
EvaBS committed Jan 5, 2024
1 parent 786f2c5 commit 26c5cc7
Showing 1 changed file with 18 additions and 18 deletions.
36 changes: 18 additions & 18 deletions www/src/pages/docs/40_StoreCreation.md
Original file line number Diff line number Diff line change
Expand Up @@ -830,22 +830,22 @@ If you want your tracking to continue instead, just handle exceptions within the

### Use Store's Current Value Correctly - Bypass Complex Flow-Operations

Sometimes there is the need to access some `Store`'s current value in a safe but easy way. That is, why its API offers
a property called `current`, which allows exactly to safely get its value at that one moment of access.
Sometimes there is the need to access a `Store`'s current value in a safe but quick and easy way. That is why its API
offers a property called `current` which provides the store's value at the exact moment of access.

Typical use cases are the mapping of `Flow`s, often event based flows, that should be mapped to some store's content
or where the content is needed for some further processing.
Typical use cases are the mapping of `Flow`s, often event based flows which should be mapped to a store's
content. Sometimes the content is needed for further processing.

Consider some panel, that can be opened and closed by some button click. In order to toggle it, you must manipulate
some state holding store:
Consider a panel that can be opened and closed by a button click. In order to toggle it, you must manipulate
a state holding store:
```kotlin
val toggle = storeOf(false) // `false`-> closed, `true` -> open

button {
+"Toggle"
clicks.map { !toggle.current } handledBy toggle.update
// ^^^^^^^
// get current value of the store to process it inside some flow-mapping
// get current value of the store to process it inside a flow-mapping
}

// finally render the panel depending on the state
Expand All @@ -857,12 +857,12 @@ toggle.data.renderIf({ it }) {
```

The key aspect is found inside the `clicks`-event handling: The event itself is not really useful. It is just needed
to get some `Flow` that listens to the click events and emit new values each time a user clicks the button. But in order
to toggle the state, we need to access the store's value, where `current` comes into play!
to get a `Flow` that listens to the click events and emits new values each time a user clicks the button. But in order
to toggle the state, we need to access the store's value, which is where `current` comes into play.

But to solve this without the `current`-property, we would have to apply typical
To solve this without the `current`-property, we would have to apply typical
`Flow`-[combining functions](https://kotlinlang.org/docs/flow.html#composing-multiple-flows),
like `combine`, `flatMapLatest` and so on. So imagine a solution without `current`:
like `combine`, `flatMapLatest` and so on. Take a look at a possible solution without `current`:
```kotlin
button {
+"Toggle"
Expand All @@ -873,21 +873,21 @@ button {
This looks far more complicated and clutters the UI code.

::: warning
**Beware:** There are many situations, where using `current` is just false. Applying it in inappropriate situations
**Caution:** There are many situations where using `current` is just plainly wrong. Applying it in inappropriate situations
might lead to subtle and hard to find errors!

Never use `current` inside some `render`-function body for example!
Never use `current` inside a `render`-function body, for example.
:::

In order to use `current` in the right situations, just follow this rule of thumb:
In order to use `current` in the correct way only, just follow this rule of thumb:

::: info
Use `current` only in code blocks, that are executed within some **reactive** scope!
That is, only in some intermediate `Flow`-operations or inside some `Handler` code for example.
Use `current` only in code blocks which are executed within a **reactive** scope, meaning, only in intermediate
`Flow`-operations or inside a `Handler`'s code, for example.
:::

You can find typical examples for using `current` inside of the fritz2 [headless-components](/headless), for example
in `Listbox`'s implementation that deals with `KeyEvents`. Similar examples can be found in other headless components.
You can find typical examples for using `current` in the fritz2 [headless-components](/headless), for example
in `Listbox`'s implementation which deals with `KeyEvents`. Similar examples can be found in other headless components.

### EmittingHandler - Observer Pattern for Handlers

Expand Down

0 comments on commit 26c5cc7

Please sign in to comment.