index.html

---
layout: default
title: Viking.js
---
<div class="intro">
    Viking.js is an open-source web framework for JavaScript.
    <br />
    Built on Backbone.js and inspired by Ruby on Rails; it makes it easier to
    write client side JavaScript applications.
</div>

<div class="downloads">
    <a class="btn outline" href="https://github.com/malomalo/viking/">Github</a>
    <a class="btn green" href="{% asset_url malomalo/viking viking.js %}">{% icon download %}Download {% version malomalo/viking %}</a>
</div>

<div class="docs">
    <div class="docs-container">
        <h2>Getting Started</h2>
        
        <p class="center">
            Viking.js makes it easy to work with Rails and REST APIs. It attempts
            to follow the philosophies of
            <a href="http://rubyonrails.org/">Ruby On Rails</a>.
        </p>
        
        
        <h3>Installation</h3>
        <div class="section">
            <div class="notes">
                <p>
                    The following libraries are required for Viking.js
                </p>
        
                <ul class="links">
                    <li><a href="http://jquery.com/">{% icon link %} jQuery</a></li>
                    <li><a href="http://github.com/samsonjs/strftime">{% icon link %}strftime</a></li>
                    <li><a href="http://underscorejs.org/">{% icon link %}Underscore.js</a></li>
                    <li><a href="https://github.com/jeremyruppel/underscore.inflection">{% icon link %}Underscore.Inflection</a></li>
                    <li><a href="http://backbonejs.org/">{% icon link %}Backbone.js</a></li>
                </ul>
            </div>
            <div class="code">
{% highlight html %}
<script type="text/javascript" src="/jquery.js"></script>
<script type="text/javascript" src="/strftime.js"></script>
<script type="text/javascript" src="/underscore.js"></script>
<script type="text/javascript" src="/underscore.inflection.js"></script>
<script type="text/javascript" src="/backbone.js"></script>
<script type="text/javascript" src="/viking.js"></script>
{% endhighlight %}
            </div>
        </div>
        

        <h3>Models</h3>
        <div class="section">
            <div class="notes">
                <p>
                    <code>Viking.Model</code> extends
                    <a href="http://backbonejs.org/#Model">Backbone.Model</a> adding
                    naming, associations, data type coerions, selection, and modifies
                    sync to work with <a href="http://rubyonrails.org/">Ruby on Rails</a>
                    out of the box.
                </p>
                <p>&nbsp;</p>
                <p>
                    Your are not required to pass a name. In this example the name
                    <code>"ship"</code> allows Viking automatically read and build the associations
                    and generate any urls.
                </p>
                <p>
                    The <code>schema</code> defines the types to serialize to and from JSON as well as
                    converting attributes to the appropriate type when they are set by the user.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
Ship = Viking.Model.extend('ship', {
    
    schema: {
        name: {type: 'string'},
        size: {type: 'number'},
        roles: {type: 'string', array: true},
        attributes: {type: 'json'},
        last_serviced_at: {type: 'date'},
        operational: {type: 'boolean', "default": false}
    },
    
    belongsTo: ['fleet'],
    
    hasMany: [['sailors', {model: 'Human'}]],
    
    initialize: function () {
        // ...
    }
});
{% endhighlight %}
            </div>
        </div>

        <h4>Defaults</h4>
        <div class="section">
            <div class="notes">
                <p>
                    Instead of setting <code>defaults</code> like in 
                    <a href="http://backbonejs.org/#Model-defaults">Backbone.js</a>
                    the default values for attributes are defined in the 
                    <code>schema</code>.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
Ship = Viking.Model.extend('ship', {
    schema: {
        operational: { type: 'boolean', "default": false },
        created_at:  { type: 'date', "default": function () { 
            return new Date();
        } }
    }
});
{% endhighlight %}
            </div>
        </div>
        
        <h4>Associations</h4>
        <div class="section">
            <div class="notes">
                <p>
                    <code>belongsTo</code> takes and array of names for the
					associations. By default a <code>get('fleet')</code> in the
					example would return <code>undefined</code> on a new instance
					of the model.
                </p>
                <p>
                    You can set the fleet with the normal <code>set</code> function
					or through the inital attributes. Both accept either an model
					or the attributes used to construct the model.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
Ship = Viking.Model.extend('ship', {
    belongsTo: ['fleet']
});
{% endhighlight %}
            </div>
        </div>
        <div class="section">
            <div class="notes">
                <p>
                    If the model name is different than the association name you can
                    pass the model name as an option.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
