Alpaca-Spa-2.0 前端单页面框架

Alpaca-Spa-2.0 使用帮助

简介

Alpaca-spa-2.0.js 简介

Alpaca-spa.js是一款轻量的前端JS框架,提供前端路由功能,前端视图渲染功能,前端套页面功能。目的是用来提高web项目的开发效率,前后端分离开发,同时使前端代码结构更加整洁。

Alpaca-spa.js 区别于其他框架的主要特点是轻巧灵活,学习成本低。框架没有复杂的概念与特性,几乎都是最基本的JavaScript语法,也就是说读者只要有JavaScript语言基础,就能很快学会使用 Alpaca-spa.js框架。

主页

Alpaca-Spa : http://www.tkc8.com

代码

码云: https://git.oschina.net/cc-sponge/alpaca-spa-2.0

GItiHub: https://github.com/big-sponge/Alpaca-Spa-2.0

入门示例

1. 引用Alpaca-spa-2.0.js

Alpaca-spa-2.0.js 目前依赖于  jquery.js。使用Alpaca-spa-2.0.js 需要引用
1). jquery.js
    下载地址(或者直接在代码中引用):http://spa.tkc8.com/common/js/jquery-2.1.4.min.js 
2). Alpaca-spa-2.0.js 
    下载地址(或者直接在代码中引用):http://spa.tkc8.com/common/js/alpaca-spa-2.0.js

2. 示例: Hello Alpaca

新建文件hello.html。在文件中编辑以下内容代码,用浏览器打开观察结果。




    Alpaca-Spa-2.0 JS
    

    
    

    



hello {{=it.text}} !



结果如下

hello Alpaca !

示例中的Alpaca.Tpl( )方法,传递了一个对象作为参数,对像中有两个属性,data表示要传递的数据(对象格式),place表示要渲染的位置。

通过上面的示例可以发现 页面body元素中的 {{=it.text}}被替换成为了 参数data中的text字段,也就是“Alpaca”,从而达到了渲染数据的效果。

, 模板中的 it 是固定关键字,代表传递过来的数据对象。关于Alpaca.Tpl( )方法的详细用法,后续章节会做详细介绍。

3. 示例:使用路由

新建文件router.html。在文件中编辑以下内容代码,用浏览器打开观察结果。




    Alpaca-Spa-2.0 JS
    

    
    

    






结果如下,表示Alpaca路由运行成功

Welcome use Alpaca-spa 2.0 !

新建文件router-index.html。在文件中编辑以下内容代码。




    Alpaca-Spa-2.0 JS
    

    
    

    

    



{{=it.text }} Alpaca.



在浏览器中输入http://127.0.0.1/examples/router-index.html#/index/index/index

结果弹出提示框:

Hello Router

在浏览器中输入http://127.0.0.1/examples/router-index.html#/index/index/index2

页面中显示:

Hello Alpaca.

通过上面两个例子,可以发现,Url中 :

#/index/index/index 映射到 Alpaca.IndexModule.IndexController.indexAction()方法

#/index/index/index2 映射到 Alpaca.IndexModule.IndexController.index2Action()方法

这就是Alpace路由的用途,将Url中hash部分映射到一个js方法。

关于路由的详细用法以及Alpaca.run()方法,后面章节会详细介绍。

模板语法

1. 语法

模板语法的作用是将JavaScript中的数据变量渲染到页面中。

Alpaca-spa.js 引用dot.js作为模板引擎,并且支持两种模板语法格式,分别是 alpaca 格式, dot.js 默认格式。常用的语法格式如下所示:

  • Alpaca 格式 :

    • 在标签内可以使用任意的JS语法
    • 输出变量
    • xxx 条件判断
    • xxx for循环
    • val) ?> xxx foreach循环
  • dot.js 格式 :

    • {{ }} 在标签内可以使用JS表达式和dot.js语法
    • {{=value }} 当前位置输出变量的值
    • {{ if(){ }} xxx {{ } }} 条件判断
    • {{ for(){ }} xxx {{ } }} for循环

学习使用Alpaca-spa.js模板引擎 ,开发人员只需要掌握三种基本的语法格式即可: 输出变量,循环, 条件判断。

提示: 在标签 或者{{ }}中,可以使用任意的JavaScript语法。

下面介绍如何使用这三种语法格式.

2. 输出变量

语法:

  • {{=it.xxx}}

