-
Notifications
You must be signed in to change notification settings - Fork 293
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Build MVP docs & examples (closes #9)
- Loading branch information
1 parent
d8e8c57
commit d7ef69c
Showing
19 changed files
with
315 additions
and
138 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,55 @@ | ||
# Components | ||
|
||
Please read [Getting Started](../getting_started.md) before this as it explains the basics of components. This page provides an in-depth explanation of the different types of components in Mesop. | ||
|
||
## Kinds of components | ||
|
||
### Native components | ||
|
||
Native components are components implemented using Angular/Javascript. Many of these components wrap [Angular Material components](https://material.angular.io/components/). Other components are simple wrappers around DOM elements. | ||
|
||
If you have a use case that's not supported by the existing native components, please [file an issue on GitHub](https://github.com/google/mesop/issues/new) to explain your use case. Given our limited bandwidth, we may not be able to build it soon, but in the future, we will enable Mesop developers to build their own custom native components. | ||
|
||
### User-defined components | ||
|
||
User-defined components are essentially Python functions which call other components, which can be native components or other user-defined components. It's very easy to write your own components, and it's encouraged to split your app into modular components for better maintainability and reusability. | ||
|
||
## Composite components | ||
|
||
Composite components allow you to compose components more flexibly than regular components. A commonly used composite component is the [button](../components/button.md) component, which accepts a child component which oftentimes the [text](../components/text.md) component. | ||
|
||
Example: | ||
|
||
```python | ||
with me.button(): | ||
me.text("Child") | ||
``` | ||
|
||
You can also have multiple composite components nested: | ||
|
||
```python | ||
with me.box(): | ||
with me.box(): | ||
me.text("Grand-child") | ||
``` | ||
|
||
Sometimes, you may want to define your own composite component for better reusability. For example, let's say I want to define a scaffold component which includes a menu positioned on the left and a main content area, I could do the following: | ||
|
||
```python | ||
@me.composite | ||
def scaffold(url: str): | ||
with me.box(style="background: white"): | ||
menu(url=url) | ||
with me.box(style=f"padding-left: {MENU_WIDTH}px"): | ||
me.slot() | ||
``` | ||
|
||
Now other components can re-use this scaffold component: | ||
|
||
```python | ||
def page1(): | ||
with scaffold(url="/page1"): | ||
some_content(...) | ||
``` | ||
|
||
This is similar to Angular's [Content Projection](https://angular.io/guide/content-projection). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,63 @@ | ||
# Interactivity | ||
|
||
This guide continues from the Counter app example in [Getting Started](../getting_started.md#counter-app) and explains advanced interactivity patterns. | ||
|
||
## State | ||
|
||
Example state class: | ||
|
||
```python | ||
@me.stateclass | ||
class State: | ||
clicks: int | ||
``` | ||
|
||
Each user session, which is equivalent to a browser session, will have its own state instance. Everything in a state class, recursively, must be serializable. This is because, under the hood, Mesop is sending the state back and forth between the server and browser client. | ||
|
||
### Nested State | ||
|
||
You can also have classes inside of a state class as long as everything is serializable: | ||
|
||
```python | ||
class NestedState: | ||
val: int | ||
|
||
@me.stateclass | ||
class State: | ||
nested: NestedState | ||
|
||
def app(): | ||
state = me.state(State) | ||
``` | ||
|
||
> Note: you only need to decorate the top-level state class with `@me.stateclass`. All the nested state classes will automatically be wrapped. | ||
## Slow / async patterns | ||
|
||
These are patterns for dealing with common use cases such as calling a slow blocking API call or a streaming API call. | ||
|
||
### Loading | ||
|
||
If you are calling a slow blocking API (e.g. several seconds) to provide a better user experience, you may want to introduce a custom loading indicator for a specific event. | ||
|
||
> Note: Mesop has a built-in loading indicator at the top of the page for all events. | ||
```python | ||
--8<-- "mesop/examples/docs/loading.py" | ||
``` | ||
|
||
In this example, our event handler is a Python generator function. Each `yield` statement yields control back to the Mesop framework and executes a render loop which results in a UI update. | ||
|
||
Before the first yield statement, we set `is_loading` to True on state so we can show a spinner while the user is waiting for the slow API call to complete. | ||
|
||
Before the second (and final) yield statement, we set `is_loading` to False, so we can hide the spinner and then we add the result of the API call to state so we can display that to the user. | ||
|
||
> Tip: you must have a yield statement as the last line of a generator event handler function. Otherwise, any code after the final yield will not be executed. | ||
### Streaming | ||
|
||
This example builds off the previous Loading example and makes our event handler a generator function so we can incrementally update the UI. | ||
|
||
```python | ||
--8<-- "mesop/examples/docs/streaming.py" | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,6 @@ | ||
# Modes | ||
|
||
There are several modes that you can run Mesop in. | ||
TODO bad | ||
|
||
## Uncompiled mode | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -140,7 +140,7 @@ | |
} | ||
|
||
.highlight code { | ||
font-size: 0.75rem; | ||
font-size: 0.7rem; | ||
} | ||
|
||
.md-tabs__link { | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -14,6 +14,7 @@ py_library( | |
srcs = glob(["*.py"]), | ||
deps = [ | ||
"//mesop", | ||
"//mesop/examples/docs", | ||
"//mesop/examples/shared", | ||
], | ||
) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
load("//build_defs:defaults.bzl", "py_library") | ||
|
||
package( | ||
default_visibility = ["//build_defs:mesop_internal"], | ||
) | ||
|
||
py_library( | ||
name = "docs", | ||
srcs = glob(["*.py"]), | ||
deps = [ | ||
"//mesop", | ||
], | ||
) |
Empty file.
Oops, something went wrong.