Added Intro Docs

jabbany · jabbany · commit 0c27584178d1 · 2014-12-29T22:13:59.000+08:00
diff --git a/demo/intro/index.htm b/demo/intro/index.htm
@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+	<meta http-equiv="X-UA-Compatible" value="IE=9">
+	<title>This is a Sample of the Library</title>
+	<!-- 在这里载入CCL的基础库 -->
+	<link rel="stylesheet" href="../../build/style.css" />
+	<script type="text/javascript" src="../../build/CommentCoreLibrary.js"></script>
+	<!-- 你还可以载入其他的库，比如jQuery之类的 -->
+	<link rel="stylesheet" href="my-page-styles.css" />
+</head>
+<body>
+	<!-- CommentCoreLibrary 的基础 DOM 结构。这个结构也可以动态生成，只要 class 设置正确即可 -->
+	<div id="my-player" class="abp" style="width:100%; height:300px; background:#000;">
+		<div id="my-comment-stage" class="container"></div>
+	</div>
+	
+	<!-- 当然可以放很多别的东西 -->
+	<div class="controlbox">
+		<h3>调试用绑定</h3>
+		<p>这里提供了一些调试用的绑定，可以通过操作它们感受操控 CCL 的方法。打开 main.js 就可以看到实现这些方法的绑定函数。</p>
+		<ul>
+			<li><a href="#" id="btnLoadTimeline">载入一个弹幕列表</a></li>
+			<li><a href="#" id="btnInsertTimeline">插入一个弹幕到弹幕列表</a></li>
+			<li><a href="#" id="btnTimer">启用/重置 定时器来告知播放器目前的播放位置</a> <span id="txPlayPos">0</span></li>
+		</ul>
+	</div>
+	
+	<!-- 下面接入 CCL 代码 -->
+	<script type="text/javascript" src="main.js"></script>
+</body>
+</html>
diff --git a/demo/intro/main.js b/demo/intro/main.js
@@ -0,0 +1,58 @@
+function $(element){
+	// 获取 DOM 对象的短写，如果你在用 jQuery 也可以采用类似的方法
+	return document.getElementById(element);
+};
+
+window.addEventListener('load', function(){
+	// 在窗体载入完毕后再绑定
+	var CM = new CommentManager($('my-comment-stage'));
+	CM.init();
+	
+	// 先启用弹幕播放（之后可以停止）
+	CM.start();
+	
+	// 绑定按钮们
+	$('btnLoadTimeline').addEventListener('click', function(e){
+		e.preventDefault(); // 抑制默认操作
+		var danmakuTimeline = [
+			{
+				"mode":1,
+				"text":"Hello World",
+				"stime":0,
+				"size":25,
+				"color":0xffffff
+			}
+		];
+		CM.load(danmakuTimeline);
+	});
+	
+	$('btnInsertTimeline').addEventListener('click', function(e){
+		e.preventDefault(); // 抑制默认操作
+		var danmaku = {
+			"mode":1,
+			"text":"Hello CommentCoreLibrary",
+			"stime":1000,
+			"size":30,
+			"color":0xff0000
+		};
+		CM.insert(danmaku);
+	});
+	
+	var startTime = 0, iVal = -1;
+	$('btnTimer').addEventListener('click', function(e){
+		e.preventDefault(); // 抑制默认操作
+		startTime = Date.now(); // 设定起始时间
+		if(iVal >= 0){
+			clearInterval(iVal); // 如果之前就有定时器，把它停掉
+		}
+		//建立新的定时器
+		iVal = setInterval(function(){
+			var playTime = Date.now() - startTime; // 用起始时间和现在时间的差模拟播放
+			CM.time(playTime); // 通报播放时间
+			$('txPlayPos').textContent = playTime; // 显示播放时间
+		}, 100); // 模拟播放器每 100ms 通报播放时间
+	});
+	
+	// 开放 CM 对象到全局这样就可以在 console 终端里操控
+	window.CM = CM;
+});
diff --git a/demo/intro/my-page-styles.css b/demo/intro/my-page-styles.css
@@ -0,0 +1,9 @@
+body {
+	margin:0px;
+	padding:0px;
+	font-family: "Segoe UI", "Microsoft Yahei", sans-serif;
+}
+
+.controlbox {
+	padding:30px;
+}
diff --git a/docs/DoingItRight.md b/docs/DoingItRight.md
@@ -59,3 +59,91 @@ container.style.transform = "scale(" + scale + ")";
 ```
 
 进而通过让用户设置 `options.global.className = 'cmt bold'` 即可开启/关闭粗体等等。
+
+### 实时弹幕支持 Live Comments
+实时弹幕也需要后端服务器的支持，而且比发送弹幕要复杂一些。实时弹幕可以采取Polling（定时读取）或者
+Push Notify（监听等待）两个主动和被动模式实现。实时弹幕还有绝对实时和相对性时间轴更新两个时间模式。
+
+- Polling
+
+    Polling是指设计的弹幕播放器定时访问服务器，询问服务器在某个弹幕池内某段时间后新产生的弹幕，然后把它
+    添加到播放列表或者呈现出来的一种简单的模式。优点是：仅仅基于HTTP，可以在各种服务器（VPS、云、
+    共享主机）和语言（PHP，Python，Ruby，Nodejs）上实现。缺点是：需要反复联网，效率底下，对服务
+    器压力大。
+    
+    推荐用于实时性不强的系统。
+    
+- Push Notify
+
+    Push Notify是指在客户端连接到服务器的一个端口，在有新的弹幕时，服务器主动发送弹幕信息，而客户
+    端在收到信息后被动的呈现或者更新列表。优点：速度快，效率高，处理开销低。缺点：需要用Websockets
+    或者Flash作为桥，要么兼容性略差一点（虽然几乎现代浏览器都支持Websockets 了），要么性能不好。
+    
+    推荐用于非常实时的系统，如不可回看的直播间等。
+
+时间轴模式也不一样
+    
+- 绝对实时
+    每当收到实时弹幕就直接显示，不保存或者少量保存历史弹幕，不能自由的回看。占用内存小。
+
+- 实时时间轴
+    定期更新时间轴，把弹幕按顺序正确插入，保持弹幕时间轴新鲜度，可以自由更改播放时间。
+    
+下面是两个模式的一些参考伪代码：
+
+    // Polling example code
+    
+    var hasLastCheckReturned = true; // 标记之前检测是否已经完成，避免服务器过载
+    var lastCheckedTime = 0; // 上次检测时间
+    setTimeout(function(){
+    	if(!hasLastCheckReturned){
+    		return; // 上次还没返回结果。放弃这次请求。
+    	}
+    	var xhr = new XMLHttpRequest();
+    	xhr.onreadystatechange = function(){
+    		if(xhr.readyState === 4){
+    			if(xhr.responseCode === 200){
+    				// 解析弹幕
+    				var danmakuList = yourFormatParser(xhr.responseText);
+    				for(var i = 0; i < danmakuList.length; i++){
+    					CM.insert(danmakuList[i]); // 把增量弹幕每一个都插入
+    				};
+    				lastCheckedTime = Date.now(); // 更新上次检测的时间
+    				hasLastCheckReturned = true;
+    			} else {
+    				// 可能出了问题
+    				hasLastCheckReturned = true;
+    			}
+    		}
+    	};
+    	xhr.open('GET', 'http://yoururl/somevideoid/?from=' + lastCheckedTime, true); // 告诉服务器上次检查的时间，来获取增量
+    	xhr.send(); // 发送请求
+    	hasLastCheckReturned = false;
+    }, 3000); // 每3s检查新的弹幕
+    
+以及：
+
+    // Push notify example code
+    // 基于 socket.io 和 JQuery来简化代码
+    
+    var socket = io(); //开启流
+    
+    socket.on('danmaku', function(data){
+    	// 当遇到 danmaku 事件，就把推送来的弹幕推送给 CCL
+    	var danmaku = yourFormatParser(data);
+    	CM.insert(danmaku);
+    });
+    
+    $('#send-danmaku-btn').click(function(){
+    	//当按了发送弹幕的按钮
+    	var data = {
+    		"text":"获取信息。。"
+    		...
+    	};// 通过UI获取新弹幕的信息
+    	
+    	//包装并发射弹幕
+    	socket.emit('send-danmaku', JSON.stringify(yourFormatPackager(data));
+    	
+    	//清除 UI 文字部分
+    	$('#send-danmaku-field').value("");
+    });
diff --git a/docs/Intro.md b/docs/Intro.md
@@ -0,0 +1,106 @@
+# Introduction 入门文档
+入门文档设计为面向有较少 Web 或者 JS 开发经验的开发者们。如果你比较熟悉 Web 开发可以直接阅读 CCL
+的设计文档。
+
+# 怎么架设 （Deployment）
+架设并开发 CCL 其实不难，首先你要确保你有一个服务器开发环境，比如在本机上安装的 Apache 或者你能访
+问到的在云端安装的 nginx 等等。请先通过浏览器测试你能正确访问该服务器。如果你在本地开发，请尝试访问
+
+    http://localhost/
+    
+来测试连同性。
+
+**注意：** 请注意确保你在服务器环境下开发 CCL ，在开发时如果遇到各种资源无法载入，请确保您的地址栏
+是以 `http:` 或者 `https:` 开头的而不是 `file:` 等等。
+
+**附加：** 如果你在linux下开发，任何一个静态Web服务器软件都可。Windows下开发的话，仅作为推荐参考
+可以试试 XAMPP。
+
+### 正确的下载类库 （Getting CCL）
+Github 有提供以 Zip 方式下载CCL的选项，但是我们不推荐你这样做。正确使用 CCL 二次开发有两种推荐
+的方法：
+
+- 作为外部库通过 npm 或者 bower 引入： 只需运行 `npm install comment-core-library --save`
+    即可获取最新版的稳定CCL库。通过 `node_modules/comment-core-library/build/`
+    可以引用需要的文件。
+- 直接 Clone 下 Git 代码仓库： 通过 `git clone https://github.com/jabbany/CommentCoreLibrary.git`
+    即可 Clone下 CCL 的全代码库。建议把工作目录放到 Web 开发服务器下的子文件夹内，如 `/var/www/`
+    或者 `D:\webroot\htdocs`下之类的。之后进入 CommentCoreLibrary 文件夹，
+    运行 `npm install grunt-cli -g` 和 `npm install` 
+    （注意：可能需要管理员权限） 即可开始开发
+    
+第一个方式主要用于希望直接挂载 CCL 功能的二次开发，而第二种方式则面向对 CCL 本生的开发有兴趣的人。
+
+### 正确的引用库 （Embedding CCL）
+CCL编译好的代码在 `build/` 目录下。有两个文件非常重要： `CommentCoreLibrary.js` 和 `style.css`。
+这两个分别负责CCL的JS引擎部分和CSS呈现部分，不能省略。相对的还有俩 `.min.js`和 `.min.css` 文件
+是上述文件的压缩版。压缩版代码都在一行，较不方便对行号调试，建议开发时采用未压缩版，架设时则可以采取
+压缩版。
+
+引用方法为，在对应的HTML文件头部添加
+
+    <head>
+        ... 其他头部信息 ...
+        <link rel="stylesheet" href="build/style.css" />
+        <script src="build/CommentCoreLibrary.js"></script>
+        ... 其他头部信息 ...
+    </head>
+    
+注意文件路径调整合理。
+
+之后在相应需要弹幕的位置，放置如下 HTML DOM结构：
+
+    <div id='my-player' class='abp'>
+        <div id='my-comment-stage' class='container'></div>
+    </div>
+    
+其中弹幕结构会在 `container` 这个 div 里插入。采用双层嵌套可以允许你的弹幕 container 于实际容器
+的大小不同，用于实现避开字幕等等功能。
+
+### 调用API函数 （API Calls）
+调用API目前来说比较容易，在建立好页面dom之后，只要绑定 CommentManager 即可。
+
+    var CM = new CommentManager(document.getElementById('my-comment-stage'));
+    CM.init(); // 初始化
+    
+之后 `CM` 实例会提供如下功能：
+
+    // 载入弹幕列表
+    var danmakuList = [
+        {
+            "mode":1,
+            "text":"Hello World",
+            "stime":0,
+            "size":25,
+            "color":0xffffff
+        }
+    ];
+    CM.load(danmakuList);
+    
+    // 插入弹幕
+    var someDanmakuAObj = {
+        "mode":1,
+        "text":"Hello CommentCoreLibrary",
+        "stime":1000,
+        "size":30,
+        "color":0xff0000
+    };
+    CM.insert(someDanmakuAObj);
+    
+    // 启动播放弹幕（在未启动状态下弹幕不会移动）
+    CM.start();
+    
+    // 停止播放（停止弹幕移动）
+    CM.stop();
+    
+    // 更新时间轴时间
+    CM.time(500);
+    CM.time(1000);
+    
+具体使用的参考可以参考 `demo/intro`。内有大部分此示例的代码。
+
+### 发送弹幕 （Sending Comments）
+CCL自己没有发送弹幕的内建支持，不过实现起来非常轻松。具体实现需要根据自己服务器的需求决定。
+
+### 实时弹幕 （Realtime Comments）
+参考[推荐的实现方法](DoingItRight.md)
diff --git a/docs/Readme.md b/docs/Readme.md
@@ -4,14 +4,19 @@ CCL包括一套尽可能完备的文档来帮助二次开发。文档主要针
 怎么用。如果想看看现实里使用了 CCL 的项目，可以参考 [Powered By CCL](PoweredByCCL.md) 里面
 的不完全收录。
 
