Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

General documentation fixes (link to parent: CanJS#4116, Component#264, and Component#270) #288

Open
wants to merge 9 commits into
base: master
Choose a base branch
from
Open
3 changes: 3 additions & 0 deletions docs/ViewModel.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,7 @@ reference to the viewModel instance and modify it. This can be seen in the
following example:

@demo demos/can-component/accordion.html
@codepen
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of these should work as of this PR: canjs/canjs#4388


Clicking the __Change title__ button sets a `<my-panel>` element’s `title`
attribute like:
Expand Down Expand Up @@ -286,6 +287,7 @@ Component.extend( {
ViewModel methods get called back with the current context, the element that you are listening to and the event that triggered the callback.

@demo demos/can-component/paginate_next.html
@codepen

## Publishing events on ViewModels

Expand Down Expand Up @@ -317,3 +319,4 @@ The following demo uses this ability to create a close button that
hides the player editor:

@demo demos/can-component/paginate_next_event.html
@codepen
37 changes: 36 additions & 1 deletion docs/component.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ document.body.appendChild( renderer( { } ) );
Check this out here:

@demo demos/can-component/click_me.html

@codepen

Typically, you do not append a single component at a time. Instead,
you’ll render a view with many custom tags like:
Expand Down Expand Up @@ -273,6 +273,36 @@ Changes `<hello-world>Hi There</hello-world>` into:
<hello-world><h1>Hi There</h1></hello-world>
```

Essentially, the children of the component tag will be treated as it's [can-component/content],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's => its

to be rendered wherever the tag is provided in the component view.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the <content> tag.

(You might want to be explicit about which tag).


If no view is provided to a Component, it will render it's content naively.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you trying to say:

If no LIGHT DOM is provided to a component, it will render the element's LIGHT DOM?

We don't call the LIGHT DOM a view. The view is the component's view property.

By natively it sounds to me like something the BROWSER apis would just do.

Also it's => its

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think maybe it's more accurate to say if there is no view property on a Component, that Component will simply render its LIGHT_DOM


A component like this:

```js
Component.extend({
tag: "can-el",
ViewModel: {
hovMessage: {
default: "I'm from can-el viewModel",
}
}
});
```

Can be rendered like: `<can-el>Here's my content!</can-el>` into exactly what it looks like:

```html
<can-el>Here's my content!</can-el>
```

or you can render viewModel properties using magic tags like : `<can-el>{{hovMessage}}</can-el>`, which renders like:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can't do this without leakScope.


```html
<can-el>I'm from can-el viewModel</can-el>
```

### ViewModel

A component’s [can-component::ViewModel ViewModel] defines a constructor that creates
Expand Down Expand Up @@ -621,6 +651,8 @@ This would make `helloWorldInstance.element` a fragment with the following struc
<hello-world>Hello <em>mundo</em></hello-world>
```



### scope

You can also provide a `scope` with which the content should be rendered:
Expand Down Expand Up @@ -690,6 +722,7 @@ The following demos a tabs widget. Click “Add Vegetables”
to add a new tab.

@demo demos/can-component/tabs.html
@codepen

An instance of the tabs widget is created by creating `<my-tabs>` and `<my-panel>`
elements like:
Expand Down Expand Up @@ -724,6 +757,7 @@ vm.addPanel( this.viewModel );
The following tree combo lets people walk through a hierarchy and select locations.

@demo demos/can-component/treecombo.html
@codepen

The secret to this widget is the viewModel’s `breadcrumb` property, which is an array
of items the user has navigated through, and `selectableItems`, which represents the children of the
Expand Down Expand Up @@ -772,6 +806,7 @@ The following example shows 3
widget-like components: a grid, next / prev buttons, and a page count indicator. And, it shows an application component that puts them all together.

@demo demos/can-component/paginate.html
@codepen

This demo uses a `Paginate` [can-define/map/map] to assist with maintaining a paginated state:

Expand Down
26 changes: 26 additions & 0 deletions docs/content.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,29 @@ Component.extend( {
view: "<h1><content>Hi There!</content></h1>"
} );
```

The children of `<content>` can be used as a default value for rendering in the case that no content is passed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of "no content is passed", I think we probably should introduce the LIGHT_DOM and SHADOW_DOM concepts?

Or for CanJS, maybe these should be shadow view and light view?


for example:
```js
Component.extend( {
tag: "my-tag",
view: stache( "<h1><content>Hello world</content></h1>" )
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets remove the stache() part.

} );
```

used like `<my-tag></my-tag>`

will render:

```html
<my-tag><h1>Hello world</h1></my-tag>
```

When the content is specified, those children will be ignored:

`<my-tag>Hello friend</my-tag>` will render:

```html
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it would be cool if these were @codepen-able examples:

<my-tag>Hello Friend</my-tag>
<script type="module">
import {Component} from "can";

...
</script>

<my-tag><h1>Hello friend</h1></my-tag>
```
2 changes: 2 additions & 0 deletions docs/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,13 @@ while still accessing the `Component`’s [can-component::ViewModel]. The follo
example listens to clicks on elements with `className="next"` and calls `.next()` on the component’s viewModel.

@demo demos/can-component/paginate_events_next.html
@codepen

The events object can also listen to objects or properties on the component’s [can-component::ViewModel] instance. For instance, instead
of using live-binding, we could listen to when offset changes and update the page manually:

@demo demos/can-component/paginate_events_next_update_page.html
@codepen

### Special events: inserted and removed

Expand Down
1 change: 1 addition & 0 deletions docs/helpers.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@ uses an `isSelected` helper to render content for selected items. Click
one of the following libraries to toggle them within the `selected` array.

@demo demos/can-component/selected.html
@codepen
36 changes: 36 additions & 0 deletions docs/view.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ There are three things to understand about a [can-component]’s view:
The following example demonstrates all three features:

@demo demos/can-component/my_greeting_full.html
@codepen

The following explains how each part works:

Expand Down Expand Up @@ -211,3 +212,38 @@ it produces:
```html
<my-greeting><h1>Hello World</h1></my-greeting>
```

### Omitting view entirely

If the user does not provide a view property,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe:

If the component does not contain a view property ...

the content -whether defined or passed inline, will be rendered instead.

This means a component like this:

```js
Component.extend({
tag: "my-greeting",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

extra tab here?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure why this is showing up in Github, it doesn't show on my local text editor

})
```

will cause `<my-greeting>Hello Friend</my-greeting>` to render like:

```html
<my-greeting>Hello Friend</my-greeting>
```

and

```js
Component.extend({
tag: "my-greeting",
content: "Hello World"
})
```

to render like:


```html
<my-greeting>Hello World</my-greeting>
```