[IMP] component/tags: add inline css tag

This add an important feature: defining completely standalone owl components, with the template/style and javascript code together. closes #284
2025-10-06 19:59:41 +07:00 · 2019-12-19 21:54:35 +01:00
parent 4f61d9f1e0
commit 953778dc50
10 changed files with 345 additions and 30 deletions
@@ -225,6 +225,10 @@ to be called in the constructor.
  }
  ```

+- **`style`** (string, optional): it should be the return value of the [`css tag](tags.md#css-tag),
+  which is used to inject stylesheet whenever the component is visible on the
+  screen.
+
 There is another static property defined on the `Component` class: `current`.
 This property is set to the currently being defined component (in the constructor).
 This is the way [hooks](hooks.md) are able to get a reference to the target
@@ -4,16 +4,19 @@

 - [Overview](#overview)
 - [`xml` tag](#xml-tag)
+- [`css` tag](#css-tag)

 ## Overview

-Tags are very small helpers to make it easy to write inline templates. There is
-only one currently available tag: `xml`, but we plan to add other tags later,
-such as a `css` tag, which will be used to write [single file components](../tooling.md#single-file-component).
+Tags are very small helpers intended to make it easy to write inline templates
+or styles. There are currently two tags: `css` and `xml`. With these functions,
+it is possible to write [single file components](../tooling.md#single-file-component).

 ## XML tag

-Without tags, creating a standalone component would look like this:
+The `xml` tag is certainly the most useful tag. It is used to define an inline
+QWeb template for a component. Without tags, creating a standalone component
+would look like this:

 ```js
 import { Component } from 'owl'
@@ -52,3 +55,84 @@ class MyComponent extends Component {
    ...
 }
 ```
+
+## CSS tag
+
+The CSS tag is useful to define a css stylesheet in the javascript file:
+
+```js
+class MyComponent extends Component {
+    static template = xml`
+        <div class="my-component">some template</div>
+    `;
+    static css`
+      .my-component {
+          color: red;
+      }
+    `;
+}
+```
+
+The `css` tag registers internally the css information. Then, whenever the first
+instance of the component is created, will add a `<style>` tag to the document
+`<head>`.
+
+Note that to make it more useful, like other css preprocessors, the `css` tag
+accepts a small extension of the css specification: css scopes can be nested,
+and the rules will then be expanded by the `css` helper:
+
+```scss
+.my-component {
+  display: block;
+  .sub-component h {
+    color: red;
+  }
+}
+```
+
+will be formatted as:
+
+```css
+.my-component {
+  display: block;
+}
+.my-component .sub-component h {
+  color: red;
+}
+```
+
+Now, there is no additional processing done by the `css` tag. However, since it
+is done in javascript at runtime, we actually have more power. For example:
+
+1. sharing values between javascript and css:
+
+```js
+import { theme } from "./theme";
+
+class MyComponent extends Component {
+  static template = xml`<div class="my-component">...</div>`;
+  static style = css`
+    .my-component {
+      color: ${theme.MAIN_COLOR};
+      background-color: ${theme.SECONDARY_color};
+    }
+  `;
+}
+```
+
+2. scoping rules to the current component:
+
+```js
+import { generateUUID } from "./utils";
+
+const uuid = generateUUID();
+
+class MyComponent extends Component {
+  static template = xml`<div data-o-${uuid}="">...</div>`;
+  static style = css`
+        [data-o-${uuid}] {
+            color: red;
+        }
+    `;
+}
+```