Skip to content

Commit bda7baf

Browse files
authored
Tweak 03_definingstate for typos and fluency
1 parent f90a7f2 commit bda7baf

File tree

1 file changed

+16
-16
lines changed

1 file changed

+16
-16
lines changed

packages/overmind-website/guides/beginner/03_definingstate.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Defining state
22

3-
Typically we think of the user interface as the application itself. But the user interface is really just there to allow a user to interact with the application. This interface can be anything. A browser window, native, sensors etc. it does not matter what the interface is, the application is still the same.
3+
Typically we think of the user interface as the application itself. But the user interface is really just there to allow a user to interact with the application. This interface can be anything. A browser window, native, sensors etc. It does not matter what the interface is, the application is still the same.
44

55
The mechanism of communicating from the application to the user interface is called **state**. A user interface is created by **transforming** the current state. To communicate from the user interface to the application an API is exposed, called **actions** in Overmind. Any interaction can trigger an action which changes the state, causing the application to notify the user interface about any updated state.
66

@@ -10,64 +10,64 @@ The mechanism of communicating from the application to the user interface is cal
1010

1111
In JavaScript we can create all sorts of abstractions to describe values, but in Overmind we lean on the core serializable values. These are **objects**, **arrays**, **strings**, **numbers**, **booleans** and **null**. Serializable values means that we can easily convert the state into a string and back again. This is fundamental for creating great developer experiences, passing state between client and server and other features. You can describe any application state with these core values.
1212

13-
Let us talk a litte bit about what each value helps us represent in our application.
13+
Let us talk a little bit about what each value helps us represent in our application.
1414

1515
### Naming
1616

17-
Each value needs to sit behind a name. Naming can be difficult, but we have some help. Even though we eventually do want to consume our application through a user interface we ideally want to avoid naming things specifically related to the environment where we show the user interface. Things like **page**, **tabs**, **modal** etc. is specific to a browser experience, maybe realted to a certain size. We want to avoid those names as they should not dictate what elements are to be used with the state, that is up to the user interface to decide later. So here are some generic terms to use instead:
17+
Each value needs to sit behind a name. Naming can be difficult, but we have some help. Even though we eventually do want to consume our application through a user interface we ideally want to avoid naming things specifically related to the environment where we show the user interface. Things like **page**, **tabs**, **modal** etc. are specific to a browser experience, maybe related to a certain size. We want to avoid those names as they should not dictate which elements are to be used with the state, that is up to the user interface to decide later. So here are some generic terms to use instead:
1818

1919
- page: **mode**
2020
- tabs: **sections**
2121
- modal: **editUser.active**
2222

2323
### Objects
2424

25-
The root value of your state tree is an object, because objects are great for holding other values. An object has keys that points to values. Most of these keys points to values that is the actual state of the application, but these keys can also represent domains of the application. A typical state structure could be:
25+
The root value of your state tree is an object, because objects are great for holding other values. An object has keys that point to values. Most of these keys point to values that are the actual state of the application, but these keys can also represent domains of the application. A typical state structure could be:
2626

2727
```marksy
2828
h(Example, { name: "guide/definingstate/objects" })
2929
```
3030

3131
### Arrays
3232

33-
Arrays are in a way similar to objects in the sense that they hold other values, but instead of keys pointing to values you have indexes. That means it is ideal for iteration. But more often than not objects are actually better at managing lists of values. We can actually do fine without arrays in our state. It is when we produce the actual user interface that we usually want arrays. You can learn more about this in the [managing lists](/guides/intermediate/01_managinglists) guide.
33+
Arrays are similar to objects in the sense that they hold other values, but instead of keys pointing to values you have indexes. That means it is ideal for iteration. But more often than not objects are actually better at managing lists of values. We can actually do fine without arrays in our state. It is when we produce the actual user interface that we usually want arrays. You can learn more about this in the [managing lists](/guides/intermediate/01_managinglists) guide.
3434

3535
### Strings
3636

37-
Strings are of course used to represent text values. Names, descriptions and what not. But strings are also used for ids, types, etc. Strings can be used as values to reference other values. This is an important part in structuring state. For example in our **objects** example above we chose to use an array to represent the modes, using an index to point to the current mode, but we could also do:
37+
Strings are of course used to represent text values. Names, descriptions and whatnot. But strings are also used for ids, types, etc. Strings can be used as values to reference other values. This is an important part in structuring state. For example in our **objects** example above we chose to use an array to represent the modes, using an index to point to the current mode, but we could also do:
3838

3939
```marksy
4040
h(Example, { name: "guide/definingstate/strings" })
4141
```
4242

