Writing Plugins
KeySnail plugin is a javascript program which works under Chrome privileges. However, consider these points:
- File name extension should be .ks.js.
- Multi-byte characters in a plugin should be enclosed by L() or M().
- Meta info should be described in the variable PLUGIN_INFO.
Detailed infomation for these points will be described later.
KeySnail plugins must have .ks.js as their extensions. This is as same as userscripts of userChrome.js have names like foobar.uc.js.
When plugins are not recognized by KeySnail, check its name is like hogehuga.ks.js.
Character encoding fails at run time if a KeySnail plugin contains code like this:
window.alert("こんにちは！");
In order to assure safe character encoding, enclose multi-byte characters
by L(). The previous code should be written like this:
window.alert(L("こんにちは！"));
Alternatively, using M() not only assure safe character encoding but
gives messages for each locale like for Japanese or for English.
window.alert(M({ja: "こんにちは！",
en: "Hello!"}));
Execute the above code in Japanese environment, “こんにちは！”
appears while “Hello!” appears in English environment.
KeySnail controls plugin based on infomation described in the variable PLUGIN_INFO in the
plugin. Therefore no plugin can be installed unless PLUGIN_INFO is
inside of the plugin because it is not recognized as a “Regular” KeySnail plugin.
Write PLUGIN_INFO when you make a plugin.
PLUGIN_INFO contains information as XML by E4X. See the following example.
var PLUGIN_INFO =
<KeySnailPlugin>
<name>KeySnail Plugin</name>
<name lang="ja">KeySnail プラグイン</name>
<description>Hello KeySnail Plugin!</description>
<description lang="ja">はじめての KeySnail プラグインです</description>
<version>0.1</version>
<updateURL>http://github.com/mooz/keysnail/raw/master/plugins/hello-plugin.ks.js</updateURL>
<iconURL>http://github.com/mooz/keysnail/raw/master/plugins/icon/hello-plugin.icon.png</iconURL>
<author mail="stillpedant@gmail.com" homepage="http://d.hatena.ne.jp/mooz/">mooz</author>
<license>The MIT License</license>
<license lang="ja">MIT ライセンス</license>
<minVersion>1.0</minVersion>
<include>main</include>
<detail><![CDATA[
=== Usage ===
Nothing.
]]></detail>
<detail lang="ja"><![CDATA[
=== 使い方 ===
なし。
]]></detail>
</KeySnailPlugin>;
PLUGIN_INFO is necessary to be enclosed by the KeySnailPlugin tag. The tags are explained here.
- name
- description
- version
- updateURL
- iconURL
- author
- license
- minVersion
- maxVersion
- include
- exclude
- provides
- require
- options
- detail
Write the name of the plugin.
<name>Plugin name</name> <name lang="ja">プラグイン名</name>
name may have this attribute.
| lang | language environment |
Write the description of the plugin.
<description>Plugin description</description> <description lang="ja">プラグインの説明</description>
description may have this attribute.
| lang | language environment |
Write the version of the Plugin. This variable is used in checking updates of the plugin.
<version>1.0</version>
Write the URL for retrieving the plugin. A file indicated by this URL is used in updating.
<updateURL>http://github.com/mooz/keysnail/raw/master/plugins/hello-plugin.ks.js</updateURL>
Write the URL for the icon of the plugin. The icon indicated here is shown by the plugin manager or other functions.
If omitted, the default icon will be used.
<iconURL>http://github.com/mooz/keysnail/raw/master/plugins/icon/hello-plugin.icon.png</iconURL>
Write the author name of the plugin.
<author mail="stillpedant@gmail.com" homepage="http://d.hatena.ne.jp/mooz/">mooz</author>
author may have these attributes.
| mail address of the author | |
| homepage | URL of the author’s web site |
When these attributes are given, links will appear in the plugin manager.
Write the license name.
<license>The MIT License</license> <license lang="ja">MIT ライセンス</license>
license may have this attribute.
| lang | language environment |
Write the minimum version of KeySnail that the plugin supports.
The plugin will be automatically disabled if the version of KeySnail is not in range that the plugin supports.
<minVersion>1.0</minVersion>
Write the maximum version of KeySnail that the plugin supports.
<maxVersion>1.0.*</maxVersion>
You can add (*). E.g., 1.0.* matches from 1.0.0 to 1.0.9. %
Write the Chrome URI of the document in which the plugin is loaded. When you write just “main”, the plugin will be loaded only in the main document of Firefox.
This is as same as indicating chrome://browser/content/browser.xul.
<include>main</include>
Write Chrome URI in which the plugin is NOT loaded.
Write exts (commands) that are provided by the plugin. This is equivalent to M-x (execute-extended-command).
<provides>
<ext>yet-another-twitter-client-keysnail</ext>
</provides>
This value is used in help by the plugin-manager.
To add an ext, use ext.add().
ext.add("command name", command body, "command description");
E.g.,
ext.add("display-hello-message",
function (aEvent, aArg) {
window.alert("Hello!");
},
M({ja: 'Hello メッセージを表示',
en: "Display hello message"}));
Registered exts can be called by ext.select(). And you can bind any key sequence to an ext.
key.setViewKey("h", function (ev, arg) {
ext.exec("display-hello-message", arg);
}, "Display hello message");
Plugins are expected to provide basic features as exts, and enable users to bind any key sequences to features by user’s preferences.
You should avoid to change key binds inside of the plugin by key.setGlobalKey() or other functions as far as possible.
Write external files that are required for the plugin. As external files, you can indicate only scripts so far.
<require>
<script>http://github.com/mooz/keysnail/raw/master/plugins/lib/oauth.js</script>
</require>
The file(s) given here is/are downloaded in installing the plugin.
To load a script inside of the plugin, use userscript.require().
var context = {};
userscript.require("oauth.js", context);
For example, the above code evaluates the content of oauth.js in context.
Write options of the plugin.
<options>
<option>
<name>twitter_client.use_popup_notification</name>
<type>boolean</type>
<description>Whether display pop up notification when statuses are updated or not</description>
<description lang="ja">ステータス更新時にポップアップ通知を行うかどうか</description>
</option>
<option>
<name>twitter_client.main_column_width</name>
<type>[integer]</type>
<description>Each column width of [User name, Message, Info] in percentage</description>
<description lang="ja">[ユーザ名, つぶやき, 情報] 各カラムの幅をパーセンテージ指定</description>
</option>
</options>
Options should be enclosed by option tags. You can describe options by these tags.
| name | option’s name |
| type | option’s type |
| description | option’s description |
The information given here is used in help by the plugin manager.
To access the value of an option inside of the plugin, write like the following:
var optionValue = plugins.options["twitter_client.use_popup_notification"];
The name space of plugins are common to all plugins, so you have to avoid collision by adding suitable prefix or other means.
Write help of the plugin in CDATA section. This part is borrowed from the code of pluginManager.js.
This is an information cited from the help of pluginManager.js.
Header:
- == heading1 == first heading(h1)
- === heading2 === second heading(h2)
- ==== heading3 ==== third heading(h3)
Lists:
- Add "- " at first to make an unordered list (ul).
- Linefeeds
>||
- Lines
separated
||<
the above code will show:
- Lines
separated
Line feeds can be written like the above.
- Nests
- Add "+ " at first to make an ordered list (ol).
You can write like the way of unordered list
Definition lists:
- Lines which end with ":" are a defintion list (dl,dt).
- To start the next line with a nest, the line is a dd element.
- These are also nestable.
Preformatted texts:
Texts enclosed by >|| and ||< are preformatted texts (pre).
You may want to use it for writing codes.
Inlines:
- URL of mailto, http and https scheme will be a link.