From b4b9edf603dbfb9093caa03680c35c0b5e1bb89f Mon Sep 17 00:00:00 2001 From: trbrc Date: Sat, 1 Jun 2019 17:15:37 +0200 Subject: [PATCH 01/26] Clearer headlines with syntax examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change headline “Actions” to “Use directive” + add a number of additional syntax examples, to make it easier to find the relevant section without ⌘F --- site/content/docs/02-template-syntax.md | 30 +++++++++++++++---------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md index 167d1fa3a288..86d3e97e0b5c 100644 --- a/site/content/docs/02-template-syntax.md +++ b/site/content/docs/02-template-syntax.md @@ -283,7 +283,7 @@ If you don't care about the pending state, you can also omit the initial block. ``` -### DOM events +### DOM events (on:eventname) ```sv on:eventname={handler} @@ -370,7 +370,7 @@ It's possible to have multiple event listeners for the same event: ``` -### Component events +### Component events (on:eventname) ```sv on:eventname={handler} @@ -392,7 +392,7 @@ As with DOM events, if the `on:` directive is used without a value, the componen ``` -### Element bindings +### Element bindings (bind:property) ```sv bind:property={variable} @@ -436,7 +436,7 @@ Numeric input values are coerced; even though `input.value` is a string as far a ``` -#### Binding related elements +#### Binding related elements (bind:group) --- @@ -550,7 +550,7 @@ Block-level elements have 4 readonly bindings, measured using a technique simila ``` -#### Binding a DOM node +#### Binding a DOM node (bind:this) --- @@ -572,7 +572,7 @@ To get a reference to a DOM node, use `bind:this`. ``` -### Component bindings +### Component bindings (bind:property) ```sv bind:property={variable} @@ -589,6 +589,8 @@ You can bind to component props using the same mechanism. ``` +#### Binding a component instance (bind:this) + --- Components also support `bind:this`, allowing you to interact with component instances programmatically. @@ -604,7 +606,7 @@ Components also support `bind:this`, allowing you to interact with component ins ``` -### Classes +### Class directive (class:name) ```sv class:name={value} @@ -630,7 +632,7 @@ A `class:` directive provides a shorter way of toggling a class on an element. ``` -### Actions +### Use directive (use:action) ```sv use:action @@ -695,7 +697,7 @@ An action can have parameters. If the returned value has an `update` method, it ``` -### Transitions +### Transitions (transition/in/out:name) ```sv transition:name @@ -911,7 +913,7 @@ Local transitions only play when the block they belong to is created or destroye ``` -### Animations +### Animations (animate:name) ```sv animate:name @@ -1047,7 +1049,7 @@ A custom animation function can also return a `tick` function, which is called * -### Slots +### <slot> ```sv @@ -1079,6 +1081,8 @@ The content is exposed in the child component using the `` element, which ``` +#### Named slots (slot="name") + --- Named slots allow consumers to target specific areas. They can also have fallback content. @@ -1098,6 +1102,8 @@ Named slots allow consumers to target specific areas. They can also have fallbac ``` +#### Let directive (let:name) + --- Slots can be rendered zero or more times, and can pass values *back* to the parent using props. The parent exposes the values to the slot template using the `let:` directive. @@ -1325,4 +1331,4 @@ It accepts a comma-separated list of variable names (not arbitrary expressions). {@debug typeof user === 'object'} ``` -The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables. \ No newline at end of file +The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables. From 570098e8dd2b26d4f5befba85a30f996cdfd561a Mon Sep 17 00:00:00 2001 From: Richard Harris Date: Thu, 6 Jun 2019 09:05:20 -0400 Subject: [PATCH 02/26] restructure --- site/content/docs/02-template-syntax.md | 341 ++++++++++++------------ site/src/routes/docs/_sections.js | 16 +- 2 files changed, 181 insertions(+), 176 deletions(-) diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md index 497396af3036..bc82e7b8ae04 100644 --- a/site/content/docs/02-template-syntax.md +++ b/site/content/docs/02-template-syntax.md @@ -101,27 +101,7 @@ Text can also contain JavaScript expressions: ``` -### HTML expressions - -```sv -{@html expression} -``` - ---- - -In a text expression, characters like `<` and `>` are escaped. With HTML expressions, they're not. - -> Svelte does not sanitize expressions before injecting HTML. If the data comes from an untrusted source, you must sanitize it, or you are exposing your users to an XSS vulnerability. - -```html -
-

{post.title}

- {@html post.content} -
-``` - - -### If blocks +### `{#if ...}` ```sv {#if expression}...{/if} @@ -158,7 +138,7 @@ Additional conditions can be added with `{:else if expression}`, optionally endi ``` -### Each blocks +### `{#each ...}` ```sv {#each expression as name}...{/each} @@ -229,7 +209,7 @@ An each block can also have an `{:else}` clause, which is rendered if the list i ``` -### Await blocks +### `{#await ...}` ```sv {#await expression}...{:then name}...{:catch name}...{/await} @@ -283,7 +263,77 @@ If you don't care about the pending state, you can also omit the initial block. ``` -### DOM events (on:eventname) +### `{@html ...}` + +```sv +{@html expression} +``` + +--- + +In a text expression, characters like `<` and `>` are escaped. With HTML expressions, they're not. + +> Svelte does not sanitize expressions before injecting HTML. If the data comes from an untrusted source, you must sanitize it, or you are exposing your users to an XSS vulnerability. + +```html +
+

{post.title}

+ {@html post.content} +
+``` + + +### `{@debug ...}` + +```sv +{@debug} +``` +```sv +{@debug var1, var2, ..., varN} +``` + +--- + +The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs the values of specific variables whenever they change, and pauses code execution if you have devtools open. + +It accepts a comma-separated list of variable names (not arbitrary expressions). + +```html + + +{@debug user} + +

Hello {user.firstname}!

+``` + +--- + +`{@debug ...}` accepts a comma-separated list of variable names (not arbitrary expressions). + +```html + +{@debug user} +{@debug user1, user2, user3} + + +{@debug user.firstname} +{@debug myArray[0]} +{@debug !isReady} +{@debug typeof user === 'object'} +``` + +The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables. + + + +### Element directives + +#### on:*event* ```sv on:eventname={handler} @@ -370,29 +420,7 @@ It's possible to have multiple event listeners for the same event: ``` -### Component events (on:eventname) - -```sv -on:eventname={handler} -``` - ---- - -Components can emit events using [createEventDispatcher](docs#createEventDispatcher), or by forwarding DOM events. Listening for component events looks the same as listening for DOM events: - -```html - -``` - ---- - -As with DOM events, if the `on:` directive is used without a value, the component will *forward* the event, meaning that a consumer of the component can listen for it. - -```html - -``` - -### Element bindings (bind:property) +#### bind:*name* ```sv bind:property={variable} @@ -436,7 +464,7 @@ Numeric input values are coerced; even though `input.value` is a string as far a ``` -#### Binding related elements (bind:group) +#### `bind:group` --- @@ -460,6 +488,28 @@ Inputs that work together can use `bind:group`. ``` +#### `bind:this` (elements) + +--- + +To get a reference to a DOM node, use `bind:this`. + +```html + + + +``` + + #### Binding ` ``` -#### `bind:group` - ---- - -Inputs that work together can use `bind:group`. - -```html - - - - - - - - - - - - -``` - -#### `bind:this` (elements) - ---- - -To get a reference to a DOM node, use `bind:this`. - -```html - - - -``` - -#### Binding `` value --- @@ -550,7 +502,7 @@ When the value of an `