DoneJS StealJS jQuery++ FuncUnit DocumentJS
3.14.1
5.0.0 4.3.0 2.3.35
  • About
  • Guides
  • API Docs
  • Community
  • Contributing
  • Bitovi
    • Bitovi.com
    • Blog
    • Design
    • Development
    • Training
    • Open Source
    • About
    • Contact Us
  • About
  • Guides
  • API Docs
    • Observables
      • can-compute
      • can-define
        • static
          • types
        • types
          • PropDefinition
        • behaviors
          • Type
          • Value
          • get
          • serialize
          • set
          • type
          • value
      • can-define/list/list
      • can-define/map/map
      • can-define-stream
      • can-define-stream-kefir
      • can-event
      • can-event/async/async
      • can-event/batch/batch
      • can-event/lifecycle/lifecycle
      • can-kefir
      • can-list
      • can-map
      • can-map-backup
      • can-map-define
      • can-observation
      • can-observe
      • can-simple-map
      • can-simple-observable
      • can-stream
      • can-stream-kefir
    • Data Modeling
      • can-connect
      • can-connect-cloneable
      • can-connect-feathers
      • can-connect-ndjson
      • can-connect-signalr
      • can-fixture
      • can-fixture-socket
      • can-ndjson-stream
      • can-set
    • Views
      • can-component
      • can-ejs
      • can-element
      • can-react-component
      • can-stache
      • can-stache/helpers/route
      • can-stache-bindings
      • can-stache-converters
      • can-view-autorender
      • can-view-callbacks
      • can-view-href
      • can-view-import
      • can-view-live
      • can-view-model
      • can-view-nodelist
      • can-view-parser
      • can-view-scope
      • can-view-target
      • react-view-model
      • react-view-model/component
      • steal-stache
    • Routing
      • can-deparam
      • can-param
      • can-route
      • can-route-pushstate
    • JS Utilities
      • can-assign
      • can-define-lazy-value
      • can-globals
      • can-key-tree
      • can-make-map
      • can-parse-uri
      • can-string
      • can-string-to-any
      • can-util
      • can-zone
      • can-zone-storage
    • DOM Utilities
      • can-ajax
      • can-attribute-encoder
      • can-control
      • can-dom-events
      • can-event-dom-enter
      • can-event-dom-radiochange
      • can-jquery
    • Data Validation
      • can-define-validate-validatejs
      • can-validate
      • can-validate-interface
      • can-validate-legacy
      • can-validate-validatejs
    • Typed Data
      • can-cid
      • can-construct
      • can-construct-super
      • can-namespace
      • can-reflect
      • can-reflect-promise
      • can-types
    • Polyfills
      • can-symbol
      • can-vdom
    • Core
    • Infrastructure
      • can-global
      • can-test-helpers
    • Ecosystem
    • Legacy
  • Community
  • Contributing
  • GitHub
  • Twitter
  • Chat
  • Forum
  • News
Bitovi

PropDefinition

  • Edit on GitHub

Defines the type, initial value, and get, set, and serialize behavior for an observable property. These behaviors can be specified with as an Object, String, Constructor function, Array, a getter expression, or setter expression.

Object

Defines multiple behaviors for a single property.

propertyName: {
  get: function(){ ... },
  set: function(){ ... },
  type: function(){ ... },
  Type: Constructor,
  value: function(){ ... },
  Value: Constructor,
  serialize: function(){ ... }
}