belongsTo: ['village'];
// or
belongsTo: [['owner', {model: 'Village'}]];
{% endhighlight %}
            </div>
        </div>
        <div class="section">
            <div class="notes">
                <p>
                    Viking also supports polymorphic relations in a similar
					fashion to Rails. If you specify <code>polymorphic: true</code>
					in the options of a <code>belongsTo</code> relation.
                </p>
				<p>
					In the example when setting or initalizing the model, if 
					<code>subject</code> is a normal Javascript Object Viking
					will look for <code>subject_type</code> in the attributes to
					know what type of model <code>subject</code> needs to
					instantiated as.
				</p>
				<p>
					When setting or initalizing the model, if <code>subject</code>
					is a Viking.Model then <code>subject_type</code> will be set
					to the modelName of the value.
				</p>
            </div>
            <div class="code">
{% highlight javascript %}
Model = Viking.Model.except({
	belongsTo: [['subject', {polymorphic: true}]];
});

var model = new Model({
	subject_type: 'ship',
	subject: {callsign: 'TREX'}
});
model.get('subject').modelName instanceof Ship // => true

model.set('subject', new Car())
model.get('subject_type') // => 'car'
{% endhighlight %}
            </div>
        </div>
        
        <div class="section">
            <div class="notes">
                <p>
                    <code>hasMany</code> relationships are similar except they
                    default to an empty collection. By default a
                    <code>get('ships')</code> in the example above would return
                    a <code>ShipCollection</code> on a new instance of the model.
                </p>
                <p>
                  // TODO: talk about setting a collection
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
Fleet = Viking.Model.extend('fleet', {
    hasMany: ['ships']
});
{% endhighlight %}
            </div>
        </div>
        <div class="section">
            <div class="notes">
                <p>
                    If the collection or model name is different than the
                    association name you can pass the model name as an option.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
hasMany: ['ships'];
// => uses `ShipCollection`

hasMany: [['ships', {model: 'Ship'}]];
// => uses `ShipCollection`

hasMany: [['ships', {collection: 'Ships'}]];
// => uses `Ships`
{% endhighlight %}
            </div>
        </div>
        
        <h4>Single Table Inheritance</h4>
        <div class="section">
            <div class="notes">
                <p>
                    <code>Viking.Model</code> supports Single table inheritance
                    in a similar fashion to <a href="http://api.rubyonrails.org/classes/ActiveRecord/Base.html#label-Single+table+inheritance">Rails' STI</a>.
                </p>
                <p>&nbsp;</p>
                <p>
                    <code>Viking.Model</code> allows inheritance by storing the
                    name of the model in the <code>type</code> attribute (can be
                    changed by setting <code>inheritanceAttribute</code> on the
                    model).
                </p>
                <p>
                    In the example when you do
                    <code>new Destroyer({name: "37signals"})</code>, the object
                    will have the <code>type</code> attribute set to
                    <code>"destroyer"</code>.
                </p>
                <p>
                    // TODO: mention about Ship.all returning all STI models and
                    // Destroyer.all returning Destroyers and GuidedMissileDestroyers
                </p>
                <p>
                    // TODO: mention about changing the `type` and perhaps
                    // implement the becomes method internally
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
Ship = Viking.Model.extend('ship', {
    hasMany: [['sailors', {model: 'Human'}]],
});

Destroyer = Ship.extend('destroyer', {
    hasMany: ['guns', 'torpedos'],
});

GuidedMissileDestroyer = Destroyer.extend('guided_missile_destroyer', {
    hasMany: ['missles'],
});
{% endhighlight %}
            </div>
        </div>


        <h3>Collections</h3>
        <div class="section">
            <div class="notes">
                <p>
                    <code>Viking.Collection</code> extends
                    <a href="http://backbonejs.org/#Collection">Backbone.Collection</a>,
                    adding predicates, selections, and modifies fetch to cancel any
                    current request if a new fetch is triggered.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
FleetCollection = Viking.Collection.extend({
    model: Ship
});
{% endhighlight %}
            </div>
        </div>
        <div class="section">
            <div class="notes">
                <p>
                    You can attach a predicate to a collection.
                </p>
                <p>
                    If a predicate is set it's paramaters will be passed under the
                    <code>where</code> key when querying the server. When the predicate changes
                    the collection is re-fetched.
                </p>
                <p>
                    To remove a predeicate call <code>#setPredicate</code> with a falsey value.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
var fleet = new FleetCollection({predicate: {}});

// or
var predicate = new Viking.Predicate();
var fleet = new FleetCollection({predicate: predicate});

// triggers a fetch and includes {type: 'battleship'} in the query params
predicate.set('type', 'battleship');
{% endhighlight %}
            </div>
        </div>
        <div class="section">
            <div class="notes">
                <h4>Paginated Collections</h4>
                <p>
                    In addition if you want paginate your results you can also use a
                    <code>Viking.PaginatedCollection</code>
                </p>
                <p>
                    A <code>Viking.PaginatedCollection</code> expects the response from the server
                    to be similar to the example.
                </p>
                <p>
                    The paginated collection will have a <code>Viking.Cursor</code>
                    available at <code>collection.curosr</code>. Any changes to the
                    attributes <code>page</code>, <code>offset</code>, or
                    <code>per_page</code> will trigger a fetch on the collection.
                </p>
        
                <p>
                    The cursor has several helper functions to allow you to navigate.
                    The functions are <code>reset</code>, <code>incrementPage</code>,
                    <code>decrementPage</code>, and <code>goToPage</code>.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
