Talent JS文档 v0.2

---

ItemView

简述

用于简单地渲染一个模板。
其render方法会将模板与数据绑定，并将结果渲染至$el中。

使用示例

MyView=Talent.Itemview.extend({
    template: jst['home/index-page']
});

属性

ui

一组hash表，获取view对应模板内的dom元素。
如下例所示，render前，this.ui.checkbox为字符串；render后，为jquery对象。

ui:{
    checkbox:"input[type=checkbox]"
},
,events:function(){
    var events = {};
    events['click ' + this.ui.checkbox] = 'clickHandler';
    return events;
}
onRender: function() {
    if (this.model.get('selected')) {
        this.ui.checkbox.addClass('checked');
    }
}

modelEvents

对model中发生的事件绑定相应的事件监听函数。

modelEvents: {
    "change":"modelChanged"
}

collectionEvents

对collection中发生的事件绑定相应的事件监听函数。

collectionEvents: {
    "add":"modelAdded"
}

方法

serializeData

该方法用于处理向模板中传入的数据，它的返回值必须为json对象。
ItemView传入的model或collection数据不适合直接渲染时，可用该方法。

serializeData: function(){
    return {
        "some attribute": "some value"
    }
}

方法回调

onRender

该方法在render后执行。你可以向其中加入你希望在view render之后执行的代码。

CompositeView

简述

包含一个模板和一个可迭代区域。可迭代区域中的每个条目由ItemView负责渲染。

使用示例

var MyItemView = Talent.ItemView.extend({
    template : Talent._.template('<li><%=text%></li>')
});
Talent.CompositeView.extend({
    template : jst['common/todo-composite'],
    itemViewContainer : 'ul',
    itemView: MyItemView
});

属性

itemView

用于指定渲染每个迭代条目的视图类，其必须是ItemView的子类；必选参数；

itemViewContainer

用于指定迭代区域。该方法指定一个DOM节点，用来包含所有迭代条目。必选参数。

itemViewOptions

从compositeView中传入到itemView中的参数。

var MyItemView = Talent.ItemView.extend({
    initialize: function(options){
        console.log(options.foo); // => "bar"
    }
});
Talent.CompositeView.extend({
    template : jst['common/todo-composite'],
    itemViewContainer : 'ul',
    itemView: MyItemView,
    itemViewOptions : {
        foo : "bar"
    }
});

当itemViewOptions中的值需要在运行时通过计算得出时，它也可以被定义为一个函数，必须返回一个对象。

Talent.CompositeView.extend({
    itemViewOptions: functioin(model, index){
        // 计算部分
        return {
            foo: "bar",
            itemIndex: index
        }
    }
});

emptyView

collection为空时在compositeView内渲染的视图类。

children

获取compositeView中所有的itemView

方法

buildItemView

自定义itemView的实例化过程。

buildItemView: function(item, ItemViewType, itemViewOptions){
    // 为ItemView构建最终的参数列表
    var options = _.extend({model: item}, itemViewOptions);
    // 实例化
    var view = new ItemViewType(options);
    return view;
}

appendHtml

自定义itemView实例插入到dom结点的过程。
默认情况下，compositeView把每个itemView添加到缓存元素中，在最后通过jQuery的.append方法把所有itemView添加到compositeView的el中。

Talent.CompositeView.extend({
        //第一个参数是compositeView实例，
        //第二个参数是当前itemView实例，
        //第三个参数itemView对应的model在collection中的序号。
    appendHtml: function(compositeView, itemView, index){
        if (compositeView.isBuffering) {
            //在事件重置和初始化渲染时缓存，减少向document插入元素的次数
            compositeView.elBuffer.appendChild(itemView.el);
        }
        else {
                        //如果compositeView已经被渲染，
                        //直接把新的itemView添加到compositeView中
            cmopositeView.$el.append(itemView.el);
        }
    }
});

close

close方法执行以下操作 ：

• 解除所有listenTo事件
• 解除所有自定义view事件
• 解除所有DOM事件
• 解除所有已渲染的item views
• 从DOM中移除this.el节点
• 如果设置了onClose事件回调函数，调用onClose函数

事件回调

onRender

view渲染完成后，对view对应的dom结构进行其它操作。

onClose

在view close后执行。

onBeforeItemAdded

item实例即将被添加到compositeView之前执行。

onBeforeItemAdded: function(itemView){
    //操作代码
}

onAfterItemAdded

item实例被添加到compositeView之后执行。

onAfterItemAdded: function(itemView){
    //操作代码
}

onItemRemoved

当item实例从compositeView中移除时执行。

onItemRemoved: function(itemView){
    // 操作代码
}

事件

以下事件函数在相应事件发生时被调用。

render

closed

before:item:added

after:item:added

item:removed

MyView = Talent.CompositeView.extend({...});
var myView = new MyView();
myView.on("render", function(){
    alert("the collection view was rendered!");
});
myView.on("colsed", function(){
    alert("the collection view was closed!");
});

var MyCV = Talent.CollectionView.extend({
    // ...
    onBeforeItemAdded: function(){
        // ...
    },
    onAfterItemAdded: function(){
        // ...
    }
});
var cv = new MyCV({...});
cv.on("before:item:added", function(viewInstance){
    // ...
});
cv.on("after:item:added", function(viewInstance){
    // ...
});
cv.on("item:removed", function(viewInstance){
    // ...
});

