documentation for the win

doc/views/index/associations.ejs

@@ -10,33 +10,16 @@ NOTE: Associations with models that use custom primaryKeys (so not the field 'id
 Because Sequelize is doing a lot of magic, you have to call Sequelize#sync after setting the associations!
 Doing so will allow you the following:
 
-<pre><%- koala(".js", partial("code/associations/associations-2.ejs")) %></pre>
+<pre><%- koala(".js", partial("code/associations/setter-and-getter.ejs")) %></pre>
 
 To remove created associations you can just call the set method without a specific id:
 
-<pre><%- koala(".js", partial("code/associations/associations-3.ejs")) %></pre>
+<pre><%- koala(".js", partial("code/associations/single-add-remove.ejs")) %></pre>
 
-You can also do it vice versa:
+You can of course also do it vice versa:
 
-<pre><%- koala(".js", partial("code/associations/associations-4.ejs")) %></pre>
+<pre><%- koala(".js", partial("code/associations/vice-versa.ejs")) %></pre>
 
 For hasOne its basically the same:
 
-<pre><%- koala(".js", partial("code/associations/associations-5.ejs")) %></pre>
-
-In order to specify many-to-many associations you can use the following syntax:
-
-<pre><%- koala(".js", partial("code/associations/associations-6.ejs")) %></pre>
-
-This will create a table, named according to the specified association names (= MembersProjects), 
-which just stores the id of a project and a member. Don't forget to call the sync method of the sequelize 
-instance.<br><br>
-
-Since v0.4.1 all association tables and association keys are named as the passed association names:
-
-<pre><%- koala(".js", partial("code/associations/associations-7.ejs")) %></pre>
-
-Sequelize v0.4.2 introduced a new possibility to load the associated objects from the database. 
-The relevant method is called <i>fetchAssociations</i> and returns a hash:
-
-<pre><%- koala(".js", partial("code/associations/associations-8.ejs")) %></pre>
\ No newline at end of file
+<pre><%- koala(".js", partial("code/associations/has-one-example.ejs")) %></pre>
\ No newline at end of file

doc/views/index/code/associations/associations-2.ejs

-Project.hasManyAndBelongsTo('tasks', Task, 'project')
-
-var project = new Project...
-var task1 = new Task...
-var task2 = new Task
-
-// save them... and then:
-project.setTasks([task1, task2], function(associatedTasks) {
-  // the associatedTasks are the very same as task1 and task2
-})
-
-// ok now they are save... how do I get them later on?
-project.getTasks(function(associatedTasks) {
-  // bam
-})
\ No newline at end of file

doc/views/index/code/associations/associations-5.ejs

-Task.hasOne('author', Author)
-Task.setAuthor(anAuthor)
\ No newline at end of file

doc/views/index/code/associations/associations-6.ejs

-Project.hasMany('members', Member, 'projects')
\ No newline at end of file

doc/views/index/code/associations/associations-7.ejs

-Person.hasOne('father', Person) // will create a foreign key 'fatherId'
-Person.hasOne('mother', Person) // will create a foreign key 'motherId'
-Person.hasMany('friends') // will create a table 'FriendsPeople' with friendId and personId
\ No newline at end of file

doc/views/index/code/associations/associations-8.ejs

-// Sequelize instantiation...
-var Person = sequelize.define('person', { name: Sequelize.STRING })
-var Pet = sequelize.define('pet', { name: Sequelize.STRING })
-Person.hasManyAndBelongsTo('pets', Pet, 'owner')
-// Table synchronization...
-var person  = new Person({ name: 'Luke' }),
-    pet1    = new Pet({ name: 'Bob' }),
-    pet2    = new Pet({ name: 'Aaron' })
-// Save the objects and associate them...
-person.fetchAssociations(function(assocs) {
-  // assocs == { pets: [pet1, pet2] }
-})
\ No newline at end of file

doc/views/index/code/associations/belongs-to.ejs

@@ -2,7 +2,7 @@ var User = sequelize.define('User', {/* ... */})
 var Project = sequelize.define('Project', {/* ... */})
 
 // One-way back associations
-Project.belongsTo('initiator', User)
+Project.belongsTo(User)
 
 /*
   In this example belongsTo will add an attribute UserId to the Project model!

doc/views/index/code/associations/has-many.ejs

@@ -3,7 +3,7 @@ var Project = sequelize.define('Project', {/* ... */})
 
 // OK. Now things get more complicated (not really visible to the user :)).
 // First let's define a hasMany association
-Project.hasMany('Workers', User, {as: 'Workers'})
+Project.hasMany(User, {as: 'Workers'})
 
 /*
   This will add the attribute ProjectId or project_id to User.
@@ -13,7 +13,7 @@ Project.hasMany('Workers', User, {as: 'Workers'})
   But we want more! Let's define the other way around:
 */
 
-User.hasMany('Projects', Project)
+User.hasMany(Project)
 
 /*
   This will remove the attribute ProjectId (or project_id) from User and create

doc/views/index/code/associations/has-one-example.ejs

+Task.hasOne(User, {as: "Author"})
+Task#setAuthor(anAuthor)
\ No newline at end of file

doc/views/index/code/associations/has-one.ejs

@@ -2,7 +2,7 @@ var User = sequelize.define('User', {/* ... */})
 var Project = sequelize.define('Project', {/* ... */})
 
 // One-way associations
-Project.hasOne('initiator', User)
+Project.hasOne(User)
 
 /*
   In this example hasOne will add an attribute ProjectId to the User model!
@@ -14,12 +14,12 @@ Project.hasOne('initiator', User)
   database and want to work on it:
 */
   
