grunt-combohtml

combine build html with ssi.

grunt-combohtml

by 拔赤 & 弘树

HTML代码的构建,合并SSI,并提取其中引用的本地css和js,执行动态和静态合并,并输出构建好的html

依赖 Grunt 版本~0.4.5

安装

npm install grunt-combohtml --save-dev

安装后,在 Gruntfile.js 中载入任务

grunt.loadNpmTasks('grunt-combohtml');

grunt.initConfig() 中添加 combohtml 的配置:

grunt.initConfig({
    combohtml:{
        options:{
            encoding:'utf8',
            replacement:{
                from:/src\//,
                to:'build/'
            },
            // 本地文件引用替换为线上地址的前缀 
            relative:'http://g.tbcdn.cn/path/to/project/',
            // 配合relative使用,将页面中所有以CDN引用的JS/CSS文件名进行拼合 
            combineAssets: true, 
            // KISSY Modules Maps File 地址 
            comboMapFile:'http://g.tbcdn.cn/path/to/maps.js',
            tidy:false,  // 是否重新格式化HTML 
            mockFilter:true, // 是否过滤Demo中的JuicerMock 
            comboJS:false, // 是否静态合并当前页面引用的本地js为一个文件 
            comboCSS:false, // 是否静态合并当前页面引用的css为一个文件 
            convert2vm:false,// 是否将juicer语法块转换为vm格式 
            convert2php:false, // 是否将juicer语法块转换为php格式 
            comboExt:'-combo', // 静态合并后的js和css后缀 
            combineExt:'-min',// 所有的脚本是否转换成带-min后缀的形式 
            htmlProxy: '<%= pkg.htmlProxy %>',      // htmlProxy 配置,用于产出线上页面区块替换为本地模块页面 
            htmlProxyDestDir: 'html-fragments'      // html 代理区块页面生成到的目标目录 
            meta: {
                'pageid': '<%= pkg.name%>/${path|regexp,"pages/",""}'
            }
        },
        main:{
            files: [
                {
                    expand: true,
                    cwd:'build',
                    // 对'*.php'文件进行HTML合并解析 
                    src: ['**/*.php'],
                    dest: 'build/'
                }
            ]
        }
    }
});

说明:relative 和 comboJS与comboCSS 的配置互斥!

合并文件提供两种模式:

  1. 代码静态合并:即页面中相对路径引用的资源文件都会被抓取合并为一个:

    options:{
        encoding:'utf8',
        replacement:{
            from:/src\//,
            to:'build/'
        },
        comboJS:true, 
        comboCSS:true,
        comboExt:'-combo'
    }

如果html中引用js和css时带有?nocombo=true参数,则不合并

  1. combo模式合并:若希望页面中引用的相对路径都编译为绝对路径并组成combo的模式http://url/??a.js,b.js,需要开始relative字段,这时comboJScomboCSS字段不起作用

    options:{
        encoding:'utf8',
        replacement:{
            from:/src\//,
            to:'build/'
        },
        // 本地文件引用替换为线上地址的前缀 
        relative:'http://g.tbcdn.cn/path/to/project/',
        // 配合relative使用,将页面中所有以CDN引用的JS/CSS文件名进行拼合 
        combineAssets: true, 
        // KISSY Modules Maps File 地址,根据需要添加 
        comboMapFile:'http://g.tbcdn.cn/path/to/maps.js'
    }

这个是一个非常小众但很有用的功能,当我开发的代码是一个html片段,这个片段是被include到另外一个线上页面的某个位置(通过选择器指定),这个时候我就可以通过grunt-combohtml构建出一个带有线上页面完整信息的html页面,同时,线上页面里对应的位置被替换成了我当前开发的代码片段。这样我就不用为了调试某个线上页面,而去把线上页面的环境给克隆下来,只使用我的本地代理即可,本地代理使用html-proxy来实现,grunt-combohtml 依赖了 html-proxy

