From 6869ccb3e71375c2d698ebb3dc60cedace3c202a Mon Sep 17 00:00:00 2001 From: Ayo Date: Sat, 18 Nov 2023 10:31:12 +0100 Subject: [PATCH] feat: more explainer for using WebComponent.props - update readme with more read/write access explanation and example - update demo page to use .props --- README.md | 41 ++++++++++++++++++++++++++++++++++------- demo/index.html | 4 ++-- 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index fb95470..f666fb9 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,8 @@ In your HTML page: setTimeout(() => { helloWorld.setAttribute('emotion', 'excited'); + // or: + helloWorld.props.emotion = 'excited'; }, 2500) @@ -93,27 +95,52 @@ This mental model attempts to reduce the cognitive complexity of authoring compo ## Prop Access -There is a `WebComponent.props` read-only property provided for easy access to *any* observed attribute. This works like [`HTMLElement.dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) except `dataset` is only for attributes prefixed with `data-*`. + The `WebComponent.props` read-only property is provided for easy access to *any* observed attribute. This works like [`HTMLElement.dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset), except `dataset` is only for attributes prefixed with `data-*`. A camelCase counterpart using `props` will give read/write access to any attribute, with or without the `data-*` prefix. -You can access attribute properties in two ways: -1. Use the camelCase counterpart: `this.props.myProp`, which is automatically filled. -1. Or stick with kebab-case: `this["my-prop"]` +### Accessing props within the component + +This API gives us read/write access to any attribute properties: ```js class HelloWorld extends WebComponent { static properties = ["my-prop"]; - + onInit() { + let count = 0; + this.onclick = () => this.props.myProp = `${++count}` + } get template() { return `

Hello ${this.props.myProp}

-

Hello ${this["my-prop"]}

`; } } ``` +With this, the `this.props` object gives us an easy way to read or write property values, which also triggers the attribute change hook. + +The alternatives are using what `HTMLElement` provides which are +1. `HTMLElement.dataset` for attributes prefixed with `data-*` +1. Methods for reading/writing attribute values: `setAttribute(...)` and `getAttribute(...)` + +### Updating props in the parent + +Assigning value to the `props.camelCase` counterpart will trigger an attribute change too. + +For example, assigning a value like so: +``` +this.props.myName = 'hello' +``` + +...is like calling the following: + +``` +this.setAttribute('my-name','hello'); +``` + +Therefore, this will tell the browser that the UI needs a render if the attribute is one of the component's observed attributes we explicitly provide with `static properties = ['my-name']`; + ## Quick Start Example Here is an example of using a custom element in a single .html file: @@ -142,7 +169,7 @@ Here is an example of using a custom element in a single .html file: diff --git a/demo/index.html b/demo/index.html index cb061d0..d73cd25 100644 --- a/demo/index.html +++ b/demo/index.html @@ -9,7 +9,7 @@ - +

@@ -20,7 +20,7 @@