API

wtfil edited this page Jun 20, 2013 · 29 revisions
Clone this wiki locally

i-router

define()

Define handler or list of handlers

@param {String|Array} [reqMethod] request method: 'get', 'post', 'get,post', 'delete' etc. or list of arguments To assign more than one method list with comma
@param {String|RegExp} reqPath request path matcher
@param {String} blockName block name

All bracket in reqPath will creates matcher.

The matches can be prepared with BEM.blocks['i-router'].get('matches') or first arguments in init method of page

examples:

BEM.blocks['i-router'].define('GET,POST', /\/db\/(save|get)/, 'i-page-db');
BEM.decl({name: 'i-page-db', baseBlock: 'i-page'}, null, {
    init: function (matches) {
        console.log(matches === BEM.blocks['i-router'].get('matches')) // true; and will be equal ['/db/save', 'save'] for url "/db/save"
    }  
}); 
BEM.blocks['i-router'].define('/', 'i-page-home');
BEM.blocks['i-router'].define(/\/?/, 'i-page-home');
BEM.blocks['i-router'].define('POST', 'save', 'i-page-save');
BEM.blocks['i-router'].define('GET,POST', /\/db\/(save|get)/, 'i-page-db');
BEM.blocks['i-router'].define([
    ['/', 'i-page-home'],
    ['POST', '/save', 'i-page-save']
]);

setPath()

Changing path (window.location.href on client and redirect on server)

@param {String} path

get()

Getting request variables

@see http://nodejs.org/api/http.html
@see https://github.com/jed/cookies

@param {String} [name] (req, res, cookies, params, matches)
@return {http.ClientRequest|http.ServerResponse|Cookie|Object|Array} depends of argument 

unescapeHTML()

Unescaping the string. Useful when You get url of something else in GET params

@param {String}
@return {String}

i-page

Base blocks for build pages.

You should use this block for creating new pages through inheritance, not calling its methods:

// creating page with name "i-page-main"
BEM.decl({block: 'i-page-main', baseBlock: 'i-page'}, null, {
    // redefined and new methods
});

There are few methods implements in this block. All of them may be redefined for customisation

init()

Called when route on page was changed. Default behavior of this function if blank page

@param {Array} matchers matched params from path
@return {Vow.promise}

out()

Creating content of page

@param {String|Object|Array} json
@return {Vow.promise}

exmaple:

BEM.decl({block: 'i-page-home', baseBlock: 'i-page'}, null, {                            

    init: function (matchers) {
        // you can pass bemjson like here:
        // return this.out({block: 'b-hello-world', content: 'hello world'});                                                      
        return this.out('hello world');                                          
    }                                                                                    

});

update()

Called when page params changed but route same to previous. This action can happen only on client side, so you must define this method in .js file (not .common.js)

@param {Array} matchers matched params from path
@return {Vow.promise}

setTitle()

Set html title for page

@param {String} title page title
@return {i-content}

setDescription()

Set html description meta tag for page

@param {String} text description content
@return {i-content}

setMeta()

Set content for meta tag

@param {String} name name of a meta tag
@param {String} content content for given meta tag
@return {i-content}

i-response

Manages error pages (404, 50x), http redirect and responses

send()

Making response for current request

@param {Number} status
@param {String} body
@param {String} [contentType=text/plain]

json()

Response with json

@param {Object} json

missing()

Showing 404 status

error()

Showing error status

@param {Error} err
@config {Number} [status=503] of error
@config {String} [message] depends of status code 

i-state

Base block for working with execution context

set()

Saving data to state

@param {String} path
@param {Mixed} data

get()

Geting data from state

@param {String} path separated with dots
@return {Mixed}

examples:

BEM.blocks['i-state'].set('params', {foo: 'bar'});
BEM.blocks['i-state'].get('params'); // {foo: 'bar'}
BEM.blocks['i-state'].get('params.foo'); // 'bar'

initNs()

Create state accessors for given namespase

@param {String} namespace
@return {Object} state with same interface for i-state
@return {Function} state.get
@return {Function} state.set

This method is useful for creating of independent variable namespace

example:

//Creating block with methods 'get' and 'set'
BEM.decl('i-router', null, BEM.blocks['i-state'].initNs('i-router')); 

// Accompany i-router block
BEM.decl('i-router', null, {
    someAct: function () {
        this.set('params', {foo: 'bar'});
        this.get('params.bar'); // 'bar'
    }
});

i-ajax-proxy

i-api-request

get() make GET request

@param {String} path or resource
@param {Object} [options]
@param {Object} [options.params] GET or POST params
@param {String} [option.requestSource] (ajax) to get string instead of JSON
@return {Vow.promise}

exmaples:

BEM.blocks['i-api-requst']
    .get('http://nodejs.org/api/assert.json')
    .then(function (result) {
        console.log(result); // will see http://nodejs.org/api/assert.json as json
    });

BEM.blocks['i-api-requst']
    .get('http://nodejs.org/api/assert.json', {requestSource: 'ajax'})
    .then(function (result) {
        console.log(result); // will see http://nodejs.org/api/assert.json as string
    });

BEM.blocks['i-api-requst']
    .get('http://nodejs.org/api/assert.json', {params: {foo: 'bar'}})
    .then(function (result) {
        console.log(result); // will see http://nodejs.org/api/assert.json?foo=bar (same to http://nodejs.org/api/assert.json)
    });

post() same interface to .get() but POST request will be occur

delete() same interface to .get() but DELETE request will be occur

i-bem

i-command

Allow to get command line arguments

get()

Getting argument by name. Single or double defies does not meter.

@param {String} name
@return {String|Boolean}

examples:

node pages/index/index.server.js --socket 3000 -d --t --workers 10
BEM.blocks['i-command'].get('socket') // 3000
BEM.blocks['i-command'].get('d') // true
BEM.blocks['i-command'].get('t') // true
BEM.blocks['i-command'].get('workers') // 10

i-content

Base block to create/output content

html()

Process given bemjson to html

@param {String|Object|Array} bemJson
@param {Boolean} [isSync] if true, method will perform synchronous BEM.JSON.build and return a html string
@return {Vow.promise|String} depends of isSync value returns promise of string

i-promise

@see https://github.com/dfilatov/jspromise

i-ycssjs

This block is used for proxying static files thought nodejs and for creating css/js files on the fly while developing. Your should not call any method of this block to use it. You just need to add follow line to pages/index/index.bemdecl.js

{block: 'i-ycssjs'}

i-block-example

Block description

methodName()

Method description

@param {Object} test
@return {Object}