Skip to content

Commit

Permalink
Fire state changed events and add progess bar (#10)
Browse files Browse the repository at this point in the history 
Co-authored-by: Paulus Schoutsen <balloob@gmail.com>
  • Loading branch information
@bramkragten @balloob
bramkragten and balloob committed Jun 12, 2021
1 parent 4ad010e commit 4cc28e1
Show file tree
Hide file tree
Showing 11 changed files with 1,396 additions and 999 deletions.
45 changes: 45 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,57 @@ All attributes can also be set via properties (`manifest`, `eraseFirst`)

## Styling

### Attributes

The following attributes are automatically added to `<esp-web-install-button>`:

| Attribute | Description |
| -- | -- |
| `install-supported` | Added if installing firmware is supported
| `install-unsupported` | Added if installing firmware is not supported
| `active` | Added when flashing is active

You can add the following attributes or properties to change the UI elements:

| Attribute | Property | Description |
| -- | -- | -- |
| `show-log` | `showLog` | Show a log style view of the progress instead of a progress bar
| `hide-progress` | `hideProgress` | Hides all progress UI elements

### CSS custom properties (variables)

The following variables can be used to change the colors of the default UI elements:

- `--esp-tools-button-color`
- `--esp-tools-button-text-color`
- `--esp-tools-success-color`
- `--esp-tools-error-color`
- `--esp-tools-progress-color`
- `--esp-tools-log-background`
- `--esp-tools-log-text-color`

### Slots

The following slots are available:

| Slot name | Description |
| -- | -- |
| `activate` | Button to start the flash progress
| `unsupported` | Message to show when the browser is not supported

## Events

When the state of flashing changes, a `state-changed` event is fired.

A `state-changed` event contains the following information:

Field | Description
-- | --
state | The current [state](https://github.com/esphome/esp-web-tools/blob/main/src/const.ts)
message | A description of the current state
manifest | The loaded manifest
chipFamily | The chip that was detected;&nbsp;"ESP32" \| "ESP8266" \| "ESP32-S2" \| "Unknown Chip"
details | An optional extra field that is different [per state](https://github.com/esphome/esp-web-tools/blob/main/src/const.ts)

## Development

Expand Down
146 changes: 140 additions & 6 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,6 @@
.project .logo img {
width: 100%;
}
esp-web-flash-log {
margin-top: 8px;
}
a {
color: #03a9f4;
}
Expand Down Expand Up @@ -61,6 +58,13 @@
font-style: italic;
margin-top: 16px;
}
table {
border-spacing: 0;
}
td {
padding: 8px;
border-bottom: 1px solid #ccc;
}
</style>
<script module>
import(
Expand Down Expand Up @@ -236,20 +240,150 @@ <h3 id="manifest">Creating your manifest</h3>

<h3>Customizing the look and feel</h3>
<p>
You can customize both the activation button and the message that is
shown when the user uses an unsupported browser. This can be done using
the <code>activate</code> and <code>unsupported</code> slots:
There are multiple options to change the look and feel of the button and
other elements.
</p>
<h4>Change colors</h4>
<p>
You can change the colors of the default UI elements with CSS custom
properties (variables), the following variables are available:
</p>
<ul>
<li><code>--esp-tools-button-color</code></li>
<li><code>--esp-tools-button-text-color</code></li>

<li><code>--esp-tools-success-color</code></li>
<li><code>--esp-tools-error-color</code></li>

<li><code>--esp-tools-progress-color</code></li>

<li><code>--esp-tools-log-background</code></li>
<li><code>--esp-tools-log-text-color</code></li>
</ul>
<p>There are also some attributes that can be used for styling:</p>
<table>
<tr>
<td><code>install-supported</code></td>
<td>Added if installing firmware is supported</td>
</tr>
<tr>
<td>
<code>install-unsupported</code>
</td>
<td>Added if installing firmware is not supported</td>
</tr>
<tr>
<td><code>active</code></td>
<td>Added when flashing is active</td>
</tr>
</table>
<p>
When you are using a custom button, you should disable it when the
<code>active</code> attribute is present.
</p>
<h4>Replace the button and message with a custom one</h4>
<p>
You can replace both the activation button and the message that is shown
when the user uses an unsupported browser with your own elements. This
can be done using the <code>activate</code> and
<code>unsupported</code> slots:
</p>
<pre>
&lt;esp-web-install-button
manifest="static/firmware_build/manifest.json"
show-log
erase-first
>
&lt;button slot="activate">Custom install button&lt;/button>
&lt;span slot="unsupported">Ah snap, your browser doesn't work!&lt;/span>
&lt;/esp-web-install-button>
</pre
>
<h4>Show or hide the progress bar and log</h4>
<p>
By default there is a progress bar showing the state and progress of the
flashing progress, you can chnage this progress bar to a log view with
the <code>show-log</code> attribute.
</p>
<p>
You can also hide all progress indicators by adding the `hide-progress`
attribute. This will hide both the progress bar and the log view. You
can then implement your own progress elements using the
<a href="#state-events">state events</a>.
</p>

<h3 id="state-events">State events</h3>
<p>
During the flash progress the button will fire
<code>state-changed</code> events for every step of the progress and to
signal progress in the writing.
</p>
<p>
With these events you can create your own progress UI or trigger certain
actions. You can also find the current state as the
<code>state</code> property of the
<code>esp-web-install-button</code> element.
</p>
<p>Events for the following states are fired:</p>
<ul>
<li>initializing</li>
<li>manifest</li>
<li>preparing</li>
<li>erasing</li>
<li>writing</li>
<li>finished</li>
<li>error</li>
</ul>
<p>
A <code>state-changed</code> event contains the following information:
</p>
<table>
<tr>
<td><code>state</code></td>
<td>The current state; one of the above</td>
</tr>
<tr>
<td><code>message</code></td>
<td>A description of the current state</td>
</tr>
<tr>
<td><code>manifest</code></td>
<td>The loaded manifest</td>
</tr>
<tr>
<td><code>build</code></td>
<td>The manifest's build that was selected</td>
</tr>
<tr>
<td><code>chipFamily</code></td>
<td>
The chip that was detected;
<code>"ESP32" | "ESP8266" | "ESP32-S2" | "Unknown Chip"</code>
</td>
</tr>
<tr>
<td><code>details</code></td>
<td>
An optional extra field that is different
<a
href="https://github.com/esphome/esp-web-tools/blob/main/src/const.ts"
>per state</a
>
</td>
</tr>
</table>
<p>An example that logs all state events:</p>
<pre>
&lt;esp-web-install-button
manifest="static/firmware_build/manifest.json"
>&lt;/esp-web-install-button>
&lt;script>
const espWebInstallButton = document.querySelector("esp-web-install-button");
espWebInstallButton.addEventListener(
"state-changed", (ev) => { console.log(ev.detail) }
);
&lt;/script>
</pre>
<div class="footer">
<div>
ESP Web Tools –
Expand Down
Loading

0 comments on commit 4cc28e1

Please sign in to comment.