Skip to content

Commit

Permalink
ie/eg
Browse files Browse the repository at this point in the history
  • Loading branch information
blimmer authored and floodfx committed Oct 18, 2022
1 parent 60b3d52 commit 7b78afc
Show file tree
Hide file tree
Showing 28 changed files with 74 additions and 75 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ export const counterLiveView = createLiveView<
{ count: number }, // Define LiveView Context / State
{ type: "increment" } | { type: "decrement" } // Define LiveView Events
>({
// Setup / initialize the LiveView Context (i.e. set count to 0)
// Setup / initialize the LiveView Context (i.e., set count to 0)
mount: (socket) => {
socket.assign({ count: 0 });
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ export const dashboardLiveView = createLiveView<
>({
mount: (socket) => {
if (socket.connected) {
// only start repeating if the socket is connected (i.e. websocket is connected)
// only start repeating if the socket is connected (i.e., websocket is connected)
socket.repeat(() => {
// send the tick event to `handleInfo` every second
socket.sendInfo({ type: "tick" });
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ export const searchLiveView = createLiveView<
// Define LiveView Infos
{ type: "doSearch"; search: string }
>({
// Setup / initialize the LiveView Context (i.e. set search to "" and results to [])
// Setup / initialize the LiveView Context (i.e., set search to "" and results to [])
mount: (socket) => {
socket.assign({ search: "", results: [] });
},
Expand Down Expand Up @@ -88,7 +88,7 @@ function renderResults(results: string[], loading: boolean) {
`handleEvent` method is called with the `search` event.
- The `handleEvent` method then updates the `context` with the search text, sets `loading` to `true`, and sends a
`doSearch` info event to the `handleInfo` method.
- The `handleInfo` method then performs the search asynchronously (i.e. _it doesn't block rendering from the
- The `handleInfo` method then performs the search asynchronously (i.e., _it doesn't block rendering from the
`handleEvent`_).
- When the search is completed `handleInfo` and updates the results in the context and sets `loading` to `false`.
Updating the context causes the `render` method to be called again, which renders the search results.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar_position: 6
`handleInfo` is how server-side events (a.k.a `Info`) are handled. These server-side events are initiated by processes
that are happening on the server for example: database updates, background jobs, pub/sub messages, or some other
asynchronous process. Just like `handleEvent` and `handleParams`, `handleInfo` is automatically passed the `info` event
(i.e. server event) along with the `socket` and can use it to manipulate the `context` of the LiveView or otherwise
(i.e., server event) along with the `socket` and can use it to manipulate the `context` of the LiveView or otherwise
respond to the `info` messages it receives.

## `handleInfo` Signature
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ renders:
the LiveView changes. `handleParams` allows developers to access the full `URL` of the LiveView including the `host`,
`path`, `hash`, `pathname`, etc, and then update the `context` of the `socket` or otherwise respond to data in the `URL`.

:::note Worth noting that the http server (e.g. express or oak) handles the routing of the browser to this LiveView. This
:::note Worth noting that the http server (e.g., express or oak) handles the routing of the browser to this LiveView. This
means that changes in the `URL` for `handleParams` are typically search parameters or hash changes. Changing the host
and/or path of a URL will typically mean the server routes you to a different LiveView (if one exists at that host and
path). :::
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ export const counterLiveView = createLiveView<
{ count: number }, // Define LiveView Context / State
{ type: "increment" } | { type: "decrement" } // Define LiveView Events
>({
// Setup / initialize the LiveView Context (i.e. set count to 0)
// Setup / initialize the LiveView Context (i.e., set count to 0)
mount: (socket) => {
socket.assign({ count: 0 });
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ export const counterLiveView = createLiveView<
{ count: number }, // Define LiveView Context / State
{ type: "increment" } | { type: "decrement" } // Define LiveView Events
>({
// Setup / initialize the LiveView Context (i.e. set count to 0)
// Setup / initialize the LiveView Context (i.e., set count to 0)
mount: (socket) => {
socket.assign({ count: 0 });
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ export const counterLiveView = createLiveView<
{ count: number }, // Define LiveView Context / State
{ type: "increment" } | { type: "decrement" } // Define LiveView Events
>({
// Setup / initialize the LiveView Context (i.e. set count to 0)
// Setup / initialize the LiveView Context (i.e., set count to 0)
mount: (socket) => {
socket.assign({ count: 0 });
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@ sidebar_position: 2

# LiveViewSocket API - Context

The "context" of a LiveView is the current state of the LiveView. One way to think of a LiveView as a set of methods
that handle events, read and write the context, and render a view based on the data present in the context. Obviously,
The "context" of a LiveView is the current state of the LiveView. One way to think of a LiveView is as a set of methods
that handle events, read and write the context, and render a view based on the data in the context. Obviously,
properties and methods that manipulate the context are very important to a LiveView.

## Context Properties and Methods on the `LiveViewSocket`

There are three parts of the `LiveViewSocket` that are used to manipulate the context:
Three parts of the `LiveViewSocket` are used to manipulate the context:

| Name | Description |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context` (property, read-only) | The current context (i.e. state) of the LiveView |
| `assign(context:Partial<TContext>):void;` | Update the context (i.e. state) of the LiveView |
| `context` (property, read-only) | The current context (i.e., state) of the LiveView |
| `assign(context:Partial<TContext>):void;` | Update the context (i.e., state) of the LiveView |
| `tempAssign(context:Partial<TContext>):void;` | Marks any set properties as temporary and will be reset to the given value after the next render cycle. Typically used to ensure large but infrequently updated values are not kept in memory. |

## Details
Expand All @@ -25,12 +25,12 @@ The `assign` method is used to update the state of the LiveView and the `context
the LiveView.

```ts
// Update the context (i.e. current state) of the `LiveView`
// Update the context (i.e., current state) of the `LiveView`
socket.assign({ foo: "bar" });
```

```ts
// Read the context (i.e. current state) of the `LiveView`
// Read the context (i.e., current state) of the `LiveView`
if (socket.context.foo === "baz") {
// do something
}
Expand All @@ -40,7 +40,7 @@ const { foo } = socket.context;

## Context Type Annotations

When creating a `LiveView` developers can provide a type annotation for `TContext` which describes the "shape" of the
When creating a `LiveView`, developers can provide a type annotation for `TContext` which describes the "shape" of the
context for that LiveView. This is useful for providing type safety and autocomplete for the context (in Typescript).

```ts
Expand All @@ -56,7 +56,7 @@ const myLiveView = createLiveView<{foo: string}>(
)
```

You can type the Context inline as above or you can define the context type first and then use it to as a type
You can type the Context inline as above or you can define the context type first and then use it as a type
annotation:

```ts
Expand All @@ -74,9 +74,9 @@ The `context` of a LiveView is persisted on the server (in memory by default) wh
## Temporary Data for Context

Sometimes you want to add data to a `context` that is temporary &mdash; that is, only added to the context for one
"render cycle". There is a method called `socket.tempAssign` which allows a developer to tell **LiveViewJS** to set a
"render cycle". There is a method called `socket.tempAssign` that allows a developer to tell **LiveViewJS** to set a
`context` property to a given value after the render cycle. Typically this is used for large objects or collections that
don't change often and therefore probabaly don't need to be stored in memory (e.g. collection of users or messages,
don't change often and therefore probably don't need to be stored in memory (e.g., collection of users or messages,
etc).

```ts
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ const myLiveView = createLiveView<MyContext, MyEvents, MyInfo>(
)
```

`socket.sendInfo` can just take a type as a string for cases where there isn't additional information passed along with
`socket.sendInfo` can take a type as a string for cases where there isn't additional information passed along with
the message.

```ts
Expand All @@ -72,4 +72,4 @@ socket.sendInfo("refresh");
delivered to `handleInfo`. This is useful for cases where a LiveView needs to receive updates from another process or
user.

You can provide the type annotation for messages you expect to receive from a pub/sub topic as well to.
You can provide the type annotation for messages you expect to receive from a pub/sub topic as well.
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@ sidebar_position: 6

# LiveViewSocket API - Misc

There are a few other methods and properties that are available on the `LiveViewSocket` object that we haven't covered
yet.
A few other methods and properties are available on the LiveViewSocket object that we haven't covered yet.

## LiveViewSocket Properties and Methods

Expand All @@ -26,7 +25,7 @@ created. It is useful for debugging and logging purposes.

The `connected` property is a boolean that indicates whether the LiveView is connected to a websocket or not. If the
LiveView is connected to a websocket, then the value will be `true`. If the LiveView is not connected to a websocket
(i.e. executing an HTTP request), then the value will be `false`. This is useful for executing logic based on whether
(i.e., executing an HTTP request), then the value will be `false`. This is useful for executing logic based on whether
the LiveView has completed the initial websocket connection or not. For example:

```ts
Expand All @@ -43,7 +42,7 @@ if (socket.connected) {
LiveViewJS provides a `live_title_tag` helper that enables LiveViews to update the `<title>` tag of the page
dynamically. This is useful for LiveViews that need to update the page title based on the current state of the LiveView.
For example, a LiveView may want to update the title to include the details of the item being viewed. The `pageTitle`
method works in partnership with the `live_title_tag` to enabled dynamic page titles. `live_title_tag` is usually used
method works in partnership with the `live_title_tag` to enable dynamic page titles. `live_title_tag` is usually used
in the `LiveViewHtmlPageTemplate` template. For example:

```ts {14}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ the LiveView.
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pushEvent(pushEvent: AnyLivePushEvent): void;` | Pushes and event (possibly with data) from the server to the client. Requires either a `window.addEventListener` defined for that event or a client `Hook` to be defined and to be listening for the event via `this.handleEvent` callback. |
| `pushPatch(path: string, params?: URLSearchParams, replaceHistory?: boolean): Promise<void>;` | Updates the LiveView's browser URL with the given path and query parameters. |
| `pushRedirect(path: string, params?: URLSearchParams, replaceHistory?: boolean): Promise<void>;` | Shutdowns the current LiveView and loads another LiveView in its place without reloading the whole page (i.e. making a full HTTP request). Can be used to remount the current LiveView if need be. Use `pushPatch` to update the current LiveView without unloading and remounting. |
| `pushRedirect(path: string, params?: URLSearchParams, replaceHistory?: boolean): Promise<void>;` | Shutdowns the current LiveView and loads another LiveView in its place without reloading the whole page (i.e., making a full HTTP request). Can be used to remount the current LiveView if need be. Use `pushPatch` to update the current LiveView without unloading and remounting. |

## Pushing Events

An event is any JSON object with a `type: string` property and optionally any other key/value pairs. e.g.:
An event is any JSON object with a `type: string` property and optionally any other key/value pairs. e.g., :

```ts
{
Expand Down Expand Up @@ -69,7 +69,7 @@ The `LiveViewSocket` has two methods for updating the URL of the LiveView:

- `pushPatch` - Updates the LiveView's browser URL with the given path and query parameters.
- `pushRedirect` - Shutdowns the current LiveView and loads another LiveView in its place without reloading the whole
page (i.e. making a full HTTP request). Can be used to remount the current LiveView if need be.
page (i.e., making a full HTTP request). Can be used to remount the current LiveView if need be.

### `pushPatch` Example

Expand All @@ -89,4 +89,4 @@ socket.pushRedirect("/foo", new URLSearchParams({ bar: "baz" }));
```

`pushRedirect` will cause the current LiveView to be shutdown and a new LiveView to be loaded at the given path and
query parameters **without reloading the whole page** (i.e. making a full HTTP request).
query parameters **without reloading the whole page** (i.e., making a full HTTP request).
Loading

0 comments on commit 7b78afc

Please sign in to comment.