From dae3d9fe11568f7bcbb2ff4506c7489de1f76e9b Mon Sep 17 00:00:00 2001 From: Michael Cheng Date: Tue, 24 Jul 2018 11:46:38 -0400 Subject: [PATCH 1/8] add extra "content" documentation to can-component to address #270 --- docs/component.md | 32 ++++++++++++++++++++++++++++++++ docs/view.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/docs/component.md b/docs/component.md index e90e6ed..fc28926 100644 --- a/docs/component.md +++ b/docs/component.md @@ -273,6 +273,36 @@ Changes `Hi There` into:

Hi There

 ``` +Essentially, the children of the component tag will be treated as it's [can-component/content], +to be rendered wherever the tag is provided in the component view. + +If no view is provided to a Component, it will render it's content naively. + +A component like this: + +```js +Component.extend({ + tag: "can-el", + ViewModel: { + hovMessage: { + default: "I'm from can-el viewModel", + } + } +}); +``` + +Can be rendered like: `Here's my content!` into exactly what it looks like: + +```html +Here's my content! +``` + +or you can render viewModel properties using magic tags like : `{{hovMessage}}`, which renders like: + +```html +I'm from can-el viewModel +``` + ### ViewModel A component’s [can-component::ViewModel ViewModel] defines a constructor that creates @@ -621,6 +651,8 @@ This would make `helloWorldInstance.element` a fragment with the following struc Hello mundo ``` + + ### scope You can also provide a `scope` with which the content should be rendered: diff --git a/docs/view.md b/docs/view.md index 9bbe0ff..94650b9 100644 --- a/docs/view.md +++ b/docs/view.md @@ -211,3 +211,38 @@ it produces: ```html

Hello World

 ``` + +### Omitting view entirely + +If the user does not provide 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", +}) +``` + +will cause `Hello Friend` to render like: + +```html +Hello Friend +``` + +and + +```js +Component.extend({ + tag: "my-greeting", + content: "Hello World" +}) +``` + +to render like: + + +```html +Hello World +``` \ No newline at end of file From eefd91b9fe075fbf206222d0ac208e6b7dd1fd85 Mon Sep 17 00:00:00 2001 From: Michael Cheng Date: Tue, 24 Jul 2018 12:05:24 -0400 Subject: [PATCH 2/8] address issue #264, by adding example --- docs/content.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/content.md b/docs/content.md index 8e68ef9..9d4639e 100644 --- a/docs/content.md +++ b/docs/content.md @@ -35,3 +35,29 @@ Component.extend( { view: "

Hi There!

" } ); ``` + +the `` tag works like it's own component and will not render it's own `LIGHT_DOM` if not accounted for in it's markup + +for example: +```js +Component.extend( { + tag: "my-tag", + view: stache( "

Hello world

" ) +} ); +``` + +used like `` + +will render: + +```html +

Hello world

 +``` + +however, used like `Hello friend` + +will render: + +```html +

Hello friend

 +``` \ No newline at end of file From 14646f264630b04756e3879138788622bd1816fa Mon Sep 17 00:00:00 2001 From: Michael Cheng Date: Tue, 24 Jul 2018 12:05:24 -0400 Subject: [PATCH 3/8] address issue #264, by adding example --- docs/content.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/content.md b/docs/content.md index 8e68ef9..a9e7f0e 100644 --- a/docs/content.md +++ b/docs/content.md @@ -35,3 +35,29 @@ Component.extend( { view: "

Hi There!

" } ); ``` + +The children of `` can be used as a default value for rendering in the case that no content is passed. + +for example: +```js +Component.extend( { + tag: "my-tag", + view: stache( "

Hello world

" ) +} ); +``` + +used like `` + +will render: + +```html +

Hello world

 +``` + +When the content is specified, those children will be ignored: + +`Hello friend` will render: + +```html +

Hello friend

 +``` \ No newline at end of file From 65c71ea5f57531379887fa981340f366d9239293 Mon Sep 17 00:00:00 2001 From: Michael Cheng Date: Wed, 25 Jul 2018 13:29:45 -0400 Subject: [PATCH 4/8] add codepen to demos --- docs/ViewModel.md | 3 +++ docs/component.md | 5 ++++- docs/content.md | 10 ---------- docs/events.md | 2 ++ docs/helpers.md | 1 + docs/view.md | 1 + 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/ViewModel.md b/docs/ViewModel.md index 08033fb..1a85a34 100644 --- a/docs/ViewModel.md +++ b/docs/ViewModel.md @@ -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 Clicking the __Change title__ button sets a `` element’s `title` attribute like: @@ -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 @@ -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 \ No newline at end of file diff --git a/docs/component.md b/docs/component.md index fc28926..ad2edd4 100644 --- a/docs/component.md +++ b/docs/component.md @@ -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: @@ -722,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 `` and `` elements like: @@ -756,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 @@ -804,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: diff --git a/docs/content.md b/docs/content.md index 8fc54c7..a9e7f0e 100644 --- a/docs/content.md +++ b/docs/content.md @@ -36,11 +36,7 @@ Component.extend( { } ); ``` -<<<<<<< HEAD The children of `` can be used as a default value for rendering in the case that no content is passed. -======= -the `` tag works like it's own component and will not render it's own `LIGHT_DOM` if not accounted for in it's markup ->>>>>>> eefd91b9fe075fbf206222d0ac208e6b7dd1fd85 for example: ```js @@ -58,15 +54,9 @@ will render:

Hello world

 ``` -<<<<<<< HEAD When the content is specified, those children will be ignored: `Hello friend` will render: -======= -however, used like `Hello friend` - -will render: ->>>>>>> eefd91b9fe075fbf206222d0ac208e6b7dd1fd85 ```html

Hello friend

 diff --git a/docs/events.md b/docs/events.md index ffb4b63..3fff6db 100644 --- a/docs/events.md +++ b/docs/events.md @@ -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 diff --git a/docs/helpers.md b/docs/helpers.md index 8551abb..cde9c55 100644 --- a/docs/helpers.md +++ b/docs/helpers.md @@ -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 \ No newline at end of file diff --git a/docs/view.md b/docs/view.md index 94650b9..286a75b 100644 --- a/docs/view.md +++ b/docs/view.md @@ -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: From 2e6e5f725c552b858bfabbe06a9da541dc20b6df Mon Sep 17 00:00:00 2001 From: Michael Cheng Date: Thu, 26 Jul 2018 09:37:07 -0400 Subject: [PATCH 5/8] address PR comments --- docs/component.md | 38 ++++++++++++++++++++++++++++++++------ docs/content.md | 4 ++-- docs/view.md | 2 +- 3 files changed, 35 insertions(+), 9 deletions(-) diff --git a/docs/component.md b/docs/component.md index ad2edd4..e32208a 100644 --- a/docs/component.md +++ b/docs/component.md @@ -273,12 +273,12 @@ Changes `Hi There` into:

Hi There

 ``` -Essentially, the children of the component tag will be treated as it's [can-component/content], -to be rendered wherever the tag is provided in the component view. +Essentially, the children(`

Hi There

` above) of the Component tag(`` above) will be treated as its [can-component/content], +to be rendered wherever the tag is provided in the Component view. -If no view is provided to a Component, it will render it's content naively. +If a Component is defined without a view property, it will simply render whatever `LIGHT_DOM` it is given. -A component like this: +A Component like this: ```js Component.extend({ @@ -297,10 +297,36 @@ Can be rendered like: `Here's my content!` into exactly what it Here's my content! ``` -or you can render viewModel properties using magic tags like : `{{hovMessage}}`, which renders like: +And a set of Components, where one lacks a view: + +```js +Component.extend({ + tag: "can-el", + ViewModel: { + hovMessage: { + default: "I'm from can-el", + } + } +}); +Component.extend({ + tag: "can-simple", + view: "{{hovMessage}}", + ViewModel: { + hovMessage: { + default: "I'm from can-simple", + } + } +}); +``` + +can still be rendered like this ``, to show: ```html -I'm from can-el viewModel + + + I'm from can-el + + ``` ### ViewModel diff --git a/docs/content.md b/docs/content.md index a9e7f0e..ba06c37 100644 --- a/docs/content.md +++ b/docs/content.md @@ -36,13 +36,13 @@ Component.extend( { } ); ``` -The children of `` can be used as a default value for rendering in the case that no content is passed. +The children of `` present a `SHADOW_DOM` for rendering in the case that no `LIGHT_DOM` is passed and no `content` is defined. for example: ```js Component.extend( { tag: "my-tag", - view: stache( "

Hello world

" ) + view: "

Hello world

" } ); ``` diff --git a/docs/view.md b/docs/view.md index 286a75b..b49bd76 100644 --- a/docs/view.md +++ b/docs/view.md @@ -215,7 +215,7 @@ it produces: ### Omitting view entirely -If the user does not provide a view property, +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: From 52e7d59603851c24ab685fc07c2ee16b43f729aa Mon Sep 17 00:00:00 2001 From: Chasen Le Hara Date: Mon, 6 Aug 2018 15:02:47 -0700 Subject: [PATCH 6/8] Clean up the `view` docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Show an example of using leakScope to render LIGHT_DOM with a component’s VM - Rename the example component tags (anything with can-* looks like it’s from CanJS) - Various grammar fixes --- docs/component.md | 76 +++++++++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 33 deletions(-) diff --git a/docs/component.md b/docs/component.md index e32208a..c8d8294 100644 --- a/docs/component.md +++ b/docs/component.md @@ -273,60 +273,70 @@ Changes `Hi There` into:

Hi There

 ``` -Essentially, the children(`

Hi There

` above) of the Component tag(`` above) will be treated as its [can-component/content], -to be rendered wherever the tag is provided in the Component view. +In the example above, the child (`

Hi There

`) of the component’s element +(``) is treated as its [can-component/content] and rendered +wherever the `` placeholder is provided in the component’s `view`. -If a Component is defined without a view property, it will simply render whatever `LIGHT_DOM` it is given. - -A Component like this: +If a component is defined **without** a [can-component.prototype.view] property, +it will render whatever `LIGHT_DOM` it is given. For example, a component as +follows: ```js Component.extend({ - tag: "can-el", - ViewModel: { - hovMessage: { - default: "I'm from can-el viewModel", - } - } + tag: "my-el", + events: { + click: function() { + // Fired when the element is clicked + } + } }); ``` -Can be rendered like: `Here's my content!` into exactly what it looks like: +…used like so: ```html -Here's my content! +Here’s my content! ``` -And a set of Components, where one lacks a view: +…will be rendered as: + +```html +Here’s my content! +``` + +With [can-component.prototype.leakScope] enabled, the component’s ViewModel can +provide data to the LIGHT_DOM it contains, such that components like this: ```js Component.extend({ - tag: "can-el", - ViewModel: { - hovMessage: { - default: "I'm from can-el", - } - } + leakScope: true, + tag: "my-el", + ViewModel: { + message: { + default: "I’m from my-el", + } + } }); + Component.extend({ - tag: "can-simple", - view: "{{hovMessage}}", - ViewModel: { - hovMessage: { - default: "I'm from can-simple", - } - } + tag: "my-app", + view: "{{message}}", + ViewModel: { + message: { + default: "I’m from my-app", + } + } }); ``` -can still be rendered like this ``, to show: +…will be rendered as: ```html - - - I'm from can-el - - + + + I’m from my-el + + ``` ### ViewModel From b65fc93cade8a50a2e7c16f442e3cd81545ee5fa Mon Sep 17 00:00:00 2001 From: Chasen Le Hara Date: Mon, 6 Aug 2018 15:13:06 -0700 Subject: [PATCH 7/8] Clean up the `` docs - Add a link to the can-slot and can-template docs - Fix the grammar Closes https://github.com/canjs/can-component/issues/264 --- docs/content.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/content.md b/docs/content.md index ba06c37..2c71de3 100644 --- a/docs/content.md +++ b/docs/content.md @@ -38,7 +38,8 @@ Component.extend( { The children of `` present a `SHADOW_DOM` for rendering in the case that no `LIGHT_DOM` is passed and no `content` is defined. -for example: +For example: + ```js Component.extend( { tag: "my-tag", @@ -46,18 +47,18 @@ Component.extend( { } ); ``` -used like `` - -will render: +…used like `` will render: ```html

Hello world

 ``` -When the content is specified, those children will be ignored: - -`Hello friend` will render: +When the content is specified, the children of `` will be ignored such +that `Hello friend` will render: ```html

Hello friend

 -``` \ No newline at end of file +``` + +If you need to provide multiple pieces of content to a component, you should use +[can-component/can-slot] and [can-component/can-template]. From e5c952ab3f34b342f2b71c7f807994f6a692960a Mon Sep 17 00:00:00 2001 From: Chasen Le Hara Date: Mon, 6 Aug 2018 15:16:03 -0700 Subject: [PATCH 8/8] Clean up the `view` docs --- docs/view.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/view.md b/docs/view.md index b49bd76..0d00613 100644 --- a/docs/view.md +++ b/docs/view.md @@ -215,8 +215,8 @@ it produces: ### Omitting view entirely -If the Component does not contain a view property, -the content -whether defined or passed inline, will be rendered instead. +If a component does not have a `view` defined, +the content (whether defined or passed inline) will be rendered instead. This means a component like this: @@ -226,24 +226,23 @@ Component.extend({ }) ``` -will cause `Hello Friend` to render like: +…will cause `Hello Friend` to render like: ```html Hello Friend ``` -and +The following component: ```js Component.extend({ tag: "my-greeting", - content: "Hello World" + view: "Hello World" }) ``` -to render like: - +…will render like: ```html Hello World -``` \ No newline at end of file +```