文档中心

前言

在继续阅读之前,请先记住下面几个站点:
BingoTouch API文档:http://dev.bingocc.com:8060/bingotouch-ui-doc/
BingoTouch UI预览:http://dev.bingocc.com:8060/bingotouch-ui/

目录结构

下载BingoTouch-UI源码之后,将其解压缩到任意目录即可看到以下的目录结构:

bingotouch/
├── css/
│    ├── bingotouch.css
│    ├── bingotouch.min.css
├── images/
├── js/
│    ├── baiduTemplate.js
│    ├── bingotouch.js
│    ├── bingotouch.min.js
│    ├── cordova.js
│    ├── iscroll.js
│    ├── zepto.js
│    ├── require.js
│    └── plugin/  
│         ├── bistoreplugins.js
│         ├── caiyunplugins.js
│         ├── sharesdkplugin.js
│         └── linkplugins.js
├── modules/
├── res/
└── index.html

这里的文件有的不是必须,有的是可以代替的。bingotouch.*的BingoTouch的核心框架,必须引用,其他为第三方辅助框架。一般生产环境建议使用带min.*的文件。

bingotouch.css

包含BingoTouch的默认浏览器重置样式、全局样式、布局样式、控件样式、组件样式

bingotouch.js

BingoTouch的js框架,具体包含bingtouch单页处理、UI控件、组件,js 原生API接口

baiduTemplate.js

提供一套模板语法,用户可以写一个模板区块,每次根据传入的数据,生成对应数据产生的HTML片段,渲染不同的效果。
具体用法请查看网址:http://baidufe.github.io/BaiduTemplate/

cordova.js

Cordova.js是Cordova核心JS文件。
Cordova是一个开源的跨平台移动应用开发框架,能使开发者们在只使用标准网络技术(HTML5、CSS和JavaScript)的情况下开发跨平台应用。
PS:你在调用API时可能会直接使用到这个文件
参考地址:http://cordova.apache.org/docs/en/2.6.0/

iscroll.js

iscroll.js是Matteo Spinelli开发的一个js文件,使用原生js编写,不依赖与任何js框架。旨在解决移动webkit系浏览器的区域滚动问题,兼容mobile
safari、android默认浏览器、safari、chrome、firefox5+、opera11+、IE9+及其他webkit核心浏览器。

zepto.js

zepto.js 是支持移动WebKit浏览器的JavaScript框架,具有与jQuery兼容的语法。
参考地址:http://zeptojs.com/

require.js

RequireJS是一个JavaScript文件或者模块的加载器。 BingoTouch使用的是其JS文件加载的功能,为了实现在单页模式下section页面加载专属的JS文件。

页面结构

BingoTouch 本身有严格的页面结构,当然也可以完全不使用这种结构。下面我们就来一起了解BingoTouch的结构。

基本模板

使用BingoTouch框架,最基本要引用的CSS和JavaScript以及HTML页面如下(所有JS和CSS均使用相对地址)

<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
<meta name="format-detection" content="telephone=no" />
<meta name="viewport" content="width=480,user-scalable=no" />

<link rel="stylesheet" href="css/bingotouch.css" /> 
<link rel="stylesheet" href="css/app.css" />

<!-- 函数库 -->
<script src="js/cordova.js"></script>
<script src="js/zepto.js"></script>
<script src="js/iscroll.js"></script>
<script src="js/baiduTemplate.js"></script>
<script src="js/bingotouch.js"></script>
<script src="js/app/app.js"></script>

<title>BingoTouch</title>
</head>
<body>
    Hello world!
</body>
</html>

由于此基本模板没有涉及任何结构,那么接下来就让我们一起来认识BingoTouch的单页的基本结构。

单页主页面

在BingoTouch单页模式中,弱化HTML的概念,把HTML当成一个容器,BODY中显示的主体内容才是页面,一个HTML容器中可以存放1个或者多个页面,每个页面放置于Section中。而一个页面(Section)中必有主体内容(content),也有可能包含头部内容、底部内容,甚至一些侧滑菜单等。
所以,以我们通常看到的一个移动应用的界面中包含了顶部Title和主体内容的页面代码如下:

<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
<meta name="format-detection" content="telephone=no" />
<meta name="viewport" content="width=480,user-scalable=no" />

<link rel="stylesheet" href="css/bingotouch.css" /> 
<link rel="stylesheet" href="css/app.css" />

<!-- 函数库 -->
<script src="js/cordova.js"></script>
<script src="js/zepto.js"></script>
<script src="js/iscroll.js"></script>
<script src="js/baiduTemplate.js"></script>
<script src="js/bingotouch.js"></script>
<script src="js/app/app.js"></script>

<title>BingoTouch</title>
</head>
<body>
    <div id="section_container">
       <section id="index_section" class="active"> 
            <div class="header" data-fixed="top">
           <div class="title row-box">
                    <div class="box-left">
                    </div>
                    <div class="span1">
                        <h1>首页</h1>
                    </div>
                    <div class="box-right">
                    </div>
                </div>
            </div>
            <div class="content">        
          <h1>欢迎使用BingoTouch</h1>
            </div>
           <div class="footer" data-fixed="bottom">    
           </div> 
       </section>    
    </div>
