Skip to content

Commit

Permalink
docs: enhance deep dive section (#9816)
Browse files Browse the repository at this point in the history
Related to: #9190
  • Loading branch information
ilhan007 authored Sep 10, 2024
1 parent 1ebf7db commit 5ba5c9b
Show file tree
Hide file tree
Showing 4 changed files with 525 additions and 42 deletions.
2 changes: 1 addition & 1 deletion docs/2-advanced/11-styles.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ We designed some components such as Title, Label, Tag, Button, Input, and a few
background: purple;
}
```
You can try this yourself on the Input [test page](https://sap.github.io/ui5-webcomponents/main/playground/main/pages/Input/).
You can try this yourself using the Input [sample](https://sap.github.io/ui5-webcomponents/components/Input/#custom-styling/).

Unfortunately, this can't be done for all components because it depends on the complexity of the DOM structure.

Expand Down
20 changes: 12 additions & 8 deletions docs/3-frameworks/03-Vue.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
In this tutorial you will learn how to add UI5 Web Components to your application. You can add UI5 Web Components both to new Vue.js applications and to already existing ones.

## Setting up a Vite and Vue.js project with UI5 Web Components
<br/>

### Step 1. Setup a Vue project with Vite.

Expand Down Expand Up @@ -55,15 +54,20 @@ import "@ui5/webcomponents/dist/Button.js";
```bash
npm run dev
```
## Additional Info

### Two-Way Data Binding

`v-model` binding doesn't work for custom elements. In order to use two-way data binding, you need to bind and update the value yourself like this:
## Two-Way Data Binding

In order to use two-way data binding, use `v-model` as follows:

```html
<ui5-input v-model="inputValue"></ui5-input>
```

For the `CheckBox` and `RadioButton` web components, you need to include an additional `type` attribute. This informs the Vue compiler that these components use the `checked` property (unlike most input-type components that use the `value` property).

```html
<ui5-input
:value="inputValue"
@input="inputValue = $event.target.value">
</ui5-input>
<ui5-radio-button type="radio" v-model="rbValue"></ui5-radio-button>
<ui5-checkbox type="checkbox" v-model="cbValue"></ui5-checkbox>
```

50 changes: 33 additions & 17 deletions docs/4-development/04-slots.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,26 @@ Currently, there are two types of slots: "named" and "unnamed". The difference b

## Unnamed slots

Use unnamed slots when your component does not need to know if any children have been passed to a certain slot, or generally interact with its children from the said slot.

To define an unnamed slot, you simply add a `<slot>` element inside your `.hbs` template, for example:
Use unnamed slots when your component doesn't need to be aware of or interact with the children passed to a specific slot.
To define an unnamed slot, simply add a `<slot>` element within your `.hbs` template. For example:

```hbs
<slot name="mySlot"></slot>
{{!-- MyDemoComponent.hbs --}}
<div>
<slot name="mySlot"></slot>
</div>
```

On the consuming side, elements can be passed to this slot using the `slot` attribute:

```html
<!-- index.html -->
<my-demo-component>
<span slot="mySlot">Hello World</span>
</my-demo-component>
```


**Note:** It is recommended to describe your unnamed slots inside a JSDoc comment that describes your class using the `@slot` tag, following the pattern `@slot {type} name - description`.

## Named slots and the `@slot` decorator
Expand All @@ -39,15 +51,15 @@ import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";

@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
@slot({ type: HTMLElement })
@slot()
mySlot!: Array<HTMLElement>;
}
```

You can see the available options below.

### type
This option is required and accepts a type constructor (e.g., `HTMLElement`, `Node`) and is used to define the type of children that can be slotted inside the slot.
### Type
The `type` option accepts a type constructor (e.g., `HTMLElement`, `Node`) and is used to define the type of children that can be slotted inside the slot.

```ts
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
Expand All @@ -67,10 +79,14 @@ Available types:
| HTMLElement | Accepts HTML Elements only |
| Node | Accepts both Text nodes and HTML Elements |

**Note**: If the slot configuration object is not provided (e.g. `@slot()`), `HTMLElement` will be used as the default type.


### Default Slot
This option accepts a boolean value and is used to define whether this slot is the default one.

**Note:** The default slot is defined simply as an empty slot tag: `<slot></slot>` (without a `name` attribute).
The `"default"` option accepts a boolean value and is used to define whether this slot is the default one.

**Note:** The default slot is defined simply as an empty slot tag `<slot></slot>` (without a `name` attribute) in the component's template.

```ts
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
Expand All @@ -79,13 +95,14 @@ import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";

@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
@slot({ type: HTMLElement, default: true })
@slot({ type: HTMLElement, "default": true })
mySlot!: Array<HTMLElement>;
}
```

### `individualSlots`
This option accepts a boolean value and determines whether each child will have its own slot, allowing you to arrange or wrap the children arbitrarily. This means that you need to handle the rendering on your own.
### Individual Slots

The `individualSlots` option accepts a boolean value and determines whether each child will have its own slot, allowing you to arrange or wrap the children arbitrarily. This means that you need to handle the rendering on your own.

```ts
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
Expand All @@ -99,7 +116,7 @@ class MyDemoComponent extends UI5Element {
}
```

To render individual slots, you have to iterate all children in that slot and use the `_individualSlot` property that the framework sets automatically set on each child:
To render individual slots, you have to iterate all children in that slot and use the `_individualSlot` property that the framework sets automatically on each child:

```hbs
{{#each mySlot}}
Expand All @@ -109,12 +126,11 @@ To render individual slots, you have to iterate all children in that slot and us

**Note:** When this option is set to `true`, the `_individualSlot` property is set to each direct child, where `_individualSlot` returns a string following the pattern `{nameOfTheSlot}-{index}` and the slot attribute is changed based on that pattern.

### `invalidateOnChildChange`
This option accepts a boolean value or an object literal containing a configuration with more specific settings, determining whether the component should be invalidated on child change.
### Invalidation upon child changes

**NOTE: This is an experimental option and should not be used.**
The `invalidateOnChildChange` option accepts a boolean value or an object literal containing a configuration with more specific settings, determining whether the component should be invalidated on child change.

Important: `invalidateOnChildChange` is not meant to be used with standard DOM elements and is not to be confused with MutationObserver-like functionality. It targets the use case of components that slot abstract items (UI5Element instances without a template) and require invalidation whenever these items are invalidated.
**Note**: `invalidateOnChildChange` is not meant to be used with standard DOM elements and is not to be confused with MutationObserver-like functionality. It targets the use case of components that slot UI5Element instances and require invalidation whenever these items are invalidated.

```ts
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
Expand Down
Loading

0 comments on commit 5ba5c9b

Please sign in to comment.