+## 入门文档（Introduction）
+想开始对 CCL 的开发却还不太了解 CommentCoreLibrary？希望在自己的项目里使用 CCL 却不熟悉接口？
+赶紧来看[入门文档](Intro.md)
+
 ### 部件参考（Individual Parts）
 
 - [CommentManager 弹幕管理器](CommentManager.md)
 - [CommentObject 弹幕对象](CommentObject.md)
 
 ### 使用方法参考（Customization）
 理论上CCL兼容的功能非常之多，但是并不是所有的功能都在库中有实现，有关实现一些效果的较好的做法，请参考
-[DoingItRight 推荐使用方法](DoingItRight.md)
+[DoingItRight 推荐使用方法](DoingItRight.md)。里面介绍了如何优雅的实现大部分现有弹幕站点的一些
+附加功能，包括实时弹幕，弹幕显示格式切换，调整运动速度，全屏同步大小等等。
 
 ## 如何架设（How to Deploy）
 CommentCoreLibrary主要包括两个部分，CommentCore主体和KagerouEngine代码弹幕支持引擎。
@@ -56,30 +61,3 @@ KagerouEngine分为两个部分：JS Host和Worker Client。在编译后，分
 往往是绑定一个发送按钮，根据一些GUI参数确定弹幕参数跟格式，最后用Ajax派发一个POST，在收到POST结果
 后如果成功则显示弹幕到现在的屏幕上，这样的流程。
 
