index.ejs

<script type="text/javascript" charset="utf-8">
  document.observe("dom:loaded", function() { buildNavigation([], []) })
</script>

<div>
  <a name="sequelize"></a>
  <h1>Sequelize</h1>
  <p>
    The Sequelize library provides easy access to a MySQL database by mapping database
    entries to objects and vice versa. To put it in a nutshell... it's an ORM (Object-Relational-Mapper).
    The library is written entirely in JavaScript and can be used in the Node.JS environment.
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="installation"></a>
  <h2>Installation</h2>
  <p>
    Sequelize will have a Kiwi package in future. For now, you can install it via NPM or just download 
    the code from the git repository and require Sequelize.js:
    
    <pre><%= partial("installation.ejs") %></pre>
    
    This will make the class Sequelize available.
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="basicMapping"></a>
  <h2>Basic Mapping</h2>
  <p>
    To get the ball rollin' you first have to create an instance of Sequelize. Use it the following way:

    <pre><%- koala.render(".js", "var sequelize = new Sequelize('database', 'username', 'password')") %></pre>

    This will save the passed database credentials and provide all further methods. Furthermore you can specify
    a non-default host or port and some options:
    
    <pre><%- koala.render(".js", partial("advancedInstantiation.ejs")) %></pre>
    
    To define mappings between a class (Stop telling me that JavaScript don't know classes. Name it however you want to!) 
    and a table, use the define method:

    <pre><%- koala.render(".js", partial("basicMapping1.ejs")) %></pre>
    
    Sequelize currently supports the following datatypes:

    <pre><%= partial("basicMapping2.ejs") %></pre>
    
    You can also store your model definitions in a single file using the import method:

    <pre><%- koala.render(".js", partial("basicMapping3.ejs")) %></pre>
    
    Choose the name of the exported function the way you want. It doesn't matter at all. You can also specify multiple
    models in one file. The import method will return a hash, which stores the result of sequelize.define under the key <i>Project</i>.
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="sync"></a>
  <h2>Synchronize with database</h2>
  <p>
    When starting a new project you won't have a database structure and using Sequelize you won't need to. Just specify 
    your model structures and let the library do the rest.<br><br>
    
    Currently supported is the creation and deletion of tables:
    
    <pre><%- koala.render(".js", partial("sync1.ejs")) %></pre>
    
    Because synchronizing and dropping all of your tables might be a lot of lines to write, you can also let
    Sequelize do the work for you:
    
    <pre><%- koala.render(".js", partial("sync2.ejs")) %></pre>
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="models"></a>
  <h2>Creating and working with instances</h2>
  <p>
    In order to create instances of defined classes just do it as follows:
    
    <pre><%- koala.render(".js", partial("models1.ejs")) %></pre>
    
    To save it in the database use the save method and pass a callback to it, if needed:
    
    <pre><%- koala.render(".js", partial("models2.ejs")) %></pre>
    
    Now lets change some values and save changes to the database... There are two ways to do that:
    
    <pre><%- koala.render(".js", partial("models3.ejs")) %></pre>
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="expandingModels"></a>
  <h2>Expanding models</h2>
  <p>
    Sequelize allows you to pass custom class and instance methods. Just do the following:
    
    <pre><%- koala.render(".js", partial("expand.ejs")) %></pre>
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="chainQueries"></a>
  <h2>Chain queries</h2>
  <p>
    Because you will want to save several items at once and just go on after all of them are saved, Sequelize provides a handy helper for that:

    <pre><%- koala.render(".js", partial("chainQueries1.ejs")) %></pre>
    
    And a real example:

    <pre><%- koala.render(".js", partial("chainQueries2.ejs")) %></pre>

    You can also pass params to the method... and of course you can also call other methods, which trigger a callback:

    <pre><%- koala.render(".js", partial("chainQueries3.ejs")) %></pre>
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="associations"></a>
  <h2>Associations</h2>
  <p>
    With Sequelize you can also specify associations between multiple classes. Doing so will help you to easily 
    access and set those associated objects. The library therefore provides for each defined class the method 
    the following methods:
    
    <pre><%- koala.render(".js", partial("associations1.ejs")) %></pre>
    
    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.render(".js", partial("associations2.ejs")) %></pre>
    
    To remove created associations you can just call the set method without a specific id:

    <pre><%- koala.render(".js", partial("associations3.ejs")) %></pre>
    
    You can also do it vice versa:
    
    <pre><%- koala.render(".js", partial("associations4.ejs")) %></pre>
    
    For hasOne its basically the same:

    <pre><%- koala.render(".js", partial("associations5.ejs")) %></pre>
    
    In order to specify many-to-many associations you can use the following syntax:

    <pre><%- koala.render(".js", partial("associations6.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.render(".js", partial("associations7.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.render(".js", partial("associations8.ejs")) %></pre>
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="finding"></a>
  <h2>Finding some objects</h2>
  <p>
    OK... you can define classes and associations. You can save them. You would probably like to get them from 
    the database again :-) Easy:
    
    <pre><%- koala.render(".js", partial("finding.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:
    
    <pre><%- koala.render(".js", partial("finding2.ejs")) %></pre>
  </p>
</div>

<div class="seperator"></div>

<div>
  <a name="projects"></a>
  <h2>Projects using Sequelize</h2>
  <p>
    You are using Sequelize? Let me know and get listed here! Just send me a private message on github :-)
  </p>
</div>