diff --git a/site/content/docs/_old_docs/02-template-syntax.md b/site/content/docs/_old_docs/02-template-syntax.md deleted file mode 100644 index d915a8e37f..0000000000 --- a/site/content/docs/_old_docs/02-template-syntax.md +++ /dev/null @@ -1,281 +0,0 @@ ---- -title: Template syntax ---- - -Rather than reinventing the wheel, Svelte templates are built on foundations that have stood the test of time: HTML, CSS and JavaScript. There's very little extra stuff to learn. - - -### Tags - -Tags allow you to bind data to your template. Whenever your data changes (for example after `component.a = 3`), the DOM updates automatically. You can use any JavaScript expression in templates, and it will also automatically update: - -```html - -

{a} + {b} = {a + b}

-``` - -```json -/* { hidden: true } */ -{ - "a": 1, - "b": 2 -} -``` - -You can also use tags in attributes: - -```html - -

{color}

- -``` - -```json -/* { hidden: true } */ -{ - color: "steelblue", - hideParagraph: false -} -``` -[Boolean attributes](https://www.w3.org/TR/html5/infrastructure.html#sec-boolean-attributes) like `hidden` will be omitted if the tag expression evaluates to false. Attributes will be removed from the element if their value is `undefined` or `null`. - -### HTML - -Ordinary tags render expressions as plain text. If you need your expression interpreted as HTML, wrap it in a special `@html` tag: - -```html - -

This HTML: {content}

-

Renders as: {@html content}

