jdcloud-m(筋斗云) 变脸式单网页应用框架

单网页应用(SPA)的概念如今已被H5前端开发者广泛接受，从用户使用的角度，它相比传统网页，操作体验更加平滑而又节省流量；从开发的角度看，前后端解耦，架构更加清晰。

手机应用一般都是有多个页面的，如果每个页面都做成一个网页或一个单网页应用，整体操作体验和开发体验都不好。
常用解决方法就是使用逻辑页面，用户看到的每个页面并不是一个个独立的H5应用，而是一个H5应用中的一个逻辑页而已，这样实现出来的应用接近手机原生应用。

变脸式应用就是支持逻辑页面的单网页应用。像川剧中的变脸艺术一样，展现多个角色（页面）并不需要多个演员（网页）来扮演，直接切换面具（逻辑页面）就可以了。
变脸式应用一定是一个单网页应用。

jdcloud-m是一个变脸式单网页应用的开发框架，也称为筋斗云前端框架，它是筋斗云框架(jdcloud)的前端部分，可以独立创建H5应用程序，其中”m”表示mobile，意味着移动前端。
jdcloud-m框架的核心是页面路由和接口调用，提供多逻辑页支持和远程接口调用支持，同时对制作安卓、苹果原生应用也提供良好的支持，因而也是一个全平台H5应用框架。

运行变脸式应用

可以从github上下载jdcloud-m：https://github.com/skyshore2001/jdcloud-m

如果已安装git工具, 可以直接下载：

git clone https://github.com/skyshore2001/jdcloud-m.git myproject

下载后，假定myproject是我们的项目目录。其中，子目录server是应用程序目录，开发主要集中在这里。tool是用于优化和发布的工具，之后在站点上线优化时介绍。

设置WEB服务器（如Apache/nginx/IIS等），添加虚拟目录myproject, 指向myproject/server目录，这时，就可以直接运行起前端应用：

http://localhost/myproject/

建议使用chrome浏览器，按F12打开开发者模式，点左上角的手机模式模拟(toggle device toolbar)或按Ctrl-Shift-M，模拟手机上的运行效果应用。

在这个示例应用中，用户可以创建订单、查看订单列表和订单详情，查看个人信息等，分别在各个逻辑页中展现，逻辑页相互链接和跳转，在逻辑页跳转时不会刷新整个网页，这就是变脸式应用。

变脸式应用与后端的交互完全是是业务数据，后端不传输任何网页、网页模板或前端样式。这里由于还没有连接后端，示例中使用的数据均为模拟后端接口返回的数据。

筋斗云前端支持模拟接口返回数据，这在前端开发时非常有用。文件mockdata.js中即是应用使用到的接口模拟，下面章节里将会详细介绍。

在server目录下，lib目录下的js/css文件都属于框架使用的文件，不宜随意修改，其中app_fw.js是筋斗云前端框架的核心部分。

page目录是默认的逻辑页目录，比如首页、登录页、订单列表等逻辑页的html和js文件都放在这里。

cordova目录是用于制作原生手机app时使用的。jdcloud-m框架支持全平台应用，即一套H5代码，可同时制作安卓应用、苹果应用、微信微站等。

逻辑页 - HelloWorld

本例在首页中添加一个链接，显示自制的HelloWorld逻辑页面。

制作一个逻辑页面，存到文件page/hello.html:

<div>
    <div class="hd">
        <h2>HelloWorld</h2>
    </div>

    <div class="bd">
        <p>Hello, world</p>
    </div>
</div>

这是个html片段，其中class="hd"与class="bd"分别代表逻辑页的标题栏和主体部分。一般应保持这样的结构，即使不需要标题栏，也建议保留hd这个div，将其设置隐藏即可(style="display:none")。

在首页page/home.html中添加一个链接过来：

    ...
    <div class="bd">
        ...
        <li><a href="#hello">Hello</a></li>
    </div>

在浏览器时刷新应用程序进入首页，点击Hello链接，就可以看到新逻辑页Hello显示出来了。
jdcloud可以动态加载逻辑页，并为它指定id为”hello”(即页面文件名)。
除了使用链接，还可以通过JS代码MUI.showPage("#hello")来显示该页。

点击浏览器的返回按钮，可以回到首页。在返回时，没有网页刷新的过程，这也是变脸式应用的典型特点。

我们也可以在逻辑页的hd部分里为应用添加返回按钮，如：

    <div class="hd">
        <!-- 加上返回按钮 -->
        <a href="javascript:history.back();" class="icon icon-back"></a>
        <h2>Hello</h2>
    </div>

改好后，不必刷新页面重新从首页进入，直接在浏览器控制台中输入：

MUI.reloadPage();