-Project.hasOne('inititator', User, { foreignKey: 'initiator_id' })
+Project.hasOne(User, { foreignKey: 'initiator_id' })
   
 /*
   Because Sequelize will use the model's name (first parameter of define) for
   the accessor methods, it is also possible to pass a special option to hasOne:
 */
 
-Project.hasOne('initiator', User, { as: 'Initiator' })
+Project.hasOne(User, { as: 'Initiator' })
 // Now you will get Project#getInitiator and Project#setInitiator
\ No newline at end of file

doc/views/index/code/associations/setter-and-getter.ejs

+Project.hasMany(Task)
+Task.hasMany(Project)
+
+Project.create()...
+Task.create()...
+Task.create()...
+
+// save them... and then:
+project.setTasks([task1, task2]).on('success', function() {
+  // saved!
+})
+
+// ok now they are save... how do I get them later on?
+project.getTasks().on('success', function(associatedTasks) {
+  // associatedTasks is an array of tasks
+})
\ No newline at end of file

doc/views/index/code/associations/associations-3.ejs → doc/views/index/code/associations/single-add-remove.ejs

 // remove the association with task1
-project.setTasks([task2], function(associatedTasks) {
+project.setTasks([task2]).on('success', function(associatedTasks) {
   // you will get task2 only
 })
 
 // remove 'em all
-projects.setTasks([], function(associatedTasks) {
+projects.setTasks([]).on('success', function(associatedTasks) {
   // you will get an empty array
 })
+
+// or remove 'em more directly
+projects.removeTask(task1).on('success', function() {
+  // it's gone
+})
+
+// and add 'em again
+projects.addTask(task1).on('success', function() {
+  // it's back again
+})
\ No newline at end of file

doc/views/index/code/associations/associations-4.ejs → doc/views/index/code/associations/vice-versa.ejs

 // project is associated with task1 and task2
-task2.setProject(null, function(associatedProject) {
-  // will return no associations
+task2.setProject(null).on('success', function() {
+  // and it's gone
 })
\ No newline at end of file

doc/views/index/code/find-objects/basics.ejs

+// search for known ids
+Project.find(123).on('success', function(project) {
+  // project will be an instance of Project and stores the content of the table entry 
+  // with id 123. if such an entry is not defined you will get null
+})
+
+// search for attributes
+Project.find({ where: {title: 'aProject'} }).on('succes', function(project) {
+  // project will be the first entry of the Projects table with the title 'aProject' || null
+})
+
+// find multiple entries
+Project.findAll().on('success', function(projects) {
+  // projects will be an array of all Project instances
+})
+
+// also possible:
+Project.all.on('success', function(projects) {
+  // projects will be an array of all Project instances
+})
+
+// search for specific attributes - hash usage
+Project.findAll({where: {name: 'A Project'}}).on('success', function(projects) {
+  // projects will be an array of Project instances with the specified name
+})
+
+// search with string replacements
+Project.findAll({where: ["id > ?", 25]}).on('success', function(projects) {
+  // projects will be an array of Projects having a greater id than 25
+})
+
+// or
+Project.findAll({where: "name = 'A Project'"}).on('success', function(projects) {
+  // the difference between this and the usage of hashes (objects) is, that string usage
+  // is not sql injection safe. so make sure you know what you are doing!
+})
\ No newline at end of file

doc/views/index/code/find-objects/finding-1.ejs

-Project.find(123, function(project) {
-  // project will be an instance of Project and stores the content of the table entry 
-  // with id 123 if such an entry is not defined you will get null
-})
-
-Project.find({ title: 'aProject' }, function(project) {
-  // project will be the first entry of the Projects table with the title 'aProject' || null
-})
-
-Project.findAll(function(projects) {
-  // projects will be an array of all Project instances
-})
-
-Project.findAll({where: "name = 'A Project'"}, function(persons) {
-  // projects will be an array of Project instances with the specified name
-})
\ No newline at end of file

doc/views/index/code/find-objects/finding-2.ejs

-Person.find(person.id, { fetchAssociations: true }, function(p) {
-  var petNames = p.fetchedAssociations.pets.map(function(pet) { return pet.name }).join(", ")
-  Sequelize.Helper.log('The person's pets: ' + petNames)
-})
\ No newline at end of file

doc/views/index/code/find-objects/options.ejs

+// define the order of the queried data
+Project.findAll({order: 'title DESC'})
+
+// limit the results of the query
+Project.findAll({limit: 10})
+
+// step over some elements
+// this only works with a specified limit
+Project.findAll({offset: 10, limit: 2})
\ No newline at end of file

doc/views/index/find-objects.ejs

+- where -> A hash with conditions (e.g. {name: 'foo'}) 
+           OR an ID as integer
+           OR a string with conditions (e.g. 'name="foo"').
+           If you use a string, you have to escape it on your own.
+- order -> e.g. 'id DESC'
+- group
+- limit -> The maximum count you want to get.
+- offset -> An offset value to start from. Only useable with limit!
+
+
 OK... you can define classes and associations. You can save them. You would probably like to get them from 
-the database again :-) Easy:
+the database again ;-) Easy:
 
-<pre><%- koala(".js", partial("code/find-objects/finding-1.ejs")) %></pre>
+<pre><%- koala(".js", partial("code/find-objects/basics.ejs")) %></pre>
 
-Since v0.4.3 there is an option for find methods, which forces the load of associated data. The resulting objects
-will store the data in the <i>fetchedAssociations</i> attribute:
+Of course you can pass a some options to the finder methods, to get more relevant data:
 
-<pre><%- koala(".js", partial("code/find-objects/finding-2.ejs")) %></pre>
\ No newline at end of file
+<pre><%- koala(".js", partial("code/find-objects/options.ejs")) %></pre>
\ No newline at end of file