用途:在渲染页面时,将一个变量显示在页面上

参考如下示例:




    Alpaca-Spa-2.0 JS
    

    
    

    

    



    

示例中的Alpaca.Tpl( )方法,传递了一个对象作为参数,对像中有三个属性,data表示要传递的数据(对象格式),from表示模板元素,to表示要渲染的位置。在浏览器中运行这个页面,结果如下:

Name:Cheng!
Age:26!

3. 循环

语法:

  • xxx
  • {{ for(){ }}xxx{{ } }}

用途:在遍历数组或者对象时候使用

参考如下示例:




    Alpaca-Spa-2.0 JS
    

    
    

    
    


    

结果如下:

0:
支付方式:支付宝
支付金额:125
支付时间:2016-11-12
1:
支付方式:微信
支付金额:130
支付时间:2016-10-12

4. 条件判断

语法:

  • xxx
  • {{ if(condition){ }}xxx{{ } }}

用途:在需要做条件判断的分支环境中使用

参考如下示例:




    Alpaca-Spa-2.0 JS
    

    
    

    
    


输出结果:

条件为true的情况

5. Alpaca.Tpl()方法

Alpaca.Tpl(option) 是一个用来渲染页面的方法,接受一个对象参数option,参数option中可以包含以下字段:

  • option.data

数据对象,为渲染模板提供数据

Alpaca.Tpl({data:{name:'Alpaca-spa'}})

  • option.from

模板位置,可以是任意的页面元素,选择方法与Jquery的选择器相同

Alpaca.Tpl({from:'#template',to:'#div',data:{name:'Alpaca-spa'}})

  • option.to

被渲染位置

Alpaca.Tpl({from:'#template',to:'#div',data:{name:'Alpaca-spa'}})

  • option.place

指定模板渲染的位置。当place被指定时,模板位置与被渲染位置相同

Alpaca.Tpl({place:'body',data:{name:"zp"}})

  • option.template

指定渲染的模板文件。当template被指定时,模板从当前页面元素变为指定的html文件

Alpaca.Tpl({to:'body',template:'layer.html',data:{name:"zp"}})

注: 使用另一个页面作为模板,需要配置web服务器,在后面章节【视图高级用法】中会做详细介绍

示例

使用参数:data from to:



    
        
        alpaca-spa.2.0
        
        
        
        
    
    
        

输出结果:

Welcome to Alpaca-spa!

使用参数:place:



    
        
        alpaca-spa.2.0
        
        
        
    
    
        Hello {{=it.name}}!
    

输出结果:

This is Alpaca-spa!
template:

使用参数:template:

创建两个html页面:template.html,test-template.html

注: 使用template参数指定另一个页面为模板时,需要配置web服务器,确保template路径正确,详情请参考后面章节【视图高级用法】。

template.html 文件用来做模板,内容如下:

This is {{=it.name}}.

test-template.html 文件是用来测试该示例的页面,内容如下:




    Alpaca-Spa-2.0 JS
    

    
    

    





在浏览器中访问test-template.html页面,输出结果:

This is Alpaca-spa.

通过上面的示例,可以发现template.html中的内容被渲染到了当前页面。

路由

1. 什么是路由

如果您已经看过前面入门示例中关于路由的示例,相信您已经了解了在Alpaca-Sap.js中,路由的功能是将Url中hash部分映射到一个js方法。

例如上面的示例:




    Alpaca-Spa-2.0 JS
    

    
    

    

    



{{=it.text }} Alpaca.



在浏览器中输入http://127.0.0.1/examples/router-index.html#/index/index/index

结果弹出提示框:

Hello Router

在浏览器中输入http://127.0.0.1/examples/router-index.html#/index/index/index2

页面中显示:

Hello Alpaca.

可以发现,Url中hash的映射关系 :

#/index/index/index 映射到 Alpaca.IndexModule.IndexController.indexAction()方法

#/index/index/index2 映射到 Alpaca.IndexModule.IndexController.index2Action()方法

路由的组成:

Alpaca-Sap.js中,路由用Url中的hash部分表示,主要有三部分组成,模块,控制器,动作。格式:#/模块/控制器/动作

例如:Url中 #/admin/user/add 表示 admin模块,user控制器,add动作。

对应js代码中 Alpaca.AdminModule.UserController.addAction()方法。

