npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

grunt-combohtml

v0.2.10

Published

combine build html with ssi.

Downloads

56

Readme

grunt-combohtml

by 拔赤 & 弘树

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

Getting Started

依赖 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-proxy html 区块代理配置

这个是一个非常小众但很有用的功能,当我开发的代码是一个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"
      }]
  }]

Juicer Mock

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

Meta 标签嵌入

通过 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']);

功能说明

SSI

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

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

XSSI

除了标准的 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,支持引入文件的变量解析