AFrameJS - Javascript MVC Library - API: AFrame → AFrame.Schema class

class AFrame.Schema

A basic data schema, useful for defining a data structure, validating data, and preparing data to be loaded from or saved to a persistence store.
Schema's define the data structure and can be nested to create complex data structures. Schemas perform serialization duties in fromSerializedJSON and toSerializedJSON. Finally, Schemas define ways to perform data validation.

When loading data from persistence, if the data is run through the fromSerializedJSON function, it will make an object with only the fields defined in the schema, and any missing fields will get default values. If a fixup function is defined for that row, the field's value will be run through the fixup function. When saving data to persistence, running data through the toSerializedJSON will create an object with only the fields specified in the schema. If a row has 'save: false' defined, the row will not be added to the form data object. If a row has a cleanup function defined, the corresponding data value will be run through the cleanup function.

Generic serialization functions can be set for a type using the AFrame.Schema.addDeserializer and AFrame.Schema.addSerializer. These are useful for doing conversions where the data persistence layer saves data in a different format than the internal application representation. A useful example of this is ISO8601 date<->Javascript Date. Already added types are 'number', 'integer', and 'iso8601'.

If a row in the schema config has the has_many field, the field is made into an array and the fixup/cleanup functions are called on each item in the array. The default default item for these fields is an empty array. If there is no data for the field in toSerializedJSON, the field is left out of the output.

// Schema defines four fields, two with validators
var librarySchemaConfig = {
    name: { type: 'text', validate: {
                minlength: 1,
                maxlength: 75,
                required: true
            } },
    version: { type: 'text', validate: {
                minlength: 1,
                required: true
           } },
    create_date: { type: 'iso8601' },
    downloads: { type: 'integer', fixup: downloadsFixup,
                     cleanup: downloadsCleanup }
};

function downloadsFixup( options ) {
     var value = options.value;
     if( value < 0 ) {
          value = 0;
     }
     return value;
};

function downloadsCleanup( options ) {
     var value = options.value;
     if( value < 0 ) {
          value = 0;
     }
     return value;
};

// recommended to use AFrame.Schema to create schemas so
// that duplicate schemas are not created for the same
// configuration.
var librarySchema = AFrame.Schema( librarySchemaConfig );

Constructor

Constructor	Parameters	Returns
`AFrame.Schema( )`

Methods

Methods	Returns	Description
`forEach( callback, context )`	`void`	↑ An iterator. Iterates over every row in the schema. The callback is called with the schema row and the key of the row. Parameters: `callback <function>` callback to call. `context <object>` (optional) context to call callback in
`fromSerializedJSON( dataToFix )`	`object`	↑ Fix a data object for use in the application. Creates a new object using the specified data as a template for values. If a value is not specified but a default value is specified in the schema, the default value is used for that item. Items are finally run through an optionally defined fixup function. If defined, the fixup function should return cleaned data. If the fixup function does not return data, the field will be undefined. `// dbData is data coming from the database, still needs to be // deserialized. var appData = schema.fromSerializedJSON( dbData );` Parameters: `dataToFix <object>` Returns: `<object>` fixedData
`getDefaults( )`	`object`	↑ Get an object with the default values specified. Only returns values of objects with a defined default. `// get the default values for all fields. var defaults = schema.getDefaults();` Returns: `<object>` object with default values
`getDefaultValue( key )`	`variant`	↑ Get the default value for a particular item `// get the default value for a particular item var value = schema.getDefaultValue( 'name' );` Parameters: `key <string>` name of item to get default value for Returns: `<variant>` default value if one is defined
`rowHasMany( rowName )`	`boolean`	↑ Check to see if a row is labeled with "has many" Parameters: `rowName <string>` Returns: `<boolean>` true if row is marked as "has_many", false otw.
`Schema.addDeserializer( type, callback )`	`void`	↑ Add a universal function that fixes data in fromSerializedJSON. This is used to convert data from a version the backend sends to one that is used internally. Parameters: `type <string>` type of field. `callback <function>` to call
`Schema.addSchemaConfig( type, config )`	`void`	↑ Add a schema config Parameters: `type <id>` identifier type `config <SchemaConfig>` the schema configuration
`Schema.addSerializer( type, callback )`	`void`	↑ Add a universal function that gets data ready to save to persistence. This is used to convert data from an internal representation of a piece of data to a representation the backend is expecting. Parameters: `type <string>` type of field. `callback <function>` to call
`Schema.getSchema( type )`	`Schema`	↑ Get a schema Parameters: `type <id>` type of schema to get, a config must be registered for type.
`toSerializedJSON( dataToSerialize )`	`object`	↑ Get an object suitable to send to persistence. This is based roughly on converting the data to a FormData "like" object - see MDC All items in the schema that do not have save parameter set to false and have values defined in dataToSerialize will have values returned. `// appData is data from the application ready to send to the // DB, needs serialized. var serializedData = schema.toSerializedJSON( appData );` Parameters: `dataToSerialize <object>` data to clean up Returns: `<object>` cleanedData
`validate( data, ignoreMissing )`	`variant`	↑ Validate a set of data against the schema `// validate, but ignore fields defined in the schema that are missing from data. var validity = schema.validate( data, true ); // validity is true if all data is valid // validity is an an object with each field in data, // for each field there is an [AFrame.FieldValidityState](AFrame.FieldValidityState.html)` Parameters: `data <object>` data to validate `ignoreMissing <boolean>` (optional) - if set to true, fields missing from data are not validated. Defaults to false. Note, even if set to true, and a field in data has an undefined value, the field will be validated against the the undefined value. Returns: `<variant>` true if all fields are valid, an object with each field in data, for each field there is an AFrame.FieldValidityState

Configuration Attributes

Attributes	Type	Description
`schema`	`{object}`	↑ The schema configuration to use for this schema