Merge pull request Tencent#44 from Maizify/dev

v2.1.0

CHANGELOG.md

@@ -1,5 +1,12 @@
 English | [简体中文](./CHANGELOG_CN.md)
 
+#### V2.1.0 (2016-06-29)
+
+- [FEATURE] Add `vConsole.tool` & `vConsole.$` helper functions, see [Helper Functions](./doc/helper_functions.md).
+- [FEATURE] Public properties & methods of vConsole are available, see [Public Properties & Methods](./doc/public_properties_methods.md).
+- [FIX] Fix issue that `error` in `window.onerror()` may be undefined.
+- [FIX] Fix error that `xhr.status` may be unavailable when `xhr.readyState < 4`.
+
 
 #### v2.0.1 (2016-06-16)
 

CHANGELOG_CN.md

@@ -1,5 +1,12 @@
 [English](./CHANGELOG.md) | 简体中文
 
+#### v2.1.0 (2016-06-29)
+
+- 【特性】新增 `vConsole.tool` 及 `vConsole.$` 辅助函数，请查阅[辅助函数](./doc/helper_functions_CN.md)。
+- 【特性】公开部分 vConsole 的属性及方法，请查阅[公共属性及方法](./doc/public_properties_methods_CN.md)。
+- 【修复】修复 `window.onerror()` 中 `error` 可能为空而导致堆栈读取错误的问题。
+- 【修复】修复当 `xhr.readyState < 4` 时读取 `xhr.status` 可能导致错误的问题。
+
 
 #### v2.0.1 (2016-06-16)
 

README.md

@@ -49,7 +49,14 @@ See [Tutorial](./doc/tutorial.md) for more details.
 
 ## Documentation
 
+vConsole:
+
  - [Tutorial](./doc/tutorial.md)
+ - [Public Properties & Methods](./doc/public_properties_methods.md)
+ - [Helper Functions](./doc/helper_functions.md)
+
+Plugin:
+
  - [Plugin: Getting Started](./doc/plugin_getting_started.md)
  - [Plugin: Building a Plugin](./doc/plugin_building_a_plugin.md)
  - [Plugin: Event List](./doc/plugin_event_list.md)

README_CN.md

@@ -50,7 +50,15 @@ console.log('Hello world');
 
 ## 文档
 
+
+vConsole 本体：
+
  - [使用教程](./doc/tutorial_CN.md)
+ - [公共属性及方法](./doc/public_properties_methods_CN.md)
+ - [辅助函数](./doc/helper_functions_CN.md)
+
+插件：
+
  - [插件：入门](./doc/plugin_getting_started_CN.md)
  - [插件：编写插件](./doc/plugin_building_a_plugin_CN.md)
  - [插件：Event 事件列表](./doc/plugin_event_list_CN.md)

doc/a_doc_index.md

@@ -7,6 +7,8 @@ Documentation Index
 ## vConsole
 
  - [Tutorial](./tutorial.md)
+ - [Public Properties & Methods](./public_properties_methods.md)
+ - [Helper Functions](./helper_functions.md)
 
 
 ## Plugin

doc/a_doc_index_CN.md

@@ -7,6 +7,8 @@
 ## vConsole 本体
 
  - [使用教程](./tutorial_CN.md)
+ - [公共属性及方法](./public_properties_methods_CN.md)
+ - [辅助函数](./helper_functions_CN.md)
 
 
 ## Plugin 插件

doc/helper_functions.md