那么如何在js代码中定义模块,控制器,方法呢?

定义模块:

Alpaca.AdminModule = {};

模块是Alpaca的一个对象,以Module结尾。上面示例定义了一个名为admin的模块。

定义控制器:

Alpaca.AdminModule.UserController ={};

控制器是模块的一个对象。以Controller 结尾。上面示例定义了一个名为user的控制器,属于admin模块。

定义动作:

Alpaca.AdminModule.UserController={
    addAction:function(){
        alert('Hello Router');
    },
}

动作是控制器中的一个方法,以Action 结尾。上面示例在user的控制器中定义了一个add方法,

2. 如何使用路由

在Alpaca-Spa.js中使用路由有三种方式:

  • 1 在浏览器的地址栏中直接输入Url,例如上面的示例。

  • 2 在页面加载完成时,使用 Alpaca.run()方法。

  • 3 使用Alpaca.to()方法。

下面分别介绍Alpaca.run()方法与Alpaca.to()。

3. Alpaca.run()

Alpaca.run()一般在页面加载完成时调用,用来执行默认路由,例如:

$().ready(function () {
    Alpaca.run();
});

在浏览期中打开页面,结果如下:

Welcome use Alpaca-spa 2.0 !

这是因为当Alpaca.run()方法中的参数为空时,调用了Alpaca-Spa.js的内置默认路由:#/alpaca/alpaca/index , 对应方法: Alpaca.AlpacaModule.AlpacaController.indexAction()。 这个方法在页面中输出了: Welcome use Alpaca-spa 2.0 !

下面示例如何修改页面加载时的默认路由:

新建页面 router-default.html ,内容入下:




    Alpaca-Spa-2.0 JS
    

    
    

    

    






浏览器中打开页面,结果如下:

Hello I'm your default Router.

通过上面的示例,可以看出为Alpaca.run()方法传递一个参数"#/index/index/index",就可以改变页面加载时执行默认的路由了。上面的示例中,我们将默认路由改为了#/index/index/index。

4. Alpaca.to()

在介绍Alpaca.to()方法使用之前,先来看一个示例:




    Alpaca-Spa-2.0 JS
    

    
    

    

    



{{= it.title}}

点我执行index2

在浏览器中运行该页面,然后点击“点我执行index2”,结果如下:

Test Router:

点我执行index2 调用index2!

通过上面的示例,可以看出Alpaca.to()方法的作用是调用路由。

Alpaca.to()方法可以传递两个参数Alpaca.to(router,data), 其中router是上面示例中的路由,data是可选参数,一个对象类型,代表传递的数据。参考下面的示例:




    Alpaca-Spa-2.0 JS
    

    
    

    

    



{{= it.title}}

点我执行index2

在浏览器中运行该页面,然后点击“点我执行index2”,结果如下:

Test Router:

点我执行index2 调用index2: hello alpaca!

通过上面的示例,可以看出动作index2对应的方法可以接受一个参数data,这个data就是Alpaca.to(router,data)方法传递过去的data对象。

5. 关于hash何时被改变

条件1:当前执行的hash必须有效,
条件2:如果未使用layout,则view的CaptureTo等于DefaultLayoutCaptureTo
条件2:如果使用了layout,则layout的CaptureTo等于DefaultLayoutCaptureTo

视图高级用法

1 简介

视图功能是Alpaca-Spa.js的核心功能,主要解决前端JavaScript实现页面嵌套,页面数据渲染,页面局部渲染等功能。使用视图功能需要配置web服务器,例如apache, nginx等,将网站的根目录设置为项目所在的目录。

推荐的目录结构如下:

-application
  -index
    -controller
       index.js
    -view
       -index
            index.html
            index-2.html
            index-3.html
       -layout
            -part
               leftMenu.html
            layout.html
    index.js
   -test
     -controller
       index.js
    -view
       -index
            index.html
            index-2.html
            index-3.html
     test.js
   index.html
1. 示例中的application是项目的根目录,应该将web服务器的根目录设置为此目录。

2. application目录下面有两个子目录,1个html文件。
   index        index目录用来存放当前项目中,所有index模块相关的文件
   test         test目录用来存放当前项目中,所有test模块相关的文件
   index.html   index.html用来做当前项目的入口文件