Options

  • value {value()}:

    Specifies the initial value of the property or a function that returns the initial value.

    // A default age of `0`:
    var Person = DefineMap.extend({
      age: {
        value: 0
      },
      address: {
        value: function(){
          return {city: "Chicago", state: "IL"};
        };
      }
    });
    
  • Value {Value()}:

    Specifies a function that will be called with new whose result is set as the initial value of the attribute.

    // A default empty DefineList of hobbies:
    var Person = DefineMap.extend({
      hobbies: {Value: DefineList}
    });
    
    new Person().hobbies //-> []
    
  • 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 types names.

    var Person = DefineMap.extend({
      age: {type: "number"},
      hobbies: {
        type: function(newValue){
          if(typeof newValue === "string") {
            return newValue.split(",")
          } else if( Array.isArray(newValue) ) {
            return newValue;
          }
        }
      }
    });
    
  • Type {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.

    var Address = DefineMap.extend({
      street: "string",
      state: "string"    
    });
    
    var Person = DefineMap.extend({
      address: {Type: Address}    
    });
    
  • set {set(newVal, resolve)}:

    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:

    DefineMap.extend({
      page: {
        set: function(newVal){
          this.offset = (parseInt(newVal) - 1) * this.limit;
        }
      }
    });
    
  • get {get(lastSetValue)}:

    A function that specifies how the value is retrieved. The get function is converted to an 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:

    DefineMap.extend({
      page: {
        get: function (newVal) {
          return Math.floor(this.offset / this.limit) + 1;
        }
      }
    });
    

    A get definition makes the property computed which means it will not be enumerable by default.

  • serialize {serialize()}:

    Specifies the behavior of the property when serialize is called.

    By default, serialize does not include computed values. Properties with a get definition are computed and therefore are not added to the result. Non-computed properties values are serialized if possible and added to the result.

    var Todo = DefineMap.extend({
      date: {
        type: "date",
        serialize: function(value) {
          return value.getTime();
        }
      }
    });
    

String

Defines a type converter as one of the named types in types.

propertyName: "typeName"

function()

Either creates a method or Defines a Type setting with a constructor function. Constructor functions are identified with isConstructorLike.

propertyName: Constructor

OR

propertyName: function() {}

For example:

subMap: DefineMap // <- sets Type to DefineMap

OR

increment: function() { ++this.count } // <- sets method prop

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.

propertyName: [Constructor | propDefinitions]

For example:

users: [User],
todos: [{complete: "boolean", name: "string"}]

GETTER

Defines a property's get behavior with the syntax.

get propertyName(){ ... }

For example:

get fullName() {
    return this.first + " " + this.last;
}

This is a shorthand for providing an object with a get property like:

fullName: {
    get: function(){
        return this.first + " " + this.last;
    }
}

You must use an object with a get property if you want your get to take the lastSetValue or resolve arguments.

SETTER

Defines a property's set behavior with the set syntax.

set propertyName(newValue){ ... }

For example:

set fullName(newValue) {
    var parts = newVal.split(" ");
    this.first = parts[0];
    this.last = parts[1];
}

This is a shorthand for providing an object with a set property like:

fullName: {
    set: function(newValue){
        var parts = newVal.split(" ");
        this.first = parts[0];
        this.last = parts[1];
    }
}

You must use an object with a set property if you want your set to take the resolve argument.

Use

A property definition can be defined in several ways. The Object form is the most literal and directly represents a PropDefinition object. The other forms get converted to a PropDefinition as follows:

DefineMap.extend({
  propertyA: Object      -> PropertyDefinition
  propertyB: String      -> {type: String}
  propertyC: Constructor -> {Type: Constructor}
  propertyD: [PropDefs]  -> {Type: DefineList.extend({"#": PropDefs})>}
  get propertyE(){...}   -> {get: propertyE(){...}}
  set propertyF(){...}   -> {get: propertyF(){...}}
  method: Function
})

Within a property definition, the available properties and their signatures look like:

DefineMap.extend({
  property: {
    get: function(lastSetValue, resolve){...},
    set: function(newValue, resolve){...},

    type: function(newValue, prop){...}| Array<PropertyDefinition> | PropertyDefinition,
    Type: Constructor | Array<PropertyDefinition> | PropertyDefinition,

    value: function(){...},
    Value: Constructor,

    serialize: Boolean | function(){...}
  }
})

For example:

var Person = DefineMap.extend("Person",{
  // a `DefineList` of `Address`
  addresses: [Address],
  // A `DefineMap` with a `first` and `last` property
  name: { type: {first: "string", last: "string"} },
  // A `DefineList of a ``DefineMap` with a `make` and `year` property.
  cars: { Type: [{make: "string", year: "number"}] }
});

var person = new Person({
  addresses: [{street: "1134 Pinetree"}],
  name: {first: "Kath", last: "Iann"}
  cars: [{ make: "Nissan", year: 2010 }]
});

CanJS is part of DoneJS. Created and maintained by the core DoneJS team and Bitovi. Currently 3.14.1.

On this page

Get help

  • Chat with us
  • File an issue
  • Ask questions
  • Read latest news