From a6edb9532fc4a391bbecd160e822a2c19604a05e Mon Sep 17 00:00:00 2001 From: Cosify Date: Sat, 4 Jun 2016 18:50:51 +0800 Subject: [PATCH] add docs --- doc/plugin_building_a_plugin.md | 105 +++++++++++++++++++++ doc/plugin_event_list.md | 159 ++++++++++++++++++++++++++++++++ doc/plugin_getting_started.md | 21 +++++ doc/tutorial.md | 10 +- 4 files changed, 290 insertions(+), 5 deletions(-) create mode 100644 doc/plugin_building_a_plugin.md create mode 100644 doc/plugin_event_list.md create mode 100644 doc/plugin_getting_started.md diff --git a/doc/plugin_building_a_plugin.md b/doc/plugin_building_a_plugin.md new file mode 100644 index 00000000..e325f4f0 --- /dev/null +++ b/doc/plugin_building_a_plugin.md @@ -0,0 +1,105 @@ +Plugin: Building a Plugin +============================== + +3 steps to build a plugin: + +- create an vConsole plugin object +- bind plugin events to this object +- add this object to vConsole + + +## 1. Create plugin object + +Make sure you have imported vConsole, then simply `new` an instance of class `VConsolePlugin`: + +``` +vConsole.VConsolePlugin(id, name) +``` + +`id` (required) is an unique string. +`name` (optional) is a string used for tab's display name. + + + +Example: + +```javascript +var myPlugin = new vConsole.VConsolePlugin('my_plugin', 'My Plugin'); +``` + + +## 2. Bind plugin events + +While installing and running a plugin, vConsole will trigger some events to allow a plugin customizing it's functions. + +use `.on()` to bind an event: + +``` +on(eventName, callback) +``` + +`eventName` (required) is a string. +`callback` (required) is a callback function when an event is triggered. + + + +Example: + +```javascript +myPlugin.on('init', function() { + console.log('My plugin init'); +}); +``` + +See [Event List](./plugin_event_list.md) to learn more about each event. + + + +In this tutorial, we'd like to build a plugin with a tab and a tool button. + +To add a tab, use `renderTab` event: + +```javascript +myPlugin.on('renderTab', function(callback) { + var html = '
Click the tool button below!
'; + callback(html); +}); +``` + +`renderTab` will be triggered while a plugin is being initialized. We simply pass a HTML string to `callback`, then this HTML will be rendered as the content of a new tab, which name is `name`. + +To add a tool button, use `addTool event: + +```javascript +myPlugin.on('addTool', function(callback) { + var button = { + name: 'Reload', + onClick: function(event) { + location.reload(); + } + }; + callback([button]); +}); +``` + +Again, `addTool` will be triggered during initialized, after `renderTab`. It's `callback` receives an array of tool button list. We make a button which can reload the current page. + + +## 3. Add to vConsole + +The final step is add your new plugin to vConsole: + +``` +vConsole.addPlugin(pluginObject) +``` + +`pluginObject` (required) is an `VConsolePlugin` object. + +Example: + +```javascript +vConsole.addPlugin(myPlugin); +``` + +Make sure you have finish binding all necessary events to your plugin before adding to vConsole. Some events (related to initialization) would not be trigger for second time after adding. + diff --git a/doc/plugin_event_list.md b/doc/plugin_event_list.md new file mode 100644 index 00000000..42318036 --- /dev/null +++ b/doc/plugin_event_list.md @@ -0,0 +1,159 @@ +Plugin: Event List +============================== + +All events are optional. But some features (like adding tool buttons) are depended on specific events. + +Each event has a callback function, which will be called when event is triggered. + +## init +Trigger before starting to initialize a plugin. You can configure plugin's properties in this event. This event will only be trigger once. +Note that plugin's DOM is not ready now. + +##### Callback Arguments: +- none + +##### Example: +```javascript +myPlugin.on('init', function() { + // do something to init plugin + this.list = []; // `this` == `myPlugin` +}); +``` + + +## renderTab +Trigger while vConsole trying to create a new tab for a plugin. This event will only be triggered once. +After binding this event, vConsole will get HTML from your callback to render a tab. A new tab will definitely be added if you bind this event, no matter what tab's HTML you set. Do not bind this event if you don't want to add a new tab. + +##### Callback Arguments: +- (required) function(html): a callback function that receives the content HTML of the new tab. `html` can be a HTML `string` or an `DOMElement` object. + +##### Example: + +```javascript +myPlugin.on('renderTab', function(callback) { + var html = '
Hello
'; + callback(html); +}); +``` + + +## addTool +Trigger while vConsole trying to add new tool buttons for a plugin. This event will only be triggered once. + +##### Callback Arguments: + +- (required) function(toolList): a callback function that receives an `array` of tool buttons. + +A tool button is an object with properties: + +Property | | | | +------- | ------- | ------- | ------- +name | string | required | The display name of the button. +global | boolean | optional, default `false` | When `false`, the button will be hidden while switching to other tab. When `true`, the button will be available to all tabs. +onClick | function(event) | required | A callback function when user click the button. + +##### Example: + +```javascript +myPlugin.on('addTool', function(callback) { + var toolList = []; + toolList.push({ + name: 'Reload', + global: false, + onClick: function(e) { + location.reload(); + } + }); + callback(toolList); +}); +``` + + +## ready + +Trigger when all initialization is finished. This event will only be triggered once. +Now plugin is installed and it's DOM is ready. + +##### Callback Arguments: + +- none + +##### Example: + +```javascript +myPlugin.on('ready', function() { + // do something... +}); +``` + + +## show + +Trigger when a tab is shown. Only the plugin binded with `renderTab` will receive this event. + +##### Callback Arguments: + +- none + +##### Example: + +```javascript +myPlugin.on('show', function() { + // do something +}); +``` + + +## Hide + +Trigger when a tab is hidden. Only the plugin binded with `renderTab` will receive this event. + +##### Callback Arguments: + +- none + +##### Example: + +```javascript +myPlugin.on('hide', function() { + // do something +}); +``` + + +## showConsole + +Trigger when vConsole is shown. + +##### Callback Arguments: + +- none + +##### Example: + +```javascript +myPlugin.on('showConsole', function() { + // do something +}); +``` + + +## hideConsole + +Trigger when vConsole is hidden. + +##### Callback Arguments: + +- none + +##### Example: + +```javascript +myPlugin.on('hideConsole', function() { + // do something +}); +``` + + + diff --git a/doc/plugin_getting_started.md b/doc/plugin_getting_started.md new file mode 100644 index 00000000..48446bc8 --- /dev/null +++ b/doc/plugin_getting_started.md @@ -0,0 +1,21 @@ +Plugin: Getting Started +============================== + +A plugin allows you to: + +- add a new tab +- add one or more tool button(s) + +You can customize the functions of the tab and buttons. + + +## Quick Start + +Two lines to create a vConsole plugin: + +```javascript +var myPlugin = new VConsolePlugin('my_plugin', 'My Plugin'); +vConsole.addPlugin(myPlugin); +``` + +The above plugin has no function. See [Building a Plugin](./plugin_building_a_plugin.md) for more details. \ No newline at end of file diff --git a/doc/tutorial.md b/doc/tutorial.md index 3b6b00ff..e736b3f1 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -85,19 +85,19 @@ console.log('UserID:', uid); // UserID: 233 ### Special format -Use `[default|system|...]` string to print logs to specific panel: +Use `[default|system|...]` string to print logs to specific tab: ```javascript // [xxx] must be at the beginning of a log console.log('[system]', 'foo'); console.log('[system] bar'); -// foo & bar will be printed to system panel +// foo & bar will be printed to system tab ``` -Supported panels: +Supported tabs: ``` -[default] Log panel (default) -[system] System panel +[default] Log tab (default) +[system] System tab ```