就可以直接查看到更新后的逻辑页了。

jdcloud-m支持逻辑页热更新技术，可以实时热更新当前页面，并保留当前的应用状态。这一技巧在开发调试逻辑页时非常好用，尤其对于复杂的应用程序，不必从首页操作进来。类似的技巧还有卸载一个逻辑页，以便再进入时可重新初始化：

MUI.unloadPage(); // 卸载当前页
MUI.unloadPage("hello"); // 卸载指定页

如果你嫌首页上加的链接太难看，可以使用MUI默认集成的weui样式库来润色它，如：

    <div class="weui_cells" style="margin-top:100px">
        ...
        <!-- 显示为一个button -->
        <li class="weui_cell" style="display:block"><a href="#hello" class="weui_btn weui_btn_default">Hello</a></li>
    </div>

同样地，在修改好后，直接在控制台输入MUI.reloadPage()看效果。

jdcloud-m的核心是页面路由(showPage)和接口调用(callSvr)。它自身不提供移动UI样式库，而是通过集成的weui样式库来提供移动UI样式。
weui是一套同微信原生视觉体验一致的基础样式库，由微信官方团队开发，关于weui的使用可以参考https://weui.io/或自行搜索。
当然你也可以把它换成你自己喜欢的UI库。

为逻辑页添加样式和逻辑

上一节中，我们添加了一个逻辑页，名为”hello”。
要为它添加一些样式（仅在这个逻辑页使用），一般在页面div中内嵌style标签。
要添加逻辑，一般在页面div上使用mui-script属性指定js文件，并通过mui-initfn标签指定页面初始化函数。

修改hello.html页面文件如下：

<div mui-initfn="initPageHello" mui-script="hello.js">
<style>
p {
    color: red;
}
</style>
    <div class="hd">
        <a href="javascript:history.back();" class="icon icon-back"></a>
        <h2>HelloWorld</h2>
    </div>

    <div class="bd">
        <p>Hello, world</p>
    </div>

</div>

在上例中，在内嵌的style标签中为”p”标签指定样式，让它显示红色。

jdcloud-m支持自动限定逻辑页样式作用域。 即框架保证这个样式只会用于当前逻辑页，不会污染到其它页面。

你也可以加页面id前缀来指定：

<style>
#hello p {
    color: red;
}
</style>

在不支持这一特性的其它框架中，一般都必须像这样人工来限定。

上面逻辑页中通过mui-script=”hello.js”指定了js文件，创建page/hello.js文件如下：

function initPageHello() 
{
    var jpage = $(this);
    jpage.on("pagebeforeshow", onBeforeShow);
    jpage.on("pagehide", onHide);

    function onBeforeShow()
    {
        app_alert("before show");
    }
    function onHide()
    {
        app_alert("hide");
    }
}

上面演示了逻辑页进入和退出时常用的事件处理，很容易理解。
app_alert是框架提供的异步弹出框函数，可用于提示消息(类似alert)、确认消息(类似confirm)、问询消息(类似prompt)等，弹出框界面也可自由定制，详见API文档。
一般从后端取数据的操作都习惯放在pagebeforeshow事件中处理。另外还有pageshow, pagecreate等事件。

调用后端接口 - callSvr

调用后端接口是jdcloud-m框架提供的两大核心功能之一。

继续hello页面的例子，假如每次进入页面时，不是固定的显示”hello, world”，而是需要根据服务端的返回内容来显示hello的内容，比如”hello, skys”或是”hello, jdcloud”。

我们需要定义一个叫做”hello”的交互接口，由前端发起一个HTTP GET请求，比如：

http://myserver/mypath/api.php?ac=hello

如果调用成功，后端返回JSON格式的数据如下：

[0, "jdcloud"]

其中0是返回码，表示调用成功。如果调用失败，可返回：

[99, "对不起，服务器爆炸了"]

以上就是一个符合筋斗云接口规范的简单例子（称为业务查询协议-BQP），在成功调用时应返回[0, data]，在调用失败时应返回[非0, 错误提示信息]。

有了清晰的接口定义，前后端就可以并行开发了。
在前端，我们把页面稍作修改以动态显示hello的内容：

    <div class="bd">
        <p>Hello, <span id="what"></span></p>
    </div>

再写一段逻辑，每当进入页面时调用hello接口并显示内容，我们选择onBeforeShow回调来做这件事：

function initPageHello() 
{
    var jpage = $(this);
    jpage.on("pagebeforeshow", onBeforeShow);

    function onBeforeShow()
    {
        callSvr("hello", api_hello);
    }

    function api_hello(data)
    {
        jpage.find("#what").html(data);
    }
}