Layout

简述

具有若干可局部刷新的区域(region)

使用示例

MyLayout = Talent.Layout.extend({
  template: "#my-layout-template",
  regions: {
    menu: "#menu-bar",
    content: "#main-content"
  } 
});
var myLayout = new MyLayout();
myLayout.render();
//myMenu在这里可以是ItemView或CompositeView的实例
myLayout.menu.show(myMenu);

属性

regions

定义Layout中的Region。通过函数定义，该函数返回一个定义Region的对象。

regions: function(options){
    return {
        fooRegion: "#foo-element"
    };
}

方法

show

渲染view并将它添加到el元素中。

addRegion

向Layout中添加Region，一次只能添加一个。

var layout = new MyLayout();
// ...
layout.addRegion("foo", "#foo");

addRegions

向Layout中添加Region，一次可以添加多个。

var layout = new MyLayout();
// ...
layout.addRegions({
    foo: "#foo",
    bar: "#bar"
});

removeRegion

移除Layout中的Region。

var layout = new MyLayout();
// ...
layout.removeRegion("foo");

自定义Region Type

用于将默认的Region类替换为你自定义的Region类。

MyLayout = Talent.Layout.extend({
    regionType: SomeCustomRegion
});

也可以分别向每个region设置不同的Region类。

AppLayout = Talent.Layout.extend({
    template: "#layout-template",
    regionType: SomeDefaultCustomRegion,
    regions: {
        menu: {
            selector: "#menu",
            regionType: CustomRegionTypeReference
        },
        content: {
            selector: "#content",
            regionType: CustomRegionType2Reference
        }
    }
});

Region

简述

需要经常变动内部视图的区域。其最重要的特性为在改变内部视图后旧视图会从DOM中移除。

使用示例

AppLayout = Talent.Layout.extend({
    template: "#layout-template",
    regions: {
        menu: "#menu",
        content: "#content"
    }
});
var layout = new AppLayout();
layout.render();
layout.menu.show(new MenuView());
layout.content.show(new MainContentView());

属性

currentView

设置绑定到Region中的view。该view不会渲染或显示。

var myView = new MyView({
    el: $("#existing-view-stuff")
});
var region = new Talent.Region({
    el: "#content",
    currentView: myView
});

方法

show

渲染并将view添加到DOM树中。每次调用show方法时会自动调用close关闭旧view。可以通过{preventClose: true}参数阻止close行为。

// 显示myView
var myView = new MyView();
MyApp.mainRegion.show(myView);
// anotherView替换掉myView。自动调用close方法
var anotherView = new AnotherView();
MyApp.mainRegion.show(anotherView);
// anotherView2替换anotherView。阻止调用close方法
var anotherView2 = new AnotherView();
MyApp.mainRegion.show(anotherView2, { preventClose: true });

reset

自动关闭所有显示的view并删除缓存的el元素。region下一次显示view时，el重新从DOM中获取。

open

改变视图添加到region中的过程。
默认的open方法为：

Talent.Region.prototype.open = function(view){
    this.$el.empty().append(view.el);
}

重写open方法添加其它效果

Talent.Region.prototype.open = function(view){
    this.$el.hide();
    this.$el.html(view.el);
    this.$el.slideDown("fast");
}

attachView

向Region中添加view，添加的view不会渲染或显示。

MyApp.addRegions({
    someRegion: "#content"
});
var myView = new MyView({
    el: $("#existing-view-stuff")
});
MyApp.someRegion.attachView(myView);

事件

beforeShow

当view已经渲染完成，但是尚未添加到DOM中时调用。

show

view渲染完成并添加到DOM中后调用。

close

当view被关闭之后调用。

MyApp.mainRegion.on("before:show", function(view){
  // manipulate the `view` or do something extra
  // with the region via `this`
});
MyApp.mainRegion.on("show", function(view){
    // manipulate the `view` or do something extra
    // with the region via `this`
});
MyApp.mainRegion.on("close", function(view){
    // manipulate the `view` or do something extra
    // with the region via `this`
});
MyRegion = Backbone.Marionette.Region.extend({
    // ...
    onBeforeShow: function(view) {
        // the `view` has not been shown yet
    },
    onShow: function(view){
        // the `view` has been shown
    }
});
MyView = Talent.ItemView.extend({
    onBeforeShow: function() {
        // called before the view has been shown
    },
    onShow: function(){
        // called when the view has been shown
    }
});

实例化自定义Region

当我们想在应用运行之后向其中添加region时，就要按照上文中的方法扩展Region类，并在应用中实例化，如下所示：

var SomeRegion = Talent.Region.extend({
    el: "#some-div",
    initialize: function(options){
      // your init code, here
    }
});
MyApp.someRegion = new SomeRegion();
MyApp.someRegion.show(someView);

注意region必须要有一个元素与自身绑定，如果在添加region实例到应用或Layout中时没有指定选择器的话，在定义时也必须声明el属性。

添加自定义Region Types

通过addRegions将自定义Region Type添加到应用中。

var FooterRegion = Talent.Region.extend({
    el: "#footer"
});
MyApp.addRegions({
    footerRegion: FooterRegion
});

也可以在添加时声明一个选择器。

var FooterRegion = Talent.Region.extend({
    el: "#footer"
});
MyApp.addRegions({
    footerRegion: {
        selector: "#footer",
        regionType: FooterRegion
    }
});