From dfd0dcedb8d56bae8254aa65f0bc1e4d539e4fd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= Date: Wed, 19 Jan 2022 10:40:15 +0100 Subject: [PATCH] [IMP] doc: add changelog to doc test, update changelog --- CHANGELOG.md | 50 ++++++++++++++++++++- doc/reference/props.md | 62 ++++++++++++++------------ tests/tooling/doc_link_checker.test.ts | 1 + 3 files changed, 84 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9af6bfb9..de95bb0a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,9 @@ All changes are documented here in no particular order. - breaking: `t-component` no longer accepts strings ([details](#17-t-component-no-longer-accepts-strings)) - breaking: `render` method does not return a promise anymore ([details](#35-render-method-does-not-return-a-promise-anymore)) - breaking: `catchError` method is replaced by `onError` hook ([details](#36-catcherror-method-is-replaced-by-onerror-hook)) +- new: components can use the `.bind` suffix to bind function props ([doc](doc/reference/props.md#binding-function-props)) +- breaking: Support for inline css (`css` tag and static `style`) has been removed ([details](#37-support-for-inline-css-css-tag-and-static-style-has-been-removed)) +- new: prop validation system can now describe that additional props are allowed (with `*`) ([doc](doc/reference/props.md#props-validation)) **Portal** @@ -74,6 +77,7 @@ All changes are documented here in no particular order. - breaking: `t-on` does not accept expressions, only functions ([details](#30-t-on-does-not-accept-expressions-only-functions)) - breaking: `renderToString` function on qweb has been removed ([details](#32-rendertostring-on-qweb-has-been-removed)) - breaking: `debounce` utility function has been removed ([details](#34-debounce-utility-function-has-been-removed)) +- breaking: `t-raw` directive has been removed (replaced by `t-out`) ([details](#38-t-raw-directive-has-been-removed-replaced-by-t-out)) ## Details/Rationale/Migration @@ -338,8 +342,16 @@ the component API to accept explicitely a callback as props. ```xml + + ``` +Note that one of the example above uses the `.bind` suffix, to bind the function +prop to the component. Most of the time, binding the function is necessary, and +using the `.bind` suffix is very helpful in that case. + +Documentation: [Binding function props](doc/reference/props.md#binding-function-props) + ### 13. Portal does no longer transfer DOM events In Owl 1, a Portal component would listen to events emitted on its portalled @@ -698,4 +710,40 @@ consistent. Migration: mostly replace all `catchError` methods by `onError` hooks in the `setup` method. -Documentation: [Error Handling](doc/reference/error_handling.md) \ No newline at end of file +Documentation: [Error Handling](doc/reference/error_handling.md) + + +## 37. Support for inline css (`css` tag and static `style`) has been removed + +Rationale: Owl tries to focus on what it does best, and supporting inline css +was not a priority. It used to support some simplified scss language, but it +was feared that it would cause more trouble than it was worth. Also, it seems +like it can be done in userspace. + +Migration: it seems possible to implement an equivalent solution using hooks. A +simple implementation could look like this: + +```js +let cache = {}; + +function useStyle(css) { + if (!css in cache) { + const sheet = document.createElement("style"); + sheet.innerHTML = css; + cache[css] = sheet; + document.head.appendChild(sheet); + } +} +``` + +## 38. `t-raw` directive has been removed (replaced by `t-out`) + +To match the Odoo qweb server implementation, Owl does no longer implement `t-raw`. +It is replaced by the `t-out` directive, which is safer: it requires the data +to be marked explicitely as markup if it is to be inserted without escaping. +Otherwise, it will be escaped (just like `t-esc`). + +Migration: replace all `t-raw` uses by `t-out`, and uses the `markup` function +to mark all the js values. + +Documentation: [Outputting data](doc/reference/templates.md#outputting-data) \ No newline at end of file diff --git a/doc/reference/props.md b/doc/reference/props.md index 48276bc1..bcbec298 100644 --- a/doc/reference/props.md +++ b/doc/reference/props.md @@ -144,9 +144,36 @@ of the props. Here is how it works in Owl: - props are only validated in `dev` mode (see [how to configure an app](app.md#configuration)) - if a key does not match the description, an error is thrown - it validates keys defined in (static) `props`. Additional keys given by the - parent will cause an error. + parent will cause an error (unless the special prop `*` is present). +- it is an object or a list of strings +- a list of strings is a simplified props definition, which only lists the name + of the props. Also, if the name ends with `?`, it is considered optional. +- all props are by default required, unless they are defined with `optional: true` + (in that case, it is only done if there is a value) +- valid types are: `Number, String, Boolean, Object, Array, Date, Function`, and all + constructor functions (so, if you have a `Person` class, it can be used as a type) +- arrays are homogeneous (all elements have the same type/shape) -For example: +For each key, a `prop` definition is either a boolean, a constructor, a list of constructors, or an object: + +- a boolean: indicate that the props exists, and is mandatory. +- a constructor: this should describe the type, for example: `id: Number` describe + the props `id` as a number +- a list of constructors. In that case, this means that we allow more than one + type. For example, `id: [Number, String]` means that `id` can be either a string + or a number. +- an object. This makes it possible to have more expressive definition. The following sub keys are then allowed (but not mandatory): + - `type`: the main type of the prop being validated + - `element`: if the type was `Array`, then the `element` key describes the type of each element in the array. If it is not set, then we only validate the array, not its elements, + - `shape`: if the type was `Object`, then the `shape` key describes the interface of the object. If it is not set, then we only validate the object, not its elements, + - `validate`: this is a function which should return a boolean to determine if + the value is valid or not. Useful for custom validation logic. + +There is a special `*` prop that means that additional prop are allowed. This is +sometimes useful for generic components that will propagate some or all their +props to their child components. + +Examples: ```js class ComponentA extends owl.Component { @@ -170,37 +197,16 @@ class ComponentB extends owl.Component { } ``` -- it is an object or a list of strings -- a list of strings is a simplified props definition, which only lists the name - of the props. Also, if the name ends with `?`, it is considered optional. -- all props are by default required, unless they are defined with `optional: true` - (in that case, validation is only done if there is a value) -- valid types are: `Number, String, Boolean, Object, Array, Date, Function`, and all - constructor functions (so, if you have a `Person` class, it can be used as a type) -- arrays are homogeneous (all elements have the same type/shape) - -For each key, a `prop` definition is either a boolean, a constructor, a list of constructors, or an object: - -- a boolean: indicate that the props exists, and is mandatory. -- a constructor: this should describe the type, for example: `id: Number` describe - the props `id` as a number -- a list of constructors. In that case, this means that we allow more than one - type. For example, `id: [Number, String]` means that `id` can be either a string - or a number. -- an object. This makes it possible to have more expressive definition. The following sub keys are then allowed (but not mandatory): - - `type`: the main type of the prop being validated - - `element`: if the type was `Array`, then the `element` key describes the type of each element in the array. If it is not set, then we only validate the array, not its elements, - - `shape`: if the type was `Object`, then the `shape` key describes the interface of the object. If it is not set, then we only validate the object, not its elements, - - `validate`: this is a function which should return a boolean to determine if - the value is valid or not. Useful for custom validation logic. - -Examples: - ```js // only the existence of those 3 keys is documented static props = ['message', 'id', 'date']; ``` +```js + // only the existence of those 3 keys is documented. any other key is allowed. + static props = ['message', 'id', 'date', '*']; +``` + ```js // size is optional static props = ['message', 'size?']; diff --git a/tests/tooling/doc_link_checker.test.ts b/tests/tooling/doc_link_checker.test.ts index 47494832..6c23f6b5 100644 --- a/tests/tooling/doc_link_checker.test.ts +++ b/tests/tooling/doc_link_checker.test.ts @@ -60,6 +60,7 @@ function getFiles(path: string[] = []): FileData[] { if (path.length === 0) { const baseFiles: FileData[] = [ { name: "README.md", path: [], links: [], sections: [], fullName: "README.md" }, + { name: "CHANGELOG.md", path: [], links: [], sections: [], fullName: "CHANGELOG.md" }, { name: "roadmap.md", path: [], links: [], sections: [], fullName: "roadmap.md" }, ]; const rest = getFiles(["doc"]);