Skip to content

Commit

Permalink
renaming to StacheElement with static props
Browse files Browse the repository at this point in the history
  • Loading branch information
phillipskevin committed Jul 17, 2019
1 parent 7521d8b commit 0ceadf7
Show file tree
Hide file tree
Showing 28 changed files with 254 additions and 249 deletions.
2 changes: 1 addition & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ deploy:
I+oNEP2jfHBxU8FQ4k45YtJrLLrQqPiekV5NxoMEAgj5uelulVVipWz5qG+h/eXnscOkt0OUrsHf6T5IC4uKrd9RwM5R5txavNETFElTHaBjqJJpQiv8quTUrOjsnSQqFnjG7BL/gxWeMVSmUSXThLxCov6QFIjJSTb1Jk26q108gbCNk8kjP667RejUkFeqCXzsFmf8JTSwzmHo7M6ZuRH1/HRl4/Gx9yZCeMAzWvyTysKHqigJbLGmNBZRmbMJQJTvkqeO6J5RGjZ7TBhJ2IT9I2F9YMrjEUAN/71MgUk8ftgDs5GJpSECJIqu5cjeASXgNmlMQ6801UNiYq5X1yJOOxCw5VDwSctrOjUSQOpGnfzetjS6viDAjAbqHTNBdzQuyeLec0iXCB7GGE9qVrxlmhCm/g6bESokWIsMCj+Zz3IgpjUqP/8nHscEWkCk2I5YVsDN5TzEQL4SP1+Fi78f4tWMjwPCC8do2ZcVSB83ez69GDQh/r6Hax0KrGa+1aNdu4DP9BvFp4/cnEBwLuMMVNe0i5zGziSAxHslzo9VQc64kcYmOlAaTu82gSM+cC5+nznbh+8oihUjNLtaTlharTBOFFxs/7v35CW29YP82GzvzuiOqAqWNiZoa1EVmXurNNfcr2ToCEUKD894LqU5ItsTvzFO2jw4mwJRXFE=
'on':
tags: true
repo: canjs/can-stache-define-element
repo: canjs/can-stache-element
skip_cleanup: true
dist: xenial
services:
Expand Down
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Contributing to can-stache-define-element
# Contributing to can-stache-element

Check out the [contribution guide on CanJS.com](https://canjs.com/doc/guides/contribute.html) for information on:

Expand All @@ -13,7 +13,7 @@ The rest of this guide has information that’s specific to this repository.

## Developing Locally

This section will walk you through setting up the [repository](https://github.com/canjs/can-stache-define-element) on your computer.
This section will walk you through setting up the [repository](https://github.com/canjs/can-stache-element) on your computer.

### Signing up for GitHub

Expand All @@ -23,14 +23,14 @@ If you don’t already have a GitHub account, you’ll need to [create a new one

A “fork” is a copy of a repository in your personal GitHub account. “Cloning” is the process of getting the repository’s source code on your computer.

GitHub has a guide for [forking a repo](https://help.github.com/articles/fork-a-repo/). To fork can-stache-define-element, you can start by going to its [fork page](https://github.com/canjs/can-stache-define-element/fork).
GitHub has a guide for [forking a repo](https://help.github.com/articles/fork-a-repo/). To fork can-stache-element, you can start by going to its [fork page](https://github.com/canjs/can-stache-element/fork).

Next, you’ll want to clone the repo. [GitHub’s cloning guide](https://help.github.com/articles/cloning-a-repository/) explains how to do this on Linux, Mac, or Windows.

GitHub’s guide will [instruct you](https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork) to clone it with a command like:

```shell
git clone https://github.com/YOUR-USERNAME/can-stache-define-element
git clone https://github.com/YOUR-USERNAME/can-stache-element
```

Make sure you replace `YOUR-USERNAME` with your GitHub username.
Expand All @@ -44,7 +44,7 @@ First, make sure you’ve [installed Node.js and npm](https://docs.npmjs.com/get
If you just cloned the repo from the command line, you’ll want to switch to the folder with your clone:

```shell
cd can-stache-define-element
cd can-stache-element
```

Next, install the project’s dependencies with npm:
Expand Down
106 changes: 53 additions & 53 deletions docs/can-stache-define-element.md → docs/can-stache-element.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,38 @@
@module {function} can-stache-define-element
@module {function} can-stache-element
@parent can-views
@collection can-ecosystem
@group can-stache-define-element/static 0 static
@group can-stache-define-element/lifecycle-methods 1 lifecycle methods
@group can-stache-define-element/lifecycle-hooks 2 lifecycle hooks
@alias can.StacheDefineElement
@group can-stache-element/static 0 static
@group can-stache-element/lifecycle-methods 1 lifecycle methods
@group can-stache-element/lifecycle-hooks 2 lifecycle hooks
@alias can.StacheElement
@package ../package.json
@outline 2

@description Create a custom element with [can-define-object DefineObject]-like properties and [can-stache stache views].
@description Create a custom element with [can-define-object ObservableObject]-like properties and [can-stache stache views].

@signature `StacheDefineElement`
@signature `StacheElement`

`can-stache-define-element` exports a `StacheDefineElement` class used to define custom elements.
`can-stache-element` exports a `StacheElement` class used to define custom elements.

Extend `StacheDefineElement` with a:
Extend `StacheElement` with a:

- `static view` - A [can-stache stache] view.
- `static define` - [can-define-object DefineObject]-like property definitions.
- `static props` - [can-define-object ObservableObject]-like property definitions.
- getters, setters, and methods.
- lifecycle hooks - [can-stache-define-element/lifecycle-hooks.connected] and [can-stache-define-element/lifecycle-hooks.disconnected].
- lifecycle hooks - [can-stache-element/lifecycle-hooks.connected] and [can-stache-element/lifecycle-hooks.disconnected].

The following defines a `<count-er>` element:

```html
<count-er></count-er>
<script type="module">
import { StacheDefineElement } from "can/everything";
class Counter extends StacheDefineElement {
import { StacheElement } from "can/everything";
class Counter extends StacheElement {
static view = `
Count: <span>{{this.count}}</span>
<button on:click="this.increment()">+1</button>
`;
static define = {
static props = {
count: 0
};
increment() {
Expand Down Expand Up @@ -66,17 +66,17 @@

## Basic Use

The following sections cover everything you need to create a custom element with `StacheDefineElement`.
The following sections cover everything you need to create a custom element with `StacheElement`.

### Defining a custom element with a StacheDefineElement constructor
### Defining a custom element with a StacheElement constructor

In order to create a basic custom element with `StacheDefineElement`, create a class that extends `StacheDefineElement` and call [customElements.define](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) with the tag for the element and the constructor:
In order to create a basic custom element with `StacheElement`, create a class that extends `StacheElement` and call [customElements.define](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) with the tag for the element and the constructor:

```html
<count-er></count-er>
<script type="module">
import { StacheDefineElement } from "can/everything";
class Counter extends StacheDefineElement {
import { StacheElement } from "can/everything";
class Counter extends StacheElement {
}
customElements.define("count-er", Counter);
</script>
Expand All @@ -88,15 +88,15 @@ This custom element can be used by putting a `<count-er></count-er>` tag in an H

### Defining an element's view

StacheDefineElement uses [can-stache] to render live-bound HTML as the element's innerHTML.
StacheElement uses [can-stache] to render live-bound HTML as the element's innerHTML.

To create a [can-stache] view for the element, add a [can-stache-define-element/static.view static view] property to the class:
To create a [can-stache] view for the element, add a [can-stache-element/static.view static view] property to the class:

```html
<count-er></count-er>
<script type="module">
import { StacheDefineElement } from "can/everything";
class Counter extends StacheDefineElement {
import { StacheElement } from "can/everything";
class Counter extends StacheElement {
static view = `
Count: <span>{{this.count}}</span>
<button on:click="this.increment()">+1</button>
Expand All @@ -112,20 +112,20 @@ The element's HTML will automatically update when any of the element's propertie

### Defining an element's properties

To manage the logic and state of an element, [can-define-object DefineObject]-like property definitions can be added to explicitly configure how an element's properties are defined.
To manage the logic and state of an element, [can-define-object ObservableObject]-like property definitions can be added to explicitly configure how an element's properties are defined.

To add property definitions, add a [can-stache-define-element/static.define static define] object to the class:
To add property definitions, add a [can-stache-element/static.props static props] object to the class:

```html
<count-er></count-er>
<script type="module">
import { StacheDefineElement } from "can/everything";
class Counter extends StacheDefineElement {
import { StacheElement } from "can/everything";
class Counter extends StacheElement {
static view = `
Count: <span>{{this.count}}</span>
<button on:click="this.increment()">+1</button>
`;
static define = {
static props = {
count: 6
};
}
Expand All @@ -142,13 +142,13 @@ Methods (as well as getters and setters) can be added to the class body as well:
```html
<count-er></count-er>
<script type="module">
import { StacheDefineElement } from "can/everything";
class Counter extends StacheDefineElement {
import { StacheElement } from "can/everything";
class Counter extends StacheElement {
static view = `
Count: <span>{{this.count}}</span>
<button on:click="this.increment()">+1</button>
`;
static define = {
static props = {
count: 6
};
increment() {
Expand All @@ -163,19 +163,19 @@ customElements.define("count-er", Counter);

### Lifecycle hooks

If needed, [can-stache-define-element/lifecycle-hooks.connected] and [can-stache-define-element/lifecycle-hooks.disconnected] lifecycle hooks can be added to the class body. These will be called when the element is added and removed from the page, respectively.
If needed, [can-stache-element/lifecycle-hooks.connected] and [can-stache-element/lifecycle-hooks.disconnected] lifecycle hooks can be added to the class body. These will be called when the element is added and removed from the page, respectively.

```html
<button id="add">Add Timer</button>
<button id="remove">Remove Timer</button>
<script type="module">
import { StacheDefineElement } from "can/everything";
import { StacheElement } from "can/everything";
class Timer extends StacheDefineElement {
class Timer extends StacheElement {
static view = `
<p>{{this.time}}</p>
`;
static define = {
static props = {
time: { type: Number, default: 0 },
timerId: Number
};
Expand Down Expand Up @@ -213,33 +213,33 @@ Custom elements have [lifecycle methods](https://developer.mozilla.org/en-US/doc
- `connectedCallback` is called when the element is added to the page
- `disconnectedCallback` is called when the element is removed from the page

StacheDefineElement uses the custom element lifecycle methods to initiate its own lifecycle.
StacheElement uses the custom element lifecycle methods to initiate its own lifecycle.

The `connectedCallback` will call:

1. [can-stache-define-element/lifecycle-methods.initialize] - to set up the element's properties
2. [can-stache-define-element/lifecycle-methods.render] - to create the innerHTML of the element
3. [can-stache-define-element/lifecycle-methods.connect] - to connect the element to the DOM
1. [can-stache-element/lifecycle-methods.initialize] - to set up the element's properties
2. [can-stache-element/lifecycle-methods.render] - to create the innerHTML of the element
3. [can-stache-element/lifecycle-methods.connect] - to connect the element to the DOM

The `disconnectedCallback` will call:

1. [can-stache-define-element/lifecycle-methods.disconnect] - to clean up event handlers and call teardown functions
1. [can-stache-element/lifecycle-methods.disconnect] - to clean up event handlers and call teardown functions

StacheDefineElement's lifecycle methods can be used to test each part of the lifecycle. The following sections explain how to do this.
StacheElement's lifecycle methods can be used to test each part of the lifecycle. The following sections explain how to do this.

### Testing an element's properties and methods

To test an element's properties and methods, call the [can-stache-define-element/lifecycle-methods.initialize] method with any initial property values:
To test an element's properties and methods, call the [can-stache-element/lifecycle-methods.initialize] method with any initial property values:


```js
import { StacheDefineElement } from "can/everything";
class Counter extends StacheDefineElement {
import { StacheElement } from "can/everything";
class Counter extends StacheElement {
static view = `
Count: <span>{{this.count}}</span>
<button on:click="this.increment()">+1</button>
`;
static define = {
static props = {
count: 6
};
increment() {
Expand All @@ -260,16 +260,16 @@ counter.count === 21; // -> true

### Testing an element's view

To test an element's view, call the [can-stache-define-element/lifecycle-methods.render] method with any initial property values:
To test an element's view, call the [can-stache-element/lifecycle-methods.render] method with any initial property values:

```js
import { StacheDefineElement } from "can/everything";
class Counter extends StacheDefineElement {
import { StacheElement } from "can/everything";
class Counter extends StacheElement {
static view = `
Count: <span>{{this.count}}</span>
<button on:click="this.increment()">+1</button>
`;
static define = {
static props = {
count: 6
};
increment() {
Expand All @@ -290,16 +290,16 @@ counter.firstElementChild.innerHTML === "21"; // -> true

### Testing an element's lifecycle hooks

To test the functionality of the `connected` or `disconnected` hooks, you can call the [can-stache-define-element/lifecycle-methods.connect] or [can-stache-define-element/lifecycle-methods.disconnect] method.
To test the functionality of the `connected` or `disconnected` hooks, you can call the [can-stache-element/lifecycle-methods.connect] or [can-stache-element/lifecycle-methods.disconnect] method.

```js
import { StacheDefineElement } from "can/everything";
import { StacheElement } from "can/everything";

class Timer extends StacheDefineElement {
class Timer extends StacheElement {
static view = `
<p>{{this.time}}</p>
`;
static define = {
static props = {
time: { type: Number, default: 0 },
timerId: Number
};
Expand Down
20 changes: 10 additions & 10 deletions docs/connect.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
@function can-stache-define-element/lifecycle-methods.connect connect
@parent can-stache-define-element/lifecycle-methods 3
@function can-stache-element/lifecycle-methods.connect connect
@parent can-stache-element/lifecycle-methods 3

@description Connect a `StacheDefineElement` instance to the DOM.
@description Connect a `StacheElement` instance to the DOM.

@signature `connect(props)`

Calling `connect` will [can-stache-define-element/lifecycle-methods.initialize] and [can-stache-define-element/lifecycle-methods.render] an element and call its [can-stache-define-element/lifecycle-hooks.connected] hook. Normally this is called by the [can-stache-define-element/lifecycle-methods.connectedCallback], but can be called manually for testing:
Calling `connect` will [can-stache-element/lifecycle-methods.initialize] and [can-stache-element/lifecycle-methods.render] an element and call its [can-stache-element/lifecycle-hooks.connected] hook. Normally this is called by the [can-stache-element/lifecycle-methods.connectedCallback], but can be called manually for testing:

```js
import { StacheDefineElement } from "can/everything";
import { StacheElement } from "can/everything";

class MyElement extends StacheDefineElement {
class MyElement extends StacheElement {
static view = `
<p>{{this.age}}</p>
`;
static define = {
static props = {
age: { type: Number, default: 30 }
};
connected() {
Expand Down Expand Up @@ -46,8 +46,8 @@ For testing purposes or integration with other libraries, `connect` can be calle

The first time `connect` is called, it will:

- [can-stache-define-element/lifecycle-methods.initialize] the element with the property values passed to `connect`.
- [can-stache-define-element/lifecycle-methods.render] the stache view into the element.
- call the [can-stache-define-element/lifecycle-hooks.connected] lifecycle hook.
- [can-stache-element/lifecycle-methods.initialize] the element with the property values passed to `connect`.
- [can-stache-element/lifecycle-methods.render] the stache view into the element.
- call the [can-stache-element/lifecycle-hooks.connected] lifecycle hook.

Subsequent calls to `connect` will not have any effect.
14 changes: 7 additions & 7 deletions docs/connected.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
@function can-stache-define-element/lifecycle-hooks.connected connected
@parent can-stache-define-element/lifecycle-hooks
@function can-stache-element/lifecycle-hooks.connected connected
@parent can-stache-element/lifecycle-hooks

@description A lifecycle hook called after the element is inserted into the document.

@signature `connected()`

The `connected` hook is called by the [can-stache-define-element/lifecycle-methods.connectedCallback] when an element is added to the page. Code that needs to run when the element is in the page should be put in `connected` so that you do not need to worry about the rest of the lifecycle (you do not need to use `super` when implementing `connected`). The following example uses `connected` to increment a timer every second and returns a teardown function to clean up the timer:
The `connected` hook is called by the [can-stache-element/lifecycle-methods.connectedCallback] when an element is added to the page. Code that needs to run when the element is in the page should be put in `connected` so that you do not need to worry about the rest of the lifecycle (you do not need to use `super` when implementing `connected`). The following example uses `connected` to increment a timer every second and returns a teardown function to clean up the timer:

```html
<time-er></time-er>
<script type="module">
import { StacheDefineElement } from "can/everything";
import { StacheElement } from "can/everything";
class Timer extends StacheDefineElement {
class Timer extends StacheElement {
static view = `
<p>{{this.time}}</p>
`;
static define = {
static props = {
time: { type: Number, default: 0 }
};
connected() {
Expand All @@ -34,4 +34,4 @@
```
@codepen

@return {Function|undefined} A teardown function to be called during [can-stache-define-element/lifecycle-methods.disconnect disconnect]. This function can be used to tear down anything that was set up during `connected`, using any local variables in its closure.
@return {Function|undefined} A teardown function to be called during [can-stache-element/lifecycle-methods.disconnect disconnect]. This function can be used to tear down anything that was set up during `connected`, using any local variables in its closure.
Loading

0 comments on commit 0ceadf7

Please sign in to comment.