-## 实时弹幕支持（Live Comments）
-实时弹幕也需要后端服务器的支持，而且比发送弹幕要复杂一些。实时弹幕可以采取Polling（定时读取）或者
-Push Notify（监听等待）两个主动和被动模式实现。实时弹幕还有绝对实时和相对性时间轴更新两个时间模式。
-
-- Polling
-    Polling是指设计的弹幕播放器定时访问服务器，询问服务器在某个弹幕池内某段时间后新产生的弹幕，然后把它
-    添加到播放列表或者呈现出来的一种简单的模式。优点是：仅仅基于HTTP，可以在各种服务器（VPS、云、
-    共享主机）和语言（PHP，Python，Ruby，Nodejs）上实现。缺点是：需要反复联网，效率底下，对服务
-    器压力大。
-    
-    推荐用于实时性不强的系统。
-    
-- Push Notify
-    Push Notify是指在客户端连接到服务器的一个端口，在有新的弹幕时，服务器主动发送弹幕信息，而客户
-    端在收到信息后被动的呈现或者更新列表。优点：速度快，效率高，处理开销低。缺点：需要用Websockets
-    或者Flash作为桥，要么兼容性略差一点（虽然几乎现代浏览器都支持Websockets 了），要么性能不好。
-    
-    推荐用于非常实时的系统，如不可回看的直播间等。
-
-时间轴模式也不一样
-    
-- 绝对实时
-    每当收到实时弹幕就直接显示，不保存或者少量保存历史弹幕，不能自由的回看。占用内存小。
-
-- 实时时间轴
-    定期更新时间轴，把弹幕按顺序正确插入，保持弹幕时间轴新鲜度，可以自由更改播放时间。
-
