From 69d35abe4fc05012c5f3ed6f23c51bc16639d146 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= Date: Sat, 15 Feb 2020 10:08:49 +0100 Subject: [PATCH] [DOC] add a dedicated page on slots closes #640 --- doc/readme.md | 1 + doc/reference/component.md | 73 +----------------- doc/reference/misc.md | 2 +- doc/reference/qweb_templating_language.md | 2 +- doc/reference/slots.md | 93 +++++++++++++++++++++++ 5 files changed, 98 insertions(+), 73 deletions(-) create mode 100644 doc/reference/slots.md diff --git a/doc/readme.md b/doc/readme.md index a15fa2dd..a0266e26 100644 --- a/doc/readme.md +++ b/doc/readme.md @@ -33,6 +33,7 @@ provided by Owl. - [QWeb Engine](reference/qweb_engine.md) - [Router](reference/router.md) - [Store](reference/store.md) +- [Slots](reference/slots.md) - [Tags](reference/tags.md) - [Utils](reference/utils.md) diff --git a/doc/reference/component.md b/doc/reference/component.md index 425266a3..2a5c8d32 100644 --- a/doc/reference/component.md +++ b/doc/reference/component.md @@ -15,7 +15,6 @@ - [Event Handling](#event-handling) - [Form Input Bindings](#form-input-bindings) - [References](#references) - - [Slots](#slots) - [Dynamic sub components](#dynamic-sub-components) - [Error Handling](#error-handling) - [Functional Components](#functional-components) @@ -823,75 +822,6 @@ Note that these two examples uses the suffix `ref` to name the reference. This is not mandatory, but it is a useful convention, so we do not forget to access it with the `el` or `comp` suffix. -### Slots - -To make generic components, it is useful to be able for a parent component to _inject_ -some sub template, but still be the owner. For example, a generic dialog component -will need to render some content, some footer, but with the parent as the -rendering context. - -This is what _slots_ are for. - -```xml -
-
-
- -
-
- -
-
-``` - -Slots are defined by the caller, with the `t-set` directive: - -```xml -
-
some component
- - -
hey
- - - - - -
-``` - -In this example, the component `Dialog` will render the slots `content` and `footer` -with its parent as rendering context. This means that clicking on the button -will execute the `doSomething` method on the parent, not on the dialog. - -Default slot: the first element inside the component which is not a named slot will -be considered the `default` slot. For example: - -```xml -
- - some content - -
- -
- -
-``` - -Slots can define a default content, in case the parent did not define them: - -```xml -
- -
- - - default content - - -``` - ### Dynamic sub components It is not common, but sometimes we need a dynamic component name. In this case, @@ -983,7 +913,8 @@ Using the `ErrorBoundary` is then extremely simple: ``` Note that we need to be careful here: the fallback UI should not throw any -error, otherwise we risk going into an infinite loop. +error, otherwise we risk going into an infinite loop (also, see the page on +[slots](slots.md) for more information on the `t-slot` directive). Also, it may be useful to know that whenever an error is caught, it is then broadcasted to the application by an event on the `qweb` instance. It may be diff --git a/doc/reference/misc.md b/doc/reference/misc.md index 71bcbf54..f5b92620 100644 --- a/doc/reference/misc.md +++ b/doc/reference/misc.md @@ -18,7 +18,7 @@ for modals (as in `bootstrap-modal`). ### Usage The content it will teleport is defined within the `` node and -internally uses the `default` [Slot](component.md#slots). +internally uses the `default` [Slot](slots.md). This slot must contain only **one** node, which in turn can have as many children as necessary. diff --git a/doc/reference/qweb_templating_language.md b/doc/reference/qweb_templating_language.md index 63b7f8f7..c183cb76 100644 --- a/doc/reference/qweb_templating_language.md +++ b/doc/reference/qweb_templating_language.md @@ -73,7 +73,7 @@ needs. Here is a list of all Owl specific directives: | `t-key` | [Defining a key (to help virtual dom reconciliation)](#loops) | | `t-on-*` | [Event handling](component.md#event-handling) | | `t-transition` | [Defining an animation](animations.md#css-transitions) | -| `t-slot` | [Rendering a slot](component.md#slots) | +| `t-slot` | [Rendering a slot](slots.md) | | `t-model` | [Form input bindings](component.md#form-input-bindings) | ## Reference diff --git a/doc/reference/slots.md b/doc/reference/slots.md new file mode 100644 index 00000000..6f34c2c5 --- /dev/null +++ b/doc/reference/slots.md @@ -0,0 +1,93 @@ +# 🦉 Slots 🦉 + +## Content + +- [Overview](#overview) +- [Example](#example) +- [Reference](#reference) + +## Overview + +Owl is a template based component system. There is therefore a need to be able +to make generic components. For example, imagine a generic `Dialog` +component, which is able to display some arbitrary content. + +Obviously, we want to use this component everywhere in our application, to +display various different content. The `Dialog` component is technically the +owner of its content, but is only a container. The user of the `Dialog` is +the component that want to _inject_ something inside the `Dialog`. This is +exactly what slots are for. + +## Example + +To make generic components, it is useful to be able for a parent component to _inject_ +some sub template, but still be the owner. For example, a generic dialog component +will need to render some content, some footer, but with the parent as the +rendering context. + +```xml +
+
+
+ +
+
+ +
+
+``` + +Slots are defined by the caller, with the `t-set` directive: + +```xml +
+
some component
+ + +
hey
+ + + + + +
+``` + +In this example, the component `Dialog` will render the slots `content` and `footer` +with its parent as rendering context. This means that clicking on the button +will execute the `doSomething` method on the parent, not on the dialog. + +## Reference + +Default slot: the first element inside the component which is not a named slot will +be considered the `default` slot. For example: + +```xml +
+ + some content + +
+ +
+ +
+``` + +Default content: slots can define a default content, in case the parent did not define them: + +```xml +
+ +
+ + + default content + + +``` + +Rendering context: the content of the slots is actually rendered with the +rendering context corresponding to where it was defined, not where it is +positioned. This allows the user to define event handlers that will be bound +to the correct component (usually, the grandparent of the slot content).