</body>
</html>

这里可以看到单页的基本结构是以Section为单个页面的容器,页面中显示的标题导航header和主体内容content都位于Section之下,并且各自可以显示需要的内容。
也就是如下图的一个结构:

单页页面片段

片段页面相对就简单很多,如下图

<section id="demo_section"> 
    <div class="header" data-fixed="top">
       <div class="title row-box">
              <div class="box-left">
           </div>
           <div class="span1">
              <h1>Demo</h1>
           </div>
           <div class="box-right">
           </div>
        </div>
    </div>
    <div class="content">
       <h1>欢迎使用BingoTouch</h1>
    </div>
    <div class="footer" data-fixed="bottom">
    </div> 
</section>  

页面片段也即是主页面里面的section块,从这里看其他页面是很简洁的。

生命周期

如下图所示:

上图中所述的事件将在下面讲解

页面事件

主页面事件

app.page.onReady

Dom结构加载完成后执行

app.page.onLoad

页面所有元素加载完成,且设备已经准备(deviceReady)

页面片段事件

app.section.onReady

Dom结构加载完成后执行

app.section.onLoad

页面所有元素uiwidget完成

app.section.onBack

页面后退触发的事件

文件引用

此部分主要说明js、css文件引用的问题。

主页js、css文件的引用

引用放在head标签里即可。使用方法如下:

<link rel="stylesheet" href="css/bingotouch.css" /> 
<!-- 应用样式 -->
<link rel="stylesheet" href="css/app.css" />

<!-- 函数库 -->
<script src="js/cordova.js"></script>
<script src="js/zepto.js"></script>
<script src="js/iscroll.js"></script>
<script src="js/baiduTemplate.js"></script>
<script src="js/bingotouch.js"></script> 
<script src="js/require.js"></script> 

<!-- 应用脚本 -->
<script src="js/app/app.js"></script>

PS:这里需要注意的是,require.js只有在子页也有js文件要引入时才需要引用。

子页js、css文件的引用

当子页(section页面)有js文件需要引入时,主页需要引入require.js。使用方法如下:

<link rel="stylesheet" href="css/testXXX.css" />
<section>
    ...
</section>
<script>
app.section.onLoad = function() {

    //第一个参数是js文件的数组,可以是远程路径
    //第二个参数是文件加载完成的回调,这里面是你的业务代码
    require(["js/plugin/sharesdkplugin.js"],function() { 
       //文件加载完成的回调
       ...
    }); 
};
</script>

这里有几点注意地方:

  1. css文件引用就直接放在section标签上面
  2. js文件引用就不再是以标签引入,而且使用requireJS加载。

RequireJS加载js文件好处:

  1. 提供文件加载完成的回调,保证了业务代码可在文件加载完成后执行。
  2. 在一个页面会话里面,js文件加载完后会被缓存,当此文件再被加载时,如果已加载就不会再加载(连请求都不会发)。减少了请求,加快页面加载速度。

页面切换

单页的切换跟多页有的不同在于单页是用css3切换,而多页是原生webview的切换。

单页切换

声明式

<div data-role="BTButton"     
     data-url="modules/test_section.html"          
     data-urlarg="{name:'bt', age:'2'}">
    Demo页面
</div>

编程式

ui.load({
    url : 'modules/test_section.html',
    params : {name:'bt', age:'2'}
})

目标页面

<section id="test_section" data-transition="slide" >
    ......
</section>

这里必须注意的是,section块的id必须跟文件名一样且唯一。
data-transition 是设置页面切换的效果,有以下取值:
slide : 从右向左推入
cover : 由右向左切入
slideUp : 由下向上切入
slideDown : 由上向下切入
popup : 弹出效果
flip : 翻转效果
none : 无效果

多页切换

多页的切换的声明式的写法跟单页是一样的,不同的是编程式

app.load({
    url:"modules/test.html",
    params:{name:"bt", age:"2"},
    slideType:"left",
    progress:{show:"false", title:"your title", message:"your message"}
});

slideType:页面切换的方向
progress:页面间切换时的提示窗口,有三个属性,分别是show、title、message
show:为true时,切换页面时显示提示窗口,为false时无提示窗口
title:提示窗口的标题
message:提示窗口的提示信息

注意事项

  1. 单页模式下,所有页面最终都放在一个容器里(即是主页),所以必须保证js、css命名不冲突。
  2. 单页模式下,页面片段的section块id必须跟文件名一致。
  3. 单页模式与多页模式的css、js文件或图片的引用地址(相对路径)的写法是不一样的。 单页模式下所有页面的相对路径是相对于主页来说的(一般主页是index.html)。
    示例:

    bingotouch/
    ├── css/
    │    ├── bingotouch.css
    │    ├── bingotouch.min.css
    ├── images/
    │    └── home.png
    ├── js/
    │    ├── bingotouch.js
    │    └── bingotouch.min.js
    ├── modules/
    │    ├── news_section.html
    │    └── link_section.html
    ├── res/
    └── index.html
    
  • news_section.html里面引用了home.png,他的路径的写法是<img src=“images/home.png” >
  • news_section.html跳转到link_section.html,他的路径写法是data-url=“modules/link_section.html”