其中 htmlProxy 的配置在 abc.json 中指定,这里读取配置,示例配置如下:

  ...
  ,
  "htmlProxy": [{
      "urlReg": "http://tiehang.demo.taobao.net/ksdemo/html-proxy.html", // 要匹配的 url 正则表达式/页面url 
      "replacements": [{    // 需要替换的各个区块和对应的选择器 
          "fragment": "mods/demo/index.html",
          "selector": "#demo"
      }]
  }, {
      "urlReg": "^http://www.baidu.com/$",
      "demoPage": "http://www.baidu.com",   // 当urlReg 为正则表达式时,给定一个遵循该正则的示例页面用于做 html 区块合并 
      "replacements": [{
          "fragment": "mods/demo/index.html",
          "selector": "#lg"
      }, {
          "fragment": "mods/nav/index.html",
          "selector": "#nv"
      }]
  }, {
      "urlReg": "^http://www.taobao.com/$",
      "demoPage": "http://www.taobao.com",
      "replacements": [{
          "fragment": "mods/demo/index.html",
          "selector": "#J_Promo"
      }, {
          "fragment": "mods/nav/index.html",
          "selector": "#J_Nav"
      }]
  }]

页面中的 JuicerMock 片段可以通过mockFilter字段来配置,原理参照grunt-flexcombo

通过 options 中的 meta 配置,以键值对形式传入每个 meta 的 key 和 value,构建时会自动生成对应的一条条 <meta> 标签嵌入 </head> 前。

除了可以通过 <%=pkg.attribute %> 读取环境变量之外,还提供了额外的环境属性,在 meta 中可按需配置,使用时遵循 Juicer 语法:

  • path:当前处理的文件路径(以 src 路径为起点,如 "pages/search/index.html"
  • ts: 时间戳

此外提供一个 Juicer 辅助函数 regexp,按需对上面的环境属性通过正则表达式进行截取或替换,如上面配置中的:

meta: {
    'pageid': '<%= pkg.name%>/${path|regexp,"pages/",""}'
}

代表将 path 中的 pages/ 正则表达式字符串替换为 "",也就是拿掉。

task.run(['combohtml']);

该服务依赖jayli-server,支持标准格式的 SSI include

<!--#include virtual="file.html" -->

除了标准的 SSI 语法支持,0.2.0 还支持重复插入以及简单变量替换:

/**
 * 处理格式为<!--#include ...-->的ssi插入.
 * @param  {JSON}ctx
 * @return {String}
 * @private
 * @example
 *
 * 1. 路径
 * -------------------------------------------------
 * 通过file属性制定的路径若以"."或".."开头则视为相对
 * 路径,否则视为据对路径,当视为绝对路径时,以项目
 * 的src目录作为根目录. 所以上面的代码用绝对路径表示
 * 可以这样写:
 *    <!--include file="/page/foo/sub.html"-->
 * 或者
 *    <!--include file="page/foo/sub.html"-->
 *
 * 2. 重复
 * -----------------------------------------------
 * 可以通过repeat参数来指定重复次数比如:
 *    <!--#include file="../sub.html" repeat="5" -->
 *
 * 3. 简单变量插入
 * ------------------------------------------------
 * 可以通过添加以$开头的属性指定插入文件中可以使用的变量,比如:
 *    <!--#include file="../sub.html" repeat="5"
 *        $name="zhang-san"
 *        $gender="f"
 *        $age="20"
 *        -->
 *
 * 那么sub.html就可以以如下格式使用这些变量:
 *    index  : <%=$__index__ + 1%>
 *    colum  : <%=$__index__ % 3%>
 *    total  : <%=$__count__%>
 *    gender : <%=$gender == 'f' ? '男' : '女' %>
 *    name   : <%=$name%>
 *    age    : <%=$age%>
 *
 * 上面的例子中有两个变量:$__count__、$__index__,
 * 这两个变量是系统自动添加进去的,分别代表文件被
 * 重复的次数以及当前重复索引(以0为起始).
 *
 *  在使用简单变量插入功能时可以使用如下运算符:
 *     +  -  *  /  %  >=  <=  !=  >  <  ?:
 *  注意: 不支持括号,不支持多个三目运算符的嵌套.
 *
 * 注意: 在本程序中凡是以双下划线* "__"开头的变量名都
 * 是系统自动注入的,在inc-vars中不要使用这样变量名,
 * 否则有可能会被覆盖掉.
 */
  • [0.2.7]

    • 加入 options.combineExt,默认为 -min,控制 js、css combo 时的 url 里资源路径是否带 -min
  • [0.2.8]

    • bugfix for juicer render
  • [0.2.9]

    • 解决 juicer 不指定版本号问题
  • [0.2.10]

    • [+] 引入 xssi,支持引入文件的变量解析