@@ -0,0 +1,304 @@
+Helper Functions
+==============================
+
+vConsole provides some useful helper functions for efficient plugin development.
+
+Helper functions are mounted in different vConsole properties according to their usage:
+
+- `vConsole.tool`: Helper functions.
+- `vConsole.$`: DOM-related functions.
+
+
+## vConsole.tool
+
+### vConsole.tool.isString(value)
+### vConsole.tool.isArray(value)
+### vConsole.tool.isBoolean(value)
+### vConsole.tool.isElement(value)
+### vConsole.tool.isFunction(value)
+### vConsole.tool.isNull(value)
+### vConsole.tool.isNumber(value)
+### vConsole.tool.isObject(value)
+### vConsole.tool.isSymbol(value)
+### vConsole.tool.isUndefined(value)
+
+Check whether a value is a certain type.
+
+##### Return:
+- Boolean
+
+
+
+### vConsole.tool.htmlEncode(text)
+
+Encode a text into a HTML non-sensitive string.
+
+##### Parameters:
+- (required) text: A string to be encoded.
+
+##### Return:
+- String
+
+
+
+### vConsole.tool.setStorage(key, value)
+
+Set data to `localStorage`. A prefix `vConsole_` will be added to `key` automatically.
+
+Note that some devices may not have `localStorage` and then `value` would not be saved under this situation, so DO NOT use this method to save permanent data.
+
+##### Parameters:
+- (required) key: A string, the name of data.
+- (required) value: A string, the value of data.
+
+##### Return:
+- None
+
+##### Example:
+
+```javascript
+vConsole.tool.setStorage('count', 1);
+```
+
+
+
+### vConsole.tool.getStorage(key)
+
+Get data from `localStorage`. A prefix `vConsole_` will be added to `key` automatically.
+
+##### Parameters:
+- (required) key: A string, the name of data.
+
+##### Return:
+- String, the value of data.
+
+##### Example:
+
+```javascript
+var num = vConsole.tool.setStorage('count'); // => 1
+```
+
+
+
+## vConsole.$
+
+### vConsole.$.one(selectors, baseElement)
+
+Returns the first element within the document or baseElement that matches the specified group of selectors.
+
+##### Parameters:
+- (required) selectors: A string containing one or more CSS selectors separated by commas.
+- (optional) baseElement: An element object, default to be `document`.
+
+##### Return:
+- Element object
+
+##### Example:
+
+```javascript
+var $page = vConsole.$.one('#my_page');
+var $item = vConsole.$.one('.item', $page);
+```
+
+
+### vConsole.$.all(selectors, baseElement)
+
+Returns a list of elements within the document or baseElement that matches the specified group of selectors.
+
+##### Parameters:
+- (required) selectors: A string containing one or more CSS selectors separated by commas.
+- (optional) baseElement: An element object, default to be `document`.
+
+##### Return:
+- Element object
+
+##### Example:
+
+```javascript
+var $page = vConsole.$.one('#my_page');
+var $items = vConsole.$.all('.item', $page);
+```
+
+
+### vConsole.$.addClass(elements, className)
+
+Add the specified class(es) to element(s).
+
+##### Parameters:
+- (required) elements: A single or a list of element object(s).
+- (required) className: A string of one or more space-separated classes.
+
+##### Return:
+- None
+
+##### Example:
+
+```javascript
+var $items = vConsole.$.all('.item');
+vConsole.$.addClass($items, 'selected');
+```
+
+
+### vConsole.$.removeClass(elements, className)
+
+Remove the specified class(es) of element(s).
+
+##### Parameters:
+- (required) elements: A single or a list of element object(s).
+- (required) className: A string of one or more space-separated classes.
+
+##### Return:
+- None
+
+##### Example:
+
+```javascript
+var $items = vConsole.$.all('.item');
+vConsole.$.removeClass($items, 'selected');
+```
+
+
+### vConsole.$.hasClass(element, className)
+
+Check whether an element is assigned the given class.
+
+##### Parameters:
+- (required) element: An element object.
+- (required) className: A string.
+
+##### Return:
+- Boolean
+
+##### Example:
+
+```javascript
+var $page = vConsole.$.one('#my_page');
+if (vConsole.$.hasClass($page, 'actived')) {
+	// do something
+}
+```
+
+
+### vConsole.$.bind(elements, eventType, fn, useCapture)
+
+Bind an event to element(s).
+
+##### Parameters:
+- (required) elements: A single or a list of element object(s).
+- (required) eventType: A string of event's type.
+- (required) fn: A function to execute when the event is triggered.
+- (optional) useCapture: A boolean that indicates the event uses capturing or bubbling, default to be `false`.
+
+##### Return:
+- None
+
+##### Example:
+
+```javascript
+var $btn = vConsole.$.one('#submit');
+vConsole.$.bind($btn, 'click', function(event) {
+	event.preventDefault();
+	alert('submit!');
+});
+```
+
+
+### vConsole.$.delegate(element, eventType, selectors, fn)
+
+Bind an event to an element, and only this element's descendants which match the selectors can trigger the event.
+
+##### Parameters:
+- (required) element: An element object.
+- (required) eventType: A string of event's type.
+- (required) selectors: A string containing one or more CSS selectors separated by commas.
+- (required) fn: A function to execute when the event is triggered.
+
+##### Return:
+- None
+
+##### Example:
+
+```javascript
+var $page = vConsole.$.one('#my_page');
+vConsole.$.delegate($page, 'click', '.item', function(event) {
+	vConsole.$.addClass(this, 'selected'); // this => '.item'
+});
+```
+
+
+### vConsole.$.render(tpl, data, toString)
+
+Compile a template into an element object or a HTML string with given data.
+
+##### Parameters:
+- (required) tpl: A template string.
+- (required) data: A key-value data which is used to render the template.
+- (optional) toString: A boolean that indicates whether returns an element object or a HTML string, default to be `false`.
+
+##### Return:
+- Element object or HTML string
+
+##### Syntax:
+
+If:
+```html
+{{if}}
+	...
+{{else}}
+	...
+{{/if}}
+```
+
+For:
+```html
+{{for (var i=0; i<10; i++)}}
+	...
+	{{continue}}
+	{{break}}
+{{/for}}
+```
+
+Switch:
+```html
+{{switch (flag)}}
+	{{case 1}}
+		...
+		{{break}}
+	{{default}}
+		...
+{{/switch}}
+```
+
+Print:
+```html
+{{flag}}
+```
+
+###### Example:
+
+```javascript
+var tpl = '<ul>' +
+	'{{for (var i = 0; i < list.length; i++)}}' +
+		'<li>' + '{{list[i]}}' + '</li>' +
+	'{{/for}}' +
+'</ul>';
+var data = {
+	list: ['Red', 'Blue', 'Yellow']	
+};
+
+var html = vConsole.&.render(tpl, data, true);
+document.body.innerHTML += html;
+```
+
+Output:
+
+```html
+<ul>
+<li>Red</li>
+<li>Blue</li>
+<li>Yellow</li>
+</ul>
+```
+
+
+[Back to Index](./a_doc_index.md)