43-
Now we are referencing the current mode with a string. In this scenario you would probably stick with the array, but it is important to highlight that objects allows you to reference things by string, while arrays reference by number.
43+
Now we are referencing the current mode with a string. In this scenario you would probably stick with the array, but it is important to highlight that objects allow you to reference things by string, while arrays reference by number.
4444

4545
### Numbers
4646

47-
Numbers of course represents things like counts, age, etc. But just like strings, they can also represent a reference to something in a list. Like we saw in our **objects** example, to define what the current mode of our application is, we can use a number. You could say that referencing things by number works very well when the value behind the number does not change. Our modes will most likely not change and that is why an array and referencing the current mode by number, is perfectly fine.
47+
Numbers of course represent things like counts, age, etc. But just like strings, they can also represent a reference to something in a list. Like we saw in our **objects** example, to define what the current mode of our application is, we can use a number. You could say that referencing things by number works very well when the value behind the number does not change. Our modes will most likely not change and that is why an array and referencing the current mode by number, is perfectly fine.
4848

4949
### Booleans
5050

51-
Are things loading or not, is the user logged in or not ? These are typical usages of boolean values. We use booleans to express that something is activated or not. We should not confuse this with **null**, which means "not existing". We should not use **null** in place of a boolean value. We have to use either `true` or `false`.
51+
Are things loading or not, is the user logged in or not? These are typical uses of boolean values. We use booleans to express that something is activated or not. We should not confuse this with **null**, which means "not existing". We should not use **null** in place of a boolean value. We have to use either `true` or `false`.
5252

5353
### Null
5454

55-
All values, with the exception of booleans, can also be **null**. Non existing. You can have a non existing object, array, string or number. That means if we have not selected a mode both the string version and number version would have the value **null**.
55+
All values, with the exception of booleans, can also be **null**. Non-existing. You can have a non-existing object, array, string or number. It means that if we haven't selected a mode, both the string version and number version would have the value **null**.
5656

5757
## Deriving state
5858

5959

6060
### Getter
6161

62-
A concept in Javascript called a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) allows you to intercept accessing a property in an object. A getter is just like a plain value, it can be added an removed at any point. Getters does **not** cache the result for that very reason, but whatever state they access is tracked.
62+
A concept in Javascript called a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) allows you to intercept accessing a property in an object. A getter is just like a plain value, it can be added or removed at any point. Getters do **not** cache the result for that very reason, but whatever state they access is tracked.
6363

6464
```marksy
6565
h(Example, { name: "guide/definingstate/getter" })
6666
```
6767

68-
### Cached gettter
68+
### Cached getter
6969

70-
When you need to do more heavy calculation or combine state from different parts ot the tree you can use a plain function instead. Overmind treats these functions like a **getter**, but the returned value is cached and they can also access the root state of the application. A simple example of this would be:
70+
When you need to do more heavy calculation or combine state from different parts of the tree you can use a plain function instead. Overmind treats these functions like a **getter**, but the returned value is cached and they can also access the root state of the application. A simple example of this would be:
7171

7272
```marksy
7373
h(Example, { name: "guide/definingstate/derived" })
@@ -85,7 +85,7 @@ The first argument of the function is the state the derived function is attached
8585
That means the function only runs when accessed and the depending state has changed since last access.
8686

8787
```marksy
88-
h(Notice, null, "Even though derived state is defined as functions you consume them as plain values. You do not have to call the derived function to get the value. Derived state can not be dynamically added. They have to be defined and live in the tree from start to end of your application lifecycle")
88+
h(Notice, null, "Even though derived state is defined as functions you consume them as plain values. You do not have to call the derived function to get the value. Derived state can not be dynamically added. They have to be defined and live in the tree from start to end of your application lifecycle.")
8989
```
9090

9191
### Dynamic getter
@@ -98,15 +98,15 @@ h(Example, { name: "guide/definingstate/derived_passvalue" })
9898

9999
## References
100100

101-
When you add objects and arrays to your state tree, they are labeled with an "address" in the tree. That means if you try to add the same object or array in multiple spots in the tree you will get an error, as they can not have multiple addresses. Typically this indicates that you rather want to create a references to an existing object or array.
101+
When you add objects and arrays to your state tree, they are labeled with an "address" in the tree. That means if you try to add the same object or array in multiple spots in the tree you will get an error, as they can not have multiple addresses. Typically this indicates that you'd rather want to create a reference to an existing object or array.
102102

103103
So this is an example of how you would **not** want to do it:
104104

105105
```marksy
106106
h(Example, { name: "guide/definingstate/reference" })
107107
```
108108

109-
You rather change a reference to the user and for example use a **getter** to grab the actual user:
109+
You'd rather have a reference to the user id, and for example use a **getter** to grab the actual user:
110110

111111
```marksy
112112
h(Example, { name: "guide/definingstate/reference_correct" })

0 commit comments

Comments
 (0)