3.index目录里面有两个目录controller,view,一个js文件
   controller   用来存放index模块的控制器的js代码。里面有一个控制器js文件,index.js
   view         用来存放index模块的视图部分的js代码。
                示例中view目录里面有一个子目录index,用于存放index控制器中相关的模板,
                本示例中,有三个模板:index.html,index-2.html,index-3.html
                还有一个子目录layout,用于存放公共的布局信息,
                layout目录中的layout.html是默认的布局模板文件
                layout目录中的还有一个子目录part,用来存放页面中其他公共区域,例如菜单等
   index.js     index.js是index模块的模块级别的js代码。
                推荐在这个文件里面做模块的定义,例如:Alpaca.IndexModule = {};

4.test目录与index目录同理

2 使用View

了解完上面的目录结构之后,我们来学习使用Alpaca.View()方法,参看下面的示例。

application/index.html 文件中的内容:




    Alpaca-Spa-2.0 JS
    

    
    

    
    

    


application/index/index.js 文件中的内容:

/* 1 定义Index模块 */
Alpaca.IndexModule = {};

application/index/controller/index.js 文件中的内容:

/* 1 定义Index模块中的IndexController */
Alpaca.IndexModule.IndexController = {
    //index动作,创建一个视图
    indexAction : function (){
        //视图默认渲染到#content位置,可以通过参数中传递to字段改变渲染位置
        //视图模板默认位于index/view/index/index.html,
        //即:默认模板位置为:[模块名]/view/[控制器名]/[动作名].html
        //可以通过参数中传递template字段改变模块路径
        var view = new Alpaca.View();
        return view;
    },
};

application/index/view/index.html 文件中的内容:

hello View !!

在浏览器中,访问网站根目录下的index.html,结果如下:

hello View !

上面的示例中,我们创建了index模块,index控制器,index动作,并且在indexAction中通过Alpaca.View()方法创建了一个视图,运行结果是视图模板中的内容被渲染到了页面的#content位置中。这就是Alpaca.View()的用途。

Alpaca.View()方法

Alpaca.View(option) 是一个用来创建视图页面的方法,接受一个对象参数option,参数option中可以包含以下字段:

  • option.data

数据对象,为渲染模板提供数据

例如:Alpaca.View({data:{name:'Alpaca-spa'}})

  • option.to

设置被渲染位置,默认位置是#content

例如:Alpaca.View({data:{name:'Alpaca-spa'},to:'#divId'})

  • option.template

指定渲染的模板文件。默认是所属模块view目录下所属controller同名目录下action同名的.html文件,即:默认模板位置为:[模块名]/view/[控制器名]/[动作名].html

如果需要改变视图模板,只需要这样写即可:template:'index2',这样就会使用同名controller下的index2.html作为模板。

这是因为函数内部自动格式化了该参数,如果不想使用自动格式化功能,请使用notFormat参数,设置notFormat:true 即可。

例如:Alpaca.View({data:{name:'Alpaca-spa'},to:'body',template:'index2'})

  • option.notFormat

默认为false,表示系统会自动格式化template参数,如果设置为true,如下例,视图将使用根目录下的index-test.html文件作为视图模板。
Alpaca.View(template:'/index-test.html',notFormat:true})

3 使用Layout和Part

实际的web项目开发中,大部分页面都是有结构的,比如总体的布局,公用的菜单、页头、页尾等。Alpaca-sap.js使用layout,part来解决这类问题。

继续上面介绍View的示例:

修改application/index/controller/index.js 文件中的内容为:

/* 1 定义Index模块中的IndexController */
Alpaca.IndexModule.IndexController = {
    //index动作,创建一个视图
    indexAction : function (){
        //视图默认渲染到#content位置,可以通过参数中传递to字段改变渲染位置
        //视图模板默认位于index/view/index/index.html
        //可以通过参数中传递template字段改变模块路径
        //即:默认模板位置为:[模块名]/view/[控制器名]/[动作名].html
        var view = new Alpaca.View();
        return view;
    },

    //test,测试layout,part。
    //layout视图默认渲染到body位置, 默认layout文件路径是view/layout/layout.html
    //part视图默认路径是view/layout/part目录下与其创建参数中name字段同名的html文件
    //part视图默认渲染位置是 id与其创建参数中name字段同名的元素位置。
    testAction : function (){

        //视图
        var view = new Alpaca.View();

        //layout 布局视图
        var layout = new Alpaca.Layout();

        //part 部件视图,默认路由位于view/layout/part中,文件名默认与name属性相同
        //part 的默认渲染位置与其name属性相同,当然也可以通过to属性指定
        var part = new Alpaca.Part({name:'leftMenu'});

        //将part添加到layout中,part的默认渲染位置与其name属性相同,也可以通过to属性指定
        layout.addChild(part);

        //设置视图的layout
        view.setLayout(layout);

        //在view中,向layout中传递数据
        view.setLayoutData({'layoutData':666});

        //在view中,向part中传递数据
        view.setPartData({leftMenu:{'partData':888}});

        return view;
    },
};

