Bitovi

can-define

Defines observable properties and their behavior on a prototype object. This function is not commonly used directly. can-define/map/map and can-define/list/list are more commonly used. Types and behaviors shared by both can-define/map/map and can-define/list/list are documented here.

`define(prototype, propDefinitions)`

The define function can be used to define observable properties, type conversion, and getter/setter logic on prototype objects. The define function is used by can-define/map/map and can-define/list/list to create observables. However, define can be used to create observables from types that do not inherit from can-define/map/map and can-define/list/list.

For more information on observables and how they are used in CanJS, please read the Technology Overview.

The following creates a Greeting type which will have observable message properties:

import {define, Reflect as canReflect} from "can";

const Greeting = function( message ) {
  this.message = message;
};

define( Greeting.prototype, {
  message: { type: "string" }
} );

const greeting = new Greeting("Hello");

canReflect.onKeyValue(greeting, "message", (newValue) => {
  console.log( newValue ); //-> logs "goodbye"
});

greeting.message = "goodbye";

Parameters

prototype {Object}:
The prototype object of a constructor function or class. The prototype object will have getter/setters defined on it that carry out the defined behavior. The prototype will also contain all of can-event-queue/map/map's methods.

propDefinitions {Object<String,PropDefinition>}:

An object of properties and their definitions. For example, a property (propertyName) has a PropDefinition object with zero or more of the following behaviors:

define(Type.prototype, {
  propertyName: {
    default: function() { /* ... */ },
    Default: Constructor,
    type: function() { /* ... */ },
    Type: Constructor,
    get: function() { /* ... */ },
    value: function() { /* ... */ },
    set: function() { /* ... */ },
    serialize: function() { /* ... */ },
    identity: Boolean
  }
})

Use

can-define provides a way to create custom types with observable properties. Where can-define/map/map and can-define/list/list provide more functionality, they also make more assumptions on the type constructor. can-define can be used to create completely customized types.

The following creates a Person constructor function that will be used to create Person instances with observable properties:

import {define} from "can";

// Define the type
const Person = function( first, last ) {
    this.first = first;
    this.last = last;
};
define( Person.prototype, {
    first: { type: "string" },
    last: { type: "string" },
    fullName: {
        get: function() {
            return this.first + " " + this.last;
        }
    }
} );

// Create an instance
const person = new Person( "Justin", "Meyer" );

console.log( person.first ); //-> "Justin"
console.log( person.last ); //-> "Meyer"
console.log( person.fullName ); //-> "Justin Meyer"

person.on( "fullName", function( ev, newVal, oldVal ) {
    console.log( newVal ); //-> "Ramiya Meyer"
    console.log( oldVal ); //-> "Justin Meyer"
} );

person.first = "Ramiya";

The observable properties call ObservationRecorder.add so they can be automatically by can-observation (and therefore can-stache).

Mixed-in instance methods and properties

define adds the following methods from can-event-queue/map/map:

addEventListener - Register an event handler to be called when an event is dispatched.
@can.getWhatIChange - Return observables whose values are affected by attached event handlers
@can.isBound - Return if the observable is bound to.
@can.offKeyValue - Unregister an event handler to be called when an event is dispatched.
@can.onKeyValue - Register an event handler to be called when a key value changes.
dispatch - Dispatch event and key binding handlers.
listenTo - Listen to an event and register the binding for simplified unbinding.
off - A shorthand method for unbinding an event.
on - A shorthand method for listening to event.
one - Register an event handler that gets called only once.
removeEventListener - Unregister an event handler to be called when an event is dispatched.
stopListening - Stops listening for registered event handlers.

can-define

define(prototype, propDefinitions)

Parameters

Use

Mixed-in instance methods and properties

Get help

`define(prototype, propDefinitions)`