Awesome

Data Modelling

dmodel provides robust data modeling capabilities for managing individual objects themselves. dmodel provides a data model class that includes multiple methods on data objects, for saving, validating, and monitoring objects for changes.

dmodel can be used with dstore, such that objects that are returned from a store (whether it be from iterating over a collection, or performing a get()) can be set to be an instance of the store's data model by setting the model property of the store to a model class, such as dmodel/Model. With this setting, the objects are instances of this model, and they all inherit the following properties and methods:

Property Summary

Property Objects

One of the key ideas in the dmodel object model is the concept of property objects. A property object is a representation of single property on an object. The property object not only can provide the current value of a property, but can track meta-data about the property, such as property-specific validation information and whether or not the property is required. With the property object we can also monitor the property for changes, and modify the value of the property. A property object represents an encapsulation of a property that can easily be passed to different input components.

Property objects actually extend the data model class, so the methods listed for data objects above are available on property objects. The following additional methods are defined on property objects:

To get a property object from an data object, we simply call the property method:

var nameProperty = object.property('name');

Once we have the property object, we can access meta-data, watch, and modify this property:

nameProperty.required -> is it required?
nameProperty.observe(function(newValue){
	// called with original value and each change
});
nameProperty.put("Mark");
object.name -> "Mark"

Schema

A data model is largely defined through the schema. The model object has a schema property to define the schema object and the schema object has properties with definitions that correspond to the properties of model instances that they describe. Each property's value is a property definition. A property definition can be a simple string, defining the primitive type to be accepted, or it can be a property definition object. The property definition can have the following properties and/or methods:

The property definition defines the type, structure, metadata, and behavior of the properties on the model. If the property definition object is an instance of dmodel/Property, it will be used as the direct prototype for the instance property objects, as well. If not, the property definition will be used to construct a dmodel/Property instance, (properties are copied over), to use as the prototype of the instance property objects.

You can also define your own methods, to override the normal validation, access, and modification functionality of properties, by subclassing dmodel/Property or by directly defining methods in the property definition. The following methods can be defined or overriden:

Here is an example of creating a model using a schema:

MyModel = declare(Model, {
    schema: {
        firstName: 'string', // simple definition
        lastName: {
            type: 'string',
            required: true
        }
    }
});

We can then define our model as the model to be used for a store:

myStore = new Rest({
    model: MyModel
});

It is important to note that each store should have its own distinct model class.

Computed Property Values

A computed property may be defined on the schema, by using the the dmodel/ComputedProperty class. With a computed property, we can define a getValue() method to compute the value to be returned when a property is accessed. We can also define a dependsOn array to specify which properties we depend on. When the property is accessed or any of the dependent property changes, the property's value will be recomputed. The getValue is called with the values of the properties defined in the dependsOn array.

With a computed property, we may also want to write a custom setValue() method if we wish to support assignments to the computed property. A setValue() method may need to interact with the parent object to compute values and determine behavior. The parent is provided as the second argument.

Here is an example of a schema that with a computed property, fullName, that represents the concatenation of the firstName and the lastName:

schema: {
    firstName: 'string'
    lastName: 'string'
    fullName: {
        dependsOn: ['firstName', 'lastName'],
        getValue: function (firstName, lastName) {
            // compute the full name
            return firstName + ' ' + lastName;
        },
        setValue: function(value, parent){
            // support setting this property as well
            var parts = value.split(' ');
            parent.set('firstName', parts[0]);
            parent.set('lastName', parts[1]);
        }
    }
}