application/index/view/layout/layout.html 文件中的内容为:

This layout ! {{=it.layoutData}}

application/index/view/layout/part/leftMenu.html 文件中的内容为:

This is View for leftMenu (part view) {{=it.partData}}

在浏览器中访问index.html#/index/index/test,结果如下:


This layout ! 666

This is View for test action
This is View for leftMenu (part view) 888

上面的示例演示了如何使用 layout、part来渲染复杂页面。

Alpaca.Layout()方法

Alpaca.Layout(option) 是用来创建一个layout布局的视图对象的方法,接受一个对象参数option,参数option中可以包含以下字段:

  • option.data

数据对象,为渲染模板提供数据

例如:Alpaca.Layout({data:{name:'Alpaca-spa'}})

  • option.to

设置被渲染位置,默认位置是body

例如:Alpaca.Layout({data:{name:'Alpaca-spa'},to:'#divId'})

  • option.name

指定layout的名字。默认为layout

layout默认的模板路径是所属模块view目录下layout目录下的layout.html文件

通过name字段可以修改模板的路径为:所属模块view目录下layout目录下与name同名的html文件

例如:Alpaca.Layout({data:{name:'Alpaca-spa'},to:'body',name:'layout2'})

Alpaca.Part()方法

Alpaca.Part(option) 是用来创建一个part布局的视图对象的方法,接受一个对象参数option,参数option中可以包含以下字段:

  • option.data

数据对象,为渲染模板提供数据

例如:Alpaca.Part({data:{name:'Alpaca-spa'}})

  • option.name

指定Part的名字。

Part默认的模板路径是所属模块view\layout\part目录下与其name同名的html文件

Part默认的渲染位置是id与其name同名的元素

通过name字段可以达到指定他的视图模板路径,以及渲染位置的效果,例如,

例如:Alpaca.Part({data:{name:'Alpaca-spa'},name:'top'})

  • option.to

设置被渲染位置,默认位置是id与其name同名的元素

例如:Alpaca.Part({data:{name:'Alpaca-spa'},to:'#divId'})

4 ready()方法

视图渲染完毕后会执行view.ready()方法,例如

var view = new Alpaca.View()

//视图渲染完成后执行ready方法。
view.ready(function () {
    console.log('视图渲染完成了...');
})

return view;

5 自定义显示效果

通过设置view.show方法可以自定义视图显示效果,例如:

var view = new Alpaca.View();

//自定义视图渲染效果为闪入效果。
//注意:在自定义视图显示效果时,需要调用onLoad事件,来触发执行ready函数。
view.show = function (to, html) {
    var that = this;
    $(to).fadeOut("fast", function () {
        $(to).html(html);
        $(to).fadeIn("fast", function () {
            that.onLoad();
        });
    });
};

return view;

上面面示例代码,实现了视图渲染时的闪入效果。

6 init()与release()方法

如果在控制器中定义了init()方法,那么在执行当前控制器的所有action方法前都会执行init()方法。如果在控制器中定义了release()方法,那么在执行完成当前控制器的所有action方法之后,都会执行release()方法,

参考示例:

/* 定义Index模块中的TestController */
Alpaca.IndexModule.TestController = {

    //init方法,当前控制下的所有动作在执行前,都回执行init方法
    init:function(){
        console.log('执行action之前,执行init()方法');
    },

    //release方法,当前控制下的所有动作在执行前,都回执行release方法
    release:function(){
        console.log('执行action之后,执行release)方法');
    },
};

内置对象与方法

交流方式

联系我们

QQ群: 298420174

Alpaca-Spa-2.0 前端单页面框架_第1张图片
图片名称

作者: Sponge
邮箱: [email protected]

你可能感兴趣的:(Alpaca-Spa-2.0 前端单页面框架)