-``` - -```json -/* { hidden: true } */ -{ - content: "Some bold text." -} -``` - -As with regular tags, you can use any JavaScript expression in HTML tags, and it will automatically update the document when your data changes. - -> HTML is **not** sanitized before it is rendered! If you are displaying user input, you are responsible for first sanitizing it. Not doing so potentially opens you up to XSS attacks. - - -### If blocks - -Control whether or not part of your template is rendered by wrapping it in an if block. - -```html - -{#if user.loggedIn} - log out -{/if} - -{#if !user.loggedIn} - log in -{/if} -``` - -You can combine the two blocks above with `{:else}`: - -```html - -{#if user.loggedIn} - log out -{:else} - log in -{/if} -``` - -You can also use `{:else if ...}`: - -```html - -{#if x > 10} -

{x} is greater than 10

-{:else if 5 > x} -

{x} is less than 5

-{:else} -

{x} is between 5 and 10

-{/if} -``` - -```json -/* { hidden: true } */ -{ - x: 7 -} -``` - -### Each blocks - -Iterate over lists of data: - -```html - -

Cats of YouTube

- - -``` - -```json -/* { hidden: true } */ -{ - cats: [ - { - name: "Keyboard Cat", - video: "https://www.youtube.com/watch?v=J---aiyznGQ" - }, - { - name: "Maru", - video: "https://www.youtube.com/watch?v=z_AbfPXTKms" - }, - { - name: "Henri The Existential Cat", - video: "https://www.youtube.com/watch?v=OUtn3pvWmpg" - } - ] -} -``` - -Else is triggered when the list is empty. - -You can access the index of the current element with *expression* as *name*, *index*: - -```html - -
- {#each rows as row, y} -
- {#each columns as column, x} - - {x + 1},{y + 1}: - {row[column]} - - {/each} -
- {/each} -
-``` - -```json -/* { hidden: true } */ -{ - columns: ["foo", "bar", "baz"], - rows: [ - { foo: "a", bar: "b", baz: "c" }, - { foo: "d", bar: "e", baz: "f" }, - { foo: "g", bar: "h", baz: "i" } - ] -} -``` - -> By default, if the list `a, b, c` becomes `a, c`, Svelte will *remove* the third block and *change* the second from `b` to `c`, rather than removing `b`. If that's not what you want, use a [keyed each block](docs#keyed-each-blocks). - -You can use destructuring patterns on the elements of the array: - -```html - -

It's the cats of YouTube again

- - -``` - -```json -/* { hidden: true } */ -{ - cats: [ - { - name: "Keyboard Cat", - video: "https://www.youtube.com/watch?v=J---aiyznGQ" - }, - { - name: "Maru", - video: "https://www.youtube.com/watch?v=z_AbfPXTKms" - }, - { - name: "Henri The Existential Cat", - video: "https://www.youtube.com/watch?v=OUtn3pvWmpg" - } - ] -} -``` - -### Await blocks - -You can represent the three states of a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — pending, fulfilled and rejected — with an `await` block: - -```html - - - -{#await promise} -

wait for it...

-{:then answer} -

the answer is {answer}!

-{:catch error} -

well that's odd

-{/await} -``` - -If the expression in `{#await expression}` *isn't* a promise, Svelte skips ahead to the `then` section. - - -### Directives - -Directives allow you to add special instructions for adding [event handlers](docs#event-handlers), [bindings](docs#bindings), [transitions](docs#transitions) and so on. We'll cover each of those in later stages of this guide – for now, all you need to know is that directives can be identified by the `:` character: - -```html - -

Count: {count}

- -``` - -```json -/* { hidden: true } */ -{ - count: 0 -} -``` - -> Technically, the `:` character is used to denote namespaced attributes in HTML. These will *not* be treated as directives, if encountered. - - -### Debug tags - -To inspect data as it changes and flows through your app, use a `{@debug ...}` tag: - -```html - - - -{@debug name} -

Hello {name}!

-``` - -```json -/* { hidden: true } */ -{ - name: 'world' -} -``` - -This will log the value of `name` whenever it changes. If your devtools are open, changing `name` will pause execution and open the debugger. - -You can debug multiple values simultaneously (`{@debug foo, bar, baz}`), or use `{@debug}` to pause execution whenever the surrounding markup is updated. - -> Debug tags only have an effect when compiling with the `dev: true` compiler option. diff --git a/site/content/docs/_old_docs/03-scoped-styles.md b/site/content/docs/_old_docs/03-scoped-styles.md deleted file mode 100644 index b9ba69b981..0000000000 --- a/site/content/docs/_old_docs/03-scoped-styles.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Scoped styles ---- - -One of Svelte's key tenets is that components should be self-contained and reusable in different contexts. Because of that, it has a mechanism for *scoping* your CSS, so that you don't accidentally clobber other selectors on the page. - -### Adding styles - -Your component template can have a ` - -
- Big red Comic Sans -
-``` - - -### How it works - -Open the example above in the REPL and inspect the element to see what has happened – Svelte has added a `svelte-[uniqueid]` class to the element, and transformed the CSS selector accordingly. Since no other element on the page can share that selector, anything else on the page with `class="foo"` will be unaffected by our styles. - -This is vastly simpler than achieving the same effect via [Shadow DOM](http://caniuse.com/#search=shadow%20dom) and works everywhere without polyfills. - -> Svelte will add a ` - -
- -
-``` - -> Scoped styles are *not* dynamic – they are shared between all instances of a component. In other words you can't use `{tags}` inside your CSS. - - -### Unused style removal - -Svelte will identify and remove styles that are not being used in your app. It will also emit a warning so that you can remove them from the source. - -For rules *not* to be removed, they must apply to the component's markup. As far as Svelte is concerned `.bold` is unused in the following code and should be removed: - -```html - -
-

this text is not bold

-
- - - - -``` - -Instead of manually manipulating the DOM, you should always use the `class` attribute (or the [class directive](https://svelte.technology/docs#classes)): - -```html - -
-

this text is bold

-
-``` - -If that's impossible for some reason, you can use `:global(...)`: - -```html - - -``` - -The same applies to the contents of `{@html ...}` tags. \ No newline at end of file diff --git a/site/content/docs/_old_docs/04-behaviour.md b/site/content/docs/_old_docs/04-behaviour.md deleted file mode 100644 index f0f4a4617b..0000000000 --- a/site/content/docs/_old_docs/04-behaviour.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Behaviours ---- - -As well as scoped styles and a template, components can encapsulate *behaviours*. For that, we add a ` - -
- -
-``` - - -### Internal state - -Often, it makes sense for a component to have internal state that isn't visible to the outside world. - -```html - - - -

Count: {count}

- -``` - - -### External properties - -On the other hand, for the component to form part of a system, it needs to expose certain values so that they can be set from outside. These are called *props*, and we use the `export` keyword to differentiate them from internal state: - -```html - - - -

Count: {count}

- -``` - -> Effectively, we're exporting a *contract* with the outside world. The `export` keyword normally means something different in JavaScript, so you might be surprised to see it used like this. Just roll with it for now! - -The `= 0` sets a default value for `count`, if none is provided. - -```js -const counter = new Counter({ - target: document.body, - props: { - count: 99 - } -}); - -counter.count; // 99 -counter.count += 1; // 100 -``` - -Props declared with `const` or `function` are *read-only* — they cannot be set from outside. This allows you to, for example, attach custom methods to your component: - -```js -component.doSomethingFun(); -``` - - -### Lifecycle hooks - -There are four 'hooks' provided by Svelte for adding control logic — `onMount`, `beforeUpdate`, `afterUpdate` and `onDestroy`. Import them directly from `svelte`: - -```html - - - - -``` - -> Lifecycle hooks do *not* run in server-side rendering (SSR) mode, with the exception of `onDestroy`. More on SSR later. diff --git a/site/content/docs/_old_docs/05-nested-components.md b/site/content/docs/_old_docs/05-nested-components.md deleted file mode 100644 index 1f5c34f8d5..0000000000 --- a/site/content/docs/_old_docs/05-nested-components.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Nested components ---- - -As well as containing elements (and `if` blocks and `each` blocks), Svelte components can contain *other* Svelte components. - -```html - - - -
- -
-``` - -```html - -

I am a nested component. The answer is {answer}

-``` - -That's similar to doing this... - -```js -import Widget from './Widget.html'; - -const widget = new Widget({ - target: document.querySelector('.widget-container'), - props: { - answer: 42 - } -}); -``` - -...except that Svelte takes care of destroying the child component when the parent is destroyed, and keeps props in sync if they change. - -> Component names must be capitalised, following the widely-used JavaScript convention of capitalising constructor names. It's also an easy way to distinguish components from elements in your template. - - -### Props - -Props, short for 'properties', are the means by which you pass data down from a parent to a child component — in other words, they're just like attributes on an element. As with element attributes, prop values can contain any valid JavaScript expression. - -Often, the name of the property will be the same as the value, in which case we can use a shorthand: - -```html - - - - -``` - -> Note that props are *one-way* — to get data from a child component into a parent component, use [bindings](docs#bindings). - - -### Composing with `` - -A component can contain a `` element, which allows the parent component to inject content: - -```html - - - - -

Hello!

-

This is a box. It can contain anything.

- -``` - -```html - - - -
- -
-``` - -The `` element can contain 'fallback content', which will be used if no children are provided for the component: - -```html - - - - -``` - -```html - - - -
- -

the box is empty!

- -
-``` - -You can also have *named* slots. Any elements with a corresponding `slot` attribute will fill these slots: - -```html - - - - - P. Sherman - 42 Wallaby Way, Sydney - -``` - -```html - - - -
-

- Unknown address -
- Unknown email -
-``` \ No newline at end of file diff --git a/site/content/docs/_old_docs/06-special-components.md b/site/content/docs/_old_docs/06-special-components.md deleted file mode 100644 index 7f632b4012..0000000000 --- a/site/content/docs/_old_docs/06-special-components.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Special elements ---- - -Svelte includes a handful of built-in elements with special behaviour. - - -### `` - -Sometimes, a component needs to embed itself recursively — for example if you have a tree-like data structure. In Svelte, that's accomplished with the `` tag: - -```html - -{#if countdown > 0} -

{countdown}

- -{:else} -

liftoff!

-{/if} -``` - -```json -/* { hidden: true } */ -{ - countdown: 5 -} -``` - - -### `` - -If you don't know what kind of component to render until the app runs — in other words, it's driven by state (aka a dynamic component) — you can use ``: - -```html - - - - foo - -``` - -```html - -

Red {name}

-``` - -```html - -

Blue {name}

-``` - -The expression inside the `this="{...}"` can be any valid JavaScript expression. - - -### `` - -The `` tag gives you a convenient way to declaratively add event listeners to `window`. Event listeners are automatically removed when the component is destroyed. - -```html - - - - - -{#if key} -

{key === ' ' ? 'Space' : key} (code {keyCode})

-{:else} -

click in this window and press any key

-{/if} -``` - -You can also bind to certain values — so far `innerWidth`, `outerWidth`, `innerHeight`, `outerHeight`, `scrollX`, `scrollY` and `online`: - -```html - - - - - -
-

user has scrolled {y} pixels

-``` - - -### `` - -The `` tag, just like ``, gives you a convenient way to declaratively add event listeners to the `document.body` object. This is useful for listening to events that don't fire on `window`, such as `mouseenter` and `mouseleave`. - - -### `` - -If you're building an application with Svelte — particularly if you're using [Sapper](https://sapper.svelte.technology) — then it's likely you'll need to add some content to the `` of your page, such as adding a `` element. - -You can do that with the `<svelte:head>` tag: - -```html -<!-- { title: '<svelte:head> tags' } --> -<svelte:head> - <title>{post.title} • My blog - -``` - -When [server rendering](docs#server-side-rendering), the `` contents can be extracted separately to the rest of the markup. diff --git a/site/content/docs/_old_docs/07-events.md b/site/content/docs/_old_docs/07-events.md deleted file mode 100644 index 6a8ff4006c..0000000000 --- a/site/content/docs/_old_docs/07-events.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Events ---- - -In most applications, you'll need to respond to the user's actions. In Svelte, this is done with the `on:[event]` directive. - -### Element events - -When used on an element, `on:click={handler}` is equivalent to calling `element.addEventListener('click', handler)`. When the element is removed, Svelte calls `removeEventListener` automatically. - -```html - -

Count: {count}

- -``` - -```json -/* { hidden: true } */ -{ - count: 0 -} -``` - -For more complicated behaviours, you'll probably want to declare an event handler in your ` - -

Count: {count}

- -``` - -```json -/* { hidden: true } */ -{ - count: 0 -} -``` - - -### Event handler modifiers - -While you can invoke methods like `event.stopPropagation` directly... - -```html - -
...
-``` - -...it gets annoying if you want to combine that with some other behaviour: - -```html - - - -
...
-``` - -For that reason, Svelte lets you use *event modifiers*: - -- [`preventDefault`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) -- [`stopPropagation`](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation) -- [`passive`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Parameters) — improves scrolling performance on touch/wheel events (Svelte will add it automatically where it's safe to do so) -- [`once`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Parameters) — removes the listener after the first invocation -- [`capture`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Parameter) - -> `passive` and `once` are not implemented in `legacy` mode - -The example above can be achieved with modifiers — no need for a separate event handler: - -```html - -
...
-``` - - -### Component events - -Events are an excellent way for [nested components](docs#nested-components) to communicate with their parents. Let's revisit our earlier example, but turn it into a `` component: - -```html - -

Select a category:

- -{#each categories as category} - -{/each} - - -``` - -When the user clicks a button, the component will fire a `select` event, where the `event` object has a `category` property. Any component that nests `` can listen for events like so: - -```html - - - - -``` - -```html - -

Select a category:

- -{#each categories as category} - -{/each} - - -``` - -Just as `this` in an element's event handler refers to the element itself, in a component event handler `this` refers to the component firing the event. - -There is also a shorthand for listening for and re-firing an event unchanged. - -```html - - - - -``` - -Since component events do not propagate as DOM events do, this can be used to pass events through intermediate components. This shorthand technique also applies to element events (`on:click` is equivalent to `on:click="fire('click', event)"`). diff --git a/site/content/docs/_old_docs/08-bindings.md b/site/content/docs/_old_docs/08-bindings.md deleted file mode 100644 index d0e4e23a9c..0000000000 --- a/site/content/docs/_old_docs/08-bindings.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Bindings ---- - - -### Bindings - -As we've seen, data can be passed down to elements and components with attributes and [props](docs#props). Occasionally, you need to get data back *up*; for that we use bindings. - - -#### Component bindings - -Component bindings keep values in sync between a parent and a child: - -```html - - -``` - -Whenever `childValue` changes in the child component, `parentValue` will be updated in the parent component and vice versa. - -If the names are the same, you can shorten the declaration: - -```html - - -``` - -> Use component bindings judiciously. They can save you a lot of boilerplate, but will make it harder to reason about data flow within your application if you overuse them. - - -#### Element bindings - -Element bindings make it easy to respond to user interactions: - -```html - -

Hello {name}!

- -``` - -```json -/* { hidden: true } */ -{ - name: 'world' -} -``` - -Some bindings are *one-way*, meaning that the values are read-only. Most are *two-way* — changing the data programmatically will update the DOM. The following bindings are available: - -| Name | Applies to | Kind | -|-----------------------------------------------------------------|----------------------------------------------|----------------------| -| `value` | `` `