The items in the `dependsOn' on array can be property names, or they can be other property objects. If other property objects are used, the computed property can be used as a standalone entity (it can be observed and values directly retrieved from it), without having to be attached to another parent object. The items in this array can be mixed, and include the property's own value as well (using its own name).

Note, that traditional getters and setters can effectively be defined by creating valueOf() and put() methods on the property definition. However, this is generally eschewed in dmodel, since the primary use cases for getters and setters are better served by defining validation or creating a computed property.

Validators

Validators are Property subclasses with more advanced validation capabilities. dmodel includes several validators, that can be used, extended, or referenced for creating your own custom validators. To use a single validator, we can use it as the constructor for a property definition. For example, we could use the StringValidator to enforce the size of a string and acceptable characters:

schema: {
    username: new StringValidator({
        // must be at least 4 characters
        minimumLength: 4,
        // and max of 20 characters
        maximumLength: 20,
        // and only letters or numbers
        pattern: /^\w+$/
    })
}

dmodel include several pre-built validators. These are the available validators, and their properties:

• StringValidator - Enforces string length and patterns.
  • minimumLength - Minimum length of the string
  • maximumLength - Maximum length of the string
  • pattern - Regular expression to test against the string
  • minimumLengthError - Error message when minimum length fails
  • maximumLengthError - Error message when maximum length fails
  • patternMatchError - The error when a pattern does not match
• NumericValidator - Enforces numbers and ranges of numbers.
  • minimum - The minimum value for the value
  • maximum - The maximum value for the value
  • minimumError - The error message for values that are too low
  • maximumError - The error message for values that are too high
  • notANumberError - The error message for values that are not a number
• UniqueValidator - Enforces uniqueness of values, testing against a store.
  • uniqueStore - The store that will be accessed to determine if a value is unique
  • uniqueError - The error message for when the value is not unique

We can also combine validators. We can do this by using Dojo's declare() to mixin additional validators. For example, if we wanted to use the StringValidator in combination with the UniqueValidator, we could write:

schema: {
    username: new (declare([StringValidator, UniqueValidator]))({
        pattern: /^\w+$/,
        // the store to do lookups for uniqueness
        uniqueStore: userStore
    })
}

Or we can use the validators array to provide a set of validators that should be applied. For example, we could alternately write this:

schema: {
    username: {
        validators: [
            new StringValidator({pattern: /^\w+$/}),
            new UniqueValidator({uniqueStore: userStore})
        ]
    }
}

This can be particularly useful in our validators may have properties that collide with each other, or we generally just want to keep them distinct from the property.

Extensions

JSON Schema Based Models

Models can be defined through JSON Schema (v3). A store with a Model based on a JSON Schema can be created with the dmodel/extensions/jsonSchema module. For example:

define(['dmodel/extensions/jsonSchema', ...], function (jsonSchema, ...) {
    var myStore = new Memory({
        model: jsonSchema({
            properties: {
                someProperty: {
                    type: "number",
                    minimum: 0,
                    maximum: 10
                },
            }
        })
    })

Queue Notifications

dmodel will queue notifications so that multiple changes to a property can be delivered in a single notification. This is done for you automatically, to provide efficient notification of changes to listeners.

The queuing mechanism is beneficial in that it avoids repetitive or intermediate notifications that occur during multiple changes to a model object. For example, if we had the computed property for fullName as described above, and we change multiple properties in a single set():

person.set({
	firstName: 'John',
	lastName: 'Doe'
});

Without notification queuing, the notification listener might be called for each intermediate step in the process (once for the change to firstName, once for the change to lastName), but the queuing means that the computed property listener for fullName would only be called once, for the resulting change, after both the dependent properties have changed.

However, dmodel can be configured to use different strategies for when the queued notifications will be fired. By default, the notifications will be fired after the highest level set() operation completes. However, we can alternately configure dmodel to wait for the next event turn to fire notifications. This can be done by setting the Model.nextTurn property to another function that can defer the callback. For example, in NodeJS, we could use process.nextTick, or in the browser we could set it to setImmediate or setTimeout:

Model.nextTurn = window.setImmediate || setTimeout;

This would queue up all the notifications that occur before the next event turn, before calling the callbacks.

HiddenProperties Model

The dmodel/extensions/HiddenProperties module provides an extension of dmodel/Model where all the model properties are stored on a separate objects, rather than the model instance itself. This can provide a couple of advantages. First, model instances can be restored from persistence quicker since, the model instance simply needs to be instantiated with a reference to an existing object, rather than modifying the prototype chain. Second, this can be useful if you wish to protect properties from being directly accessed on the model object. Since the property values are stored on a separate object, this encourages property access through get, set, and property. This can be used as a model for stores, although you may want to use a custom query engine, depending on how you want property access to function during querying.

Stores

Validating

The dmodel/store/Validating module is a store mixin that adds functionality for validating any objects that are saved through put() or add(). The validation relies on the Model for the objects, so any property constraints that should be applied should be defined on the model's schema. If validation fails on put() or add() than a validation TypeError will be thrown, with an errors property that lists any validation errors.