callSvr是框架提供的一个重要函数，它封装了ajax调用的细节，完整的函数原型为：

callSvr(ac, param?, fn?, postParam?, options?);

其中，ac是调用接口名，fn是回调函数，param和postParam分别是URL参数和POST参数。除ac外，其它参数均可省略。例如

callSvr("hello");
callSvr("hello", {id: 1}); // URL: hello?id=1
callSvr("hello", {id: 1}, api_hello); // function api_hello(data) {}
callSvr("hello", api_hello, {name: "hello"});

回调函数api_hello仅在成功时被调用，参数data是实际数据，即[0, data]中的data部分，不包括返回码0。

调用模拟接口

上面代码写好了，后端接口还没做好怎么测试？

jdcloud-m支持模拟接口返回数据。 在mockdata.js中，可以设置接口的模拟返回数据：

MUI.mockData = {
    ...
    "hello": [0, "jdcloud"]
}

此处还可以用函数做更复杂的基于参数的模拟，详见API文档，查询MUI.mockData。

运行H5应用，进入hello页面，看看是不是可以正常显示了？

可以动态修改模拟数据，在控制台中输入：

MUI.mockData["hello"] = [0, "skys"]

然后从hello页返回首页，再进入hello页，看看显示内容是不是变了？

再改一个出错的试试：

MUI.mockData["hello"] = [99, "对不起，服务器爆炸了"]

进入hello页，我们看到，调用失败时，回调函数api_hello没有执行，而是框架自动接管过去，显示出错信息。

调用真实接口

在后端接口开发好后，我们可去掉对这个接口的模拟，直接远程调用服务端接口。这需要配置好后端接口的地址。

我们用php写一个简单的符合筋斗云接口规范的后端实现，通过名为”ac”的URL参数表示接口名，在server目录中创建文件api.php如下：

<?php

@$ac = $_GET['ac'];
if ($ac == 'hello') {
    $what = "jdcloud @ " . time();
    echo json_encode([0, $what]);
}
else {
    echo json_encode([1, "bad ac"]);
}

配置好php的调用环境后，访问

http://localhost/myproject/api.php?ac=hello

输出类似这样（根据时间动态变化）：

[0,"jdcloud @ 1483526151"]

回到前端，我们在app.js中设置：

    $.extend(MUI.options, {
        serverUrl: "api.php",
        serverUrlAc: "ac"
    });

serverUrl选项设置了服务端的URL地址，因为我们将”api.php”放在与”index.html”同一目录下，所以直接用相对路径就可以了。serverUrlAc选项定义了接口名对应的URL参数名称，即?ac={接口名}.
在mockdata.js中去掉对”hello”接口的模拟，刷新应用就可以看到调用后端的效果了。

如果前后端不在同一台服务器上，则要将URL写完整，如

serverUrl: "http://myserver/myapp/api.php";

注意：后端应设置好允许跨域请求。这里不做详述。

以上讲述的是符合筋斗云接口规范的接口调用设置，如果不符合该规范，请阅读下一节“接口适配”。

接口适配

在上例中，假定了后端接口兼容筋斗云接口规范，例如返回格式为[0, jsonData]及[非0, 错误信息]。
如果接口协议不兼容，则需要做接口适配。

假定协议约定接口返回格式为：{code, msg, data}，
例如上例中的hello接口，调用成功时返回：

{
    "code":"0",
    "msg":"success",
    "data":"jdcloud"
}

失败返回：

{
    "code":"99",
    "msg":"对不起，服务器爆炸了"
}

这时需要对callSvr进行适配，可以在app.js中，设置 MUI.callSvrExt如下:

    MUI.callSvrExt['default'] = {
        makeUrl: function(ac) {
            return 'http://hostname/lcapi/' + ac;
        },
        dataFilter: function (data) {
            if ($.isPlainObject(data) && data.code !== undefined) {
                if (data.code == 0)
                    return data.data;
                if (this.noex)
                    return false;
                app_alert("操作失败：" + data.msg, "e");
            }
            else {
                app_alert("服务器通讯协议异常!", "e"); // 格式不对
            }
        }
    };

在可mockdata.js中设置模拟数据：

MUI.mockData = {
    "User.get": {code: 0, msg: "success", data: user},
    "hello": {code: 0, msg: "success", data:"myworld"}
    ...
}

上例中，User.get接口在显示首页是会调用，所以和”hello”接口一并模拟下。

测试接口调用：

callSvr("hello", console.log);
或
callSvrSync("hello");

callSvrSync是callSvr的同步调用版本，它直接等到调用完成才返回，且返回值就是调用成功返回的数据。

可以动态修改模拟数据：

MUI.mockData["hello"] = {code: 99, msg: "对不起，服务器爆炸了"}