Gallery

YUI({
    //Last Gallery Build of this module
    gallery: 'gallery-2012.04.18-20-14'
}).use('gallery-model-relate', function(Y) {
	var CompanyModel, EmployeeModel;
 
	// example company model that has a toMany relationship 'employees' to EmployeeModel
	CompanyModel = Y.Base.create('companyModel', Y.Model, [Y.ModelRelate], {}, {
		ATTRS: {
			name: {}
		},
		RELATIONSHIPS: {
			employees: {
				type: 'toMany',
				key: 'id',
				relatedModel: 'EmployeeModel',
				relatedKey: 'companyId'
			}
		}
	});
 
	// example employee model that has a toOne relationship 'company' to CompanyModel
	EmployeeModel = Y.Base.create('employeeModel', Y.Model, [Y.ModelRelate], {}, {
		ATTRS: {
			name: {},
			companyId: {}
		},
		RELATIONSHIPS: {
			company: {
				type: 'toOne',
				key: 'companyId',
				relatedModel: 'CompanyModel',
				relatedKey: 'id'
			}
		}
	});
 
	// creating an instance of a model extended with ModelRelate
	// automatically registers it with the ModelStore
	var foo = new CompanyModel({id: 1, name: 'Foo Inc.'});
	var joe = new EmployeeModel({id: 1, name: 'Joe Foo', companyId: 1});
 
	// use the getRelated method to return models matching the
	// 'employees' relationship defined on CompanyModel.  In
	// this case, a ModelList instance since 'employees' is defined
	// as a 'toMany' relationship
	var fooEmployees = foo.getRelated('employees');
 
	// fooEmployees is a modelList containing the joe model
 
	var larry = new EmployeeModel({id: 2, name: 'Larry Bar', companyId: 1});
 
	// fooEmployees now contains 2 employee models, joe and larry
 
	var joeCompany = joe.getRelated('company');
 
	// joeCompany is the Foo Inc. company model
 
	// aww, larry switched jobs
	larry.set('companyId', 2);
 
	// since we updated the companyId on the larry model, it no longer matches the companyId
        // on the fooEmployees relationship.  larry has been removed from the fooEmployees
        // relationship which now contains only the joe model.  larry still exists, just not as
        // part of the fooEmployees relationship
 
 
	// note:  Relationships are not actually created until the first call to 'getRelated'
	//        so defining a relationship and adding a bunch of related models prior to
	//        the first call to 'getRelated' does not incur any overhead
 
 
	// Now, lets say larry starts his own business
	var larryCo = new CompanyModel({name: 'LarryCo Ltd.'});
 
	larry.set('companyId', larryCo.get('id'));
 
	// model-relate changes the definition of a 'new' model.  Instead of setting id=null
	// new models have id=clientId so we always have a valid id for the relationship
 
	// now when we save larryCo to our database
	larryCo.save();
 
	// the relationship knows to update all the related models to the new id
	larryCo.get('id'); // == 5768 as assigned by the database
	larry.get('companyId'); // == 5678
	larryCo.getRelated('employees'); // modelList containing the larry model
	larry.getRelated('company'); // the larryCo model
 
	// if a related key changes not as the result of a new model being created, the relationship
	// is broken and will be refreshed with models in the store matching the new key
});