App

A website is divided in apps. Their goal is to provide structure to the code, and can be seen as modules. Each app contains its own controllers, views and models, and handles a specific set of routes.

// Create new app
var app1 = dry.app('app1');
// Start the app
app1.init();

Controller

A controller contains methods. Each method handles a specific route or event, returning a view instance if the result of the method's execution triggers UI changes. In this sense, Dry.js controllers are very similar to Rails or ASP.NET MVC.

var app1 = dry.app('app1');

// Handles a list of products
app1.controller('products', {
    // Triggered when navigating to /products/list
    'list': function() {
        return new dry.View('ProductList')
    }
});

Router

The router is responsible for directing page navigation actions to controllers. As the previous example hints, you do not need to specify routes anywhere. They are automatically generated from controller names and methods.

var app1 = dry.app('app1');

// Home page
app1.controller('default', {
    // Triggered on base url (root)
    'default': function() {
        return new dry.View('HomePage')
    }
});

// Handles a list of products
app1.controller('products', {
    // Triggered when navigating to /products/:id
    ':id': function(id) {
        return new dry.View('ProductDetails')
    }
    // Triggered when navigating to /products/list
    'list': function() {
        return new dry.View('ProductList')
    }
});

Model

In a typical fashion, models concentrate the responsibility of handling data structure, storage and server communication. They are injected into views through controller actions, and come with a convenient API for handling Ajax communication. Expanding on the previous example:

var app1 = dry.app('app1');

// Product model definition
app1.model('Product', {
    attributes: {
        id: 1 // default
    }
    getAll: 'GET https://someUrl/products'
    newProduct: 'POST https://someUrl/products/new',
    updateProduct: 'PUT https://someUrl/products/{id}',
    deleteProduct: 'DELETE https://someUrl/{id}'
});

// Handles a list of products
app1.controller('products', {
    'list': function() {
        // Creates a new model instance and calls the getAll method
        var allProducts = app1.model('Product');
        return allProducts
            .getAll() // Promises are built-in
            .then(function (data) {
                allProducts.set(data);
                // Pass the model to the view
                new dry.View('ProductList', {model: allProducts});
            });
    }
});

View

Views contain presentation logic. Each view contains a model instance which stores the data that is rendered on the template. They are also responsible for handling events, and do so by calling methods from the controller that created the view.

var app1 = dry.app('app1');

// Product model definition
app1.model('Product');

app1.view('ProductList', {
    events: {
        // When the button with class .btn-new' is pressed,
        // call the 'new' method in the controller
        'click .btn-new': 'new'
    }
});

// Handles a list of products
app1.controller('products', {
    'new': function() {
        // Creates a new model instance
        var product = app1.model('Product');
        // Pass the model to the view
        return app1.view('ProductList', {model: product});
    }
});

Template

Templates can be either strings or functinons which construct HTML code from the view data. Dry.js automatically finds template definitions in the dom looking for a script with a data-dry attribute, and then renders it to a DOM element with a data-dry attribute of the same value.

The convention here is very simple: by default, once a user navigates to a route (say www.someUrl.com/main/hello), then the main controller executes the hello method, which will create a new instance of the main/hello view.

Notice that the view instance is created on the fly, and since the only parameter specified when creating the view is its name, it will simply follow the default behavior for views. More specifically, it look for a script with a data-dry attribute equal to its name (the template) and render it into the first non-script DOM element with the same attribute value. Please read the Default behavior and best practices section for additional info.

var app1 = dry.app('app1');

// Home page
app1.controller('main', {
    'hello': function() {
        return new dry.View('main/hello');
    }
});

<!-- Template -->
<script data-dry="main/hello" type="text/template">
    <% for(var i=0; i<10; i++) { %>
        Lorem ipsum
    <% } %>
</script>

<!-- Template will be rendered here -->
<div data-dry="main/hello"></div>

Filters

Filters are a simple and semantic way to reuse code inside your application (again, DRY principle). They check if a condition is fulfilled and execute a given action if it is. They can seve as annotations and make controller logic much easier to read.

Note: filters are not required, so you can choose not to use them if you find them irrelevant or confusing.

var app1 = dry.app('app1');

function isLoggedIn() {
    // some logic...
}

function redirectToHome() {
    dry.navigate("/home");
}

app1.filter('IsLoggedIn', isLoggedIn, redirectToHome);

// Home page
app1.controller('main', {
    'hello': function() {
          app1.filter("IsLogedIn");

          // Continue controller logic...
    }
});

Type Checking

// Check if the given parameter is an array
dry.isArray([1,2,3]) => true

// Check if the given parameter is an object
dry.isObject({a:1, b:2}) => true

// Check if the given parameter is strictly an object
dry.isStrictlyObject({'a':1, 'b':2}) => true
dry.isStrictlyObject([1,2,3]) => false

// Check if the given parameter is boolean
dry.isBoolean(true) => true

// Check if the given parameter is a string
dry.isString('Hi there') => true

// Check if the given parameter is a function
dry.isFunction(function(){}) => true

// Check if the given parameter is undefined
dry.isUndefined(undefined) => true

// Check if the given parameter is numeric
dry.isNumeric(1) => true

Object management

// Returns an array with the property names for the given object
dry.keys({'a':1, 'b': 2, 'c': 3}) => ['a', 'b', 'c'];

// Concise and efficient forEach implementation
var arr = [10, 20, 30];
dry.each(arr, function(number) {
    console.log(number)
});
// Logs 10 20 30

var context = {
    valueMessage: 'The value is',
    indexMessage: 'at index'
};
dry.each(arr, function(num, index) {
    console.log(this.valueMessage, num, this.indexMessage, index);
}, context);
// Logs:
// The number is 10 at index 0
// The number is 20 at index 1
// The number is 30 at index 2

Ajax communication

// jQuery-like ajax implementation
dry.ajax({
    type: 'GET',
    url: 'https://api.github.com/users/diegocard',
    timeout: 5000,
    success: function(data){
        console.log(data);
    },
    error: function() {
        console.log('error');
    }
});

// There are also default values for most parameters
function ajaxCall(someUrl) {
    return dry.ajax({
        url: someUrl
    }).then(function(data){
        console.log(data);
    }) // Returns a promise
}

DOM Management

// jQuery-like selectors
dry.$('body');

// jQuery-like html function
dry.$('body').html('<h1>Hi</h1>');

// jQuery-like event handlers
var clickHandler = function() {
    console.log('clicked');
}

// Activate click event
dry.$('body').on('click', clickHandler);

// Trigger the click event
dry.$('body').trigger('click', /* You can pass data here */);

// Deactivate click event
dry.$('body').off('click', clickHandler);

A+ Promises

function randomOutcome(number) {
    var deferred = dry.deferred();
    setTimeout(function(){
        if (Math.random() > number) {
            deferred.resolve('Bigger');
        } else {
            deferred.reject('Smaller');
        }
    }, 1000);
    return deferred.promise;
}

randomOutcome(0.5)
.then(function(outcome){
    console.log(outcome, 'than 0.5');
})
.error(function(outcome){
    console.log(outcome, 'than 0.5');
})

And other shortcuts

• dry.getJSON(url, [success], [error]);
• dry.get(url, [success], [error]);
• dry.post(url, data, [success], [error])
• dry.put(url, data, [success], [error])
• dry.delete(url, data, [success], [error])
• dry.jsonp(url, callback)