FleetCollection = Viking.PaginatedCollection.extend({
    model: Ship
});
{% endhighlight %}
{% highlight javascript %}
{
    page: 1,
    offset: 0,
    per_page: 25,
    total_pages: 479,
    total: 11974,
    count: 25,
    ships: [
        // ...
    ]
}
{% endhighlight %}
            </div>
        </div>

        <h3>Controllers</h3>
        <div class="section">
            <div class="notes">
                <p>routers...</p>
            </div>
            <div class="code">
{% highlight html %}
//TODO
{% endhighlight %}
            </div>
        </div>


        <h3>Templates</h3>
        <div class="section">
            <div class="notes">
                <p>
                    Templates are functions stored under the
                    <code>Viking.View.templates</code> object. The templates
                    function accepts bindings that can be used when compiling
                    the template.
                </p>
                <p>
                    Templates can be rendered via
                    <code>Viking.View.Helpers.render</code>.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
Viking.View.templates['my/template'] = function (bindings) {
    return 'My template';
};

Viking.View.Helpers.render('my/template'); // => 'My template'
{% endhighlight %}
            </div>
        </div>


        <h3>Views</h3>
        <div class="section">
            <div class="notes">
                <p>
                    <code>Viking.View</code> provides additional functionality
                    ontop of <code>Backbone.View</code>. Helper functions include
                    <code>Viking.View#subView</code>,
                    <code>Viking.View#renderTemplate</code> and inheritance of
                    View <code>events</code>.
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
WorldView = Viking.View.extend({
    events: {
        'click .region': 'zoomIn'
    },
    
    zoomIn: function () {
        // ...
    }
});

FleetView = WorldView.extend({
    
    // FleetView inherits from WorldView which is a
    // Viking.View so it will still have the
    // 'click .region' event, unless it is overridden
    events: {
        'click .ship': 'showShipInfo'
    },
    
    showShipInfo: function () {
        // ...
    }
});
{% endhighlight %}
            </div>
        </div>
        
        <div class="section">
            <div class="notes">
                <p>
                    <code>Viking.View#renderTemplate</code> is an alias for
                    <code>Viking.View.Helpers.render(template, locals)</code>.
                    <code>Viking.View.Helpers.render(template, locals)</code>
                    allows you pass locals but also includes all the
                    <code>Viking.View.Helpers</code> for use in your template
                </p>
            </div>
            <div class="code">
{% highlight javascript %}
Viking.View.templates['fleet/overview'] = function () {
    
    return formTag({action: '/inspect'}, function() {
        return labelTag("Ship " + ship.name) + submitTag('Inspect');
    });
    
};

FleetView = Viking.View.extend({
    
    render: function () {
        this.$el.html(this.renderTemplate('fleet/overview'))
        return this;
    }
    
});
{% endhighlight %}
            </div>
        </div>


        <h3>Form</h3>
        <div class="section">
            <div class="notes">
                <p>routers...</p>
            </div>
            <div class="code">
{% highlight html %}
[[ formFor(listing, function(f) { ]]
    <div class="section">
        [[= f.label('address') ]]
        [[= f.textField('address')]]

        [[= f.label('space_type') ]]
        [[= f.select('space_type', ["lease", "sublease"]) ]]
    </div>
[[ }) ]]
{% endhighlight %}
            </div>
        </div>


        <h3>Loading data from a server</h3>
        <div class="section">
            <div class="notes">
                <p>coming...</p>
            </div>
            <div class="code">
{% highlight html %}
//TODO
{% endhighlight %}
            </div>
        </div>

        <h3>Errors</h3>
        <div class="section">
            <div class="notes">
                <p>coming...</p>
            </div>
            <div class="code">
{% highlight html %}
//TODO
{% endhighlight %}
            </div>
        </div>

        <h3>Support</h3>
        <div class="section">
            <div class="notes">
                <p>coming...</p>
            </div>
            <div class="code">
{% highlight html %}
//TODO
{% endhighlight %}
            </div>
        </div>
    </div>
</div>


<div class="footer">
    <div class="footer-container">
        <h2>Contributors</h2>
        <p>
            Viking.js is open source tool created for use at <a href="http://42floors.com">42Floors</a>.
        </p>
        <p>
            Please report bugs on the <a href="https://github.com/malomalo/viking/issues">GitHub issues page</a>.
        </p>
        {% contributors malomalo/viking %}
        <h2>Licensing</h2>
        <p>
            Viking.js is released under the
            <a href="http://en.wikipedia.org/wiki/MIT_License">MIT License</a>
        </p>
    </div>
</div>