codepen documentation update (#375)

* propDef examples codepen ready and linked if able - The exception is identity and serialize - Examples indented by signatures and option don't seem to properly link * codepen-able example in defaultConstructor * added `@codepen` tag to [docs/default.md] * Made most examples codepenable for get * added log for propDefinition function type * fixed capitalization error in [docs/types.propDefinition.md]. * Added working codepen examples to set. * linking DefineMap and DefineList to Use in type * Removed legacy code from types.get * updated text to reference can-simple-observable instead of can-compute in one place. * changed to updating to latest practises on an example * Changed constructor to shorthand, return from map. - Constructor needs `new` keyword in shorthand. I was unable to get it to work properly by just assigning `DefaultList`. - Now returning in map example to properly get and return keys. * reverted some changes in 73cc278. * fullNameChangeCount example in use section now working and linked to codepen
canjs · Aug 23, 2018 · c9fe2e1 · c9fe2e1
1 parent 2c6d22b
commit c9fe2e1
Show file tree

Hide file tree

Showing 7 changed files with 144 additions and 70 deletions.
diff --git a/docs/default.md b/docs/default.md
@@ -27,7 +27,7 @@ If the default value should be an object of some type, it should be specified as
 
 Any value can be provided as the default value used for this property, like:
 
-```
+```js
 {
 	prop: {
 		default: 'foo'
@@ -44,6 +44,7 @@ Any value can be provided as the default value used for this property, like:
 The following defaults `age` to `0` and `address` to an object:
 
 ```js
+import { DefineMap } from "can"
 // A default age of `0`:
 const Person = DefineMap.extend( {
 	age: {
@@ -55,7 +56,11 @@ const Person = DefineMap.extend( {
 		}
 	}
 } );
+
+const person = new Person();
+console.log(person.age); //-> 0
 ```
+@codepen
 
 ## Alternates
 

diff --git a/docs/defaultConstructor.md b/docs/defaultConstructor.md
@@ -27,6 +27,8 @@ Specify `Default` like:
 ## Use
 
 ```js
+import { DefineMap } from "can";
+
 const Address = DefineMap.extend( {
 	street: { type: "string", value: "321 Longbow" },
 	city: { type: "string", value: "Dallas" }
@@ -41,6 +43,7 @@ const direction = new Direction( {
 	to: { street: "2070 N. Stave" }
 } );
 
-direction.from.street; //-> "321 Longbow"
-direction.to.street;   //-> "2070 N. Stave"
+console.log(direction.from.street); //-> "321 Longbow"
+console.log(direction.to.street);   //-> "2070 N. Stave"
 ```
+@codepen
diff --git a/docs/type.md b/docs/type.md
@@ -82,8 +82,8 @@ as either:
 
 - A type function that returns the type coerced value.
 - A named type in [can-define.types].
-- An object that gets converted into an inline `DefineMap`.
-- An array that gets converted to an inline `DefineList`.
+- An object that gets converted into an inline `[can-define/map/map DefineMap]`.
+- An array that gets converted to an inline `[can-define/list/list DefineList]`.
 
 ### Basic Example
 

diff --git a/docs/types.get.md b/docs/types.get.md
@@ -25,7 +25,7 @@ Specify `get` like:
 ```
 
   @param {*} [lastSetValue] The value last set by `instance.propertyName = value`.  Typically, _lastSetValue_
-  should be an observable value, like a [can-compute] or promise. If it's not, it's likely
+  should be an observable value, like a [can-simple-observable] or promise. If it's not, it's likely
   that a [can-define.types.set] should be used instead.
 
   @return {*} The value of the property.
@@ -74,6 +74,8 @@ Whenever a getter is provided, it is wrapped in a [can-compute], which ensures
 that whenever its dependent properties change, a change event will fire for this property also.
 
 ```js
+import { DefineMap } from "can";
+
 const Person = DefineMap.extend( {
 	first: "string",
 	last: "string",
@@ -86,21 +88,24 @@ const Person = DefineMap.extend( {
 
 const p = new Person( { first: "Justin", last: "Meyer" } );
 
-p.fullName; // "Justin Meyer"
+console.log(p.fullName); //-> "Justin Meyer"
 
 p.on( "fullName", function( ev, newVal ) {
-	newVal; //-> "Lincoln Meyer";
+	console.log(newVal); //-> "Lincoln Meyer";
 } );
 
 p.first = "Lincoln";
 ```
+@codepen
 
 ## Asynchronous virtual properties
 
 Often, a virtual property's value only becomes available after some period of time.  For example,
 given a `personId`, one might want to retrieve a related person:
 
 ```js
+import { DefineMap } from "can";
+
 const AppState = DefineMap.extend( {
 	personId: "number",
 	person: {
@@ -167,22 +172,25 @@ For example, a property might be set to a compute, but when read, provides the v
 of the compute.
 
 ```js
+import { DefineMap, SimpleObservable, Reflect } from "can";
+
 const MyMap = DefineMap.extend( {
-	value: {
-		get: function( lastSetValue ) {
-			return lastSetValue();
-		}
-	}
+    value: {
+        get: function( lastSetValue ) {
+            return lastSetValue.value;
+        }
+    }
 } );
 
 const map = new MyMap();
-const compute = compute( 1 );
-map.value = compute;
+const observable = new SimpleObservable( 1 );
+map.value = observable;
 
-map.value; //-> 1
-compute( 2 );
-map.value; //-> 2
+console.log(map.value); //-> 1
+Reflect.setValue(observable, 2);
+console.log(map.value); //-> 2
 ```
+@codepen
 
 This technique should only be used when the `lastSetValue` is some form of
 observable, that when it changes, can update the `getter` value.
@@ -200,16 +208,24 @@ the [can-define/list/list] will be updated with the `id`s of the `locations`.
 
 
 ```js
+import { DefineMap, DefineList } from "can";
+
 const Store = DefineMap.extend( {
-	locations: DefineList,
+	locations: { Default: DefineList },
 	locationIds: {
 		Default: DefineList,
 		get: function( initialValue ) {
 			const ids = this.locations.map( function( location ) {
-				ids.push( location.id );
+				return location.id;
 			} );
 			return initialValue.replace( ids );
 		}
 	}
 } );
+
+const s = new Store();
+console.log(s.locationIds[0]); //-> undefined
+s.locations.push({ id: 1 });
+console.log(s.locationIds[0]); //-> 1
 ```
+@codepen
diff --git a/docs/types.propDefinition.md b/docs/types.propDefinition.md
@@ -23,40 +23,46 @@ observable property.  These behaviors can be specified with as an `Object`, `Str
 }
 ```
 
-    @option {can-define.types.default} default Specifies the initial value of the property or
-    a function that returns the initial value.
+    @option {can-define.types.default} default Specifies the initial value of the property or a function that returns the initial value.
 
     ```js
+import { DefineMap } from "can";
+
 // A default age of `0`:
 const Person = DefineMap.extend( {
-	age: {
-		value: 0
-	},
-	address: {
-		value: function() {
-			return { city: "Chicago", state: "IL" };
-		}
-	}
+    age: {
+        default: 0
+    },
+    address: {
+        default: function() {
+            return { city: "Chicago", state: "IL" };
+        }
+    }
 } );
+
+const person = new Person();
+console.log(person.age); //->  0
 ```
 
-    @option {can-define.types.defaultConstructor} Default Specifies a function that will be called with `new` whose result is
-    set as the initial value of the attribute.
+    @option {can-define.types.defaultConstructor} Default Specifies a function that will be called with `new` whose result is set as the initial value of the attribute.
 
     ```js
+import { DefineMap, DefineList } from "can";
+
 // A default empty DefineList of hobbies:
 const Person = DefineMap.extend( {
 	hobbies: { Default: DefineList }
 } );
 
-new Person().hobbies; //-> []
+const person = new Person();
+console.log(person.hobbies); //-> []
 ```
 
-    @option {can-define.types.type} type Specifies the type of the
-    property.  The type can be specified as either a function
-    that returns the type coerced value or one of the [can-define.types] names.
+    @option {can-define.types.type} type Specifies the type of the property. The type can be specified as either a function that returns the type coerced value or one of the [can-define.types] names.
 
     ```js
+import { DefineMap } from "can";
+
 const Person = DefineMap.extend( {
 	age: { type: "number" },
 	hobbies: {
@@ -69,13 +75,16 @@ const Person = DefineMap.extend( {
 		}
 	}
 } );
+
+const person = new Person({ age: 20, hobbies: "1,2,3" });
+console.log(person.age, person.hobbies); //-> 20, [1,2,3]
 ```
 
-    @option {can-define.types.typeConstructor} Type A constructor function that takes
-    the assigned property value as the first argument and called with new. For example, the following will call
-    `new Address(newValue)` with whatever non null, undefined, or address type is set as a `Person`'s address property.
+    @option {can-define.types.typeConstructor} Type A constructor function that takes the assigned property value as the first argument and called with new. For example, the following will call `new Address(newValue)` with whatever non null, undefined, or address type is set as a `Person`'s address property.
 
     ```js
+import { DefineMap } from "can";
+
 const Address = DefineMap.extend( {
 	street: "string",
 	state: "string"
@@ -84,22 +93,32 @@ const Address = DefineMap.extend( {
 const Person = DefineMap.extend( {
 	address: { Type: Address }
 } );
-```
-
 
+const person = new Person({
+    address: {
+        street: "Example Ave.",
+        state: "IL"
+    }
+});
+console.log(person.address.street); //-> "Example Ave."
+```
 
-    @option {can-define.types.get} get A function that specifies how the value is retrieved.  The get function is
-    converted to an [can-compute.async async compute].  It should derive its value from other values on the object. The following
-    defines a `page` getter that reads from a map's offset and limit:
+    @option {can-define.types.get} get A function that specifies how the value is retrieved.  The get function is converted to an [can-compute.async async compute].  It should derive its value from other values on the object. The following defines a `page` getter that reads from a map's offset and limit:
 
     ```js
-DefineMap.extend( {
+import { DefineMap } from "can";
+
+const pages = DefineMap.extend( {
+    offset: 10,
+    limit: 5,
 	page: {
 		get: function( newVal ) {
 			return Math.floor( this.offset / this.limit ) + 1;
 		}
 	}
 } );
+
+console.log(pages.page) //-> 3
 ```
 
     A `get` definition makes the property __computed__ which means it will not be enumerable by default.
@@ -109,7 +128,9 @@ DefineMap.extend( {
     counts the number of times the `page` property changes:
 
     ```js
-DefineMap.extend( {
+import { DefineMap } from "can";
+
+const book = DefineMap.extend( {
 	pageChangeCount: function( prop ) {
 		let count = 0;
 
@@ -122,12 +143,14 @@ DefineMap.extend( {
 		prop.resolve( count );
 	}
 } );
+book.page = 1;
+book.page += 1;
+console.log(book.count); //-> 2
 ```
 
     A `value` definition makes the property __computed__ which means it will not be enumerable by default.
 
-    @option {can-define.types.set} set A set function that specifies what should happen when a property is set. `set` is called with the result of `type` or `Type`. The following
-    defines a `page` setter that updates the map's offset:
+    @option {can-define.types.set} set A set function that specifies what should happen when a property is set. `set` is called with the result of `type` or `Type`. The following defines a `page` setter that updates the map's offset:
 
     ```js
 DefineMap.extend( {
@@ -206,7 +229,7 @@ OR
 @type {Array} Defines an inline [can-define/list/list] Type setting. This is
 used as a shorthand for creating a property that is an [can-define/list/list] of another type.
 
-```
+```js
 {
 	propertyName: [Constructor | propDefinitions]
 }
@@ -252,11 +275,9 @@ This is a shorthand for providing an object with a `get` property like:
 }
 ```
 
-You must use an object with a [can-define.types.get] property if you want your get to take the `lastSetValue`
-or `resolve` arguments.
+You must use an object with a [can-define.types.get] property if you want your get to take the `lastSetValue` or `resolve` arguments.
 
-@type {SETTER} Defines a property's [can-define.types.set] behavior with the
-[set syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set).
+@type {SETTER} Defines a property's [can-define.types.set] behavior with the [set syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set).
 
 ```js
 {
@@ -278,7 +299,7 @@ For example:
 
 This is a shorthand for providing an object with a `set` property like:
 
-```
+```js
 {
 	fullName: {
 	    set: function(newValue){
@@ -305,19 +326,19 @@ get converted to a `PropDefinition` as follows:
 
 ```js
 DefineMap.extend( {
-	propertyA: Object,      // -> PropertyDefinition
-	propertyB: String,      // -> {type: String}
-	propertyC: Constructor, // -> {Type: Constructor}
-	propertyD: [ PropDefs ],  // -> {Type: DefineList.extend({"#": PropDefs})>}
+	propertyA: Object,          // -> PropertyDefinition
+	propertyB: String,          // -> {type: String}
+	propertyC: Constructor,     // -> {Type: Constructor}
+	propertyD: [ PropDefs ],    // -> {Type: DefineList.extend({"#": PropDefs})>}
 	get propertyE() { /* ... */ },   // -> {get: propertyE(){ /* ... */ }}
-	set propertyF( value ) { /* ... */ },   // -> {set: propertyF(value){ /* ... */ }}
+	set propertyF( value ) { /* ... */ },   // -> {set: propertyF(value){ /* ... */ }},
 	method: Function
 } );
 ```
 
 Within a property definition, the available properties and their signatures look like:
 
-```
+```js
 DefineMap.extend({
   property: {
     get: function(lastSetValue, resolve){...},
@@ -338,6 +359,12 @@ For example:
 
 
 ```js
+import { DefineMap } from "can";
+const Address = DefineMap.extend( "Address", {
+    street: "string",
+    state: "string"
+} );
+
 const Person = DefineMap.extend( "Person", {
 
 	// a `DefineList` of `Address`
@@ -355,4 +382,9 @@ const person = new Person( {
 	name: { first: "Kath", last: "Iann" },
 	cars: [ { make: "Nissan", year: 2010 } ]
 } );
+
+console.log(person.addresses[0].street); //-> "1134 Pinetree"
+console.log(person.name.first); //-> "Kath"
+console.log(person.cars[0].make); //-> "Nissan"
 ```
+@codepen