Maxthon 2 - Plugin Reference
From Maxthon Wiki
Contents |
[edit] Maxthon Plugin Types
Maxthon plugin type is defined by ModuleType (Script, HTML, COM and EXE) and Type (Button, SideBar, Toolbar, COM_Button, MHO, MHO_Button) simultaneously:
Button SideBar Toolbar COM_Button MHO MHO_Button Script yes yes HTML yes EXE yes COM yes yes yes yes yes yes COM_Global yes yes yes yes
ModuleType - Script, HTML, EXE, COM and COM_Global
Script - Script plugin can be button type, which run script when clicked. Script can be written in languages supported by IE, like javascript or vbscript. Maxthon 2.0 supports additional mscript running environment (more details later). Script can also be sidebar type, which shows an HTML file in the sidebar.
HTML - A new plugin type for Maxthon 2.0 only. HTML type plugin is similar to Script Sidebar plugin in nature. The major difference is that Script Sidebar plugin is show in Maxthon's sidebar while HTML plugin is shown as a button in the plugin bar or any toolbar (status bar, menu bar, tab bar, address bar...).
EXE - EXE plugin will be shown as a button in the plugin bar. EXE plugin can be any executable file. Maxthon can pass various parameters to the executable file like the url of the current webpage or the handle of Maxthon browser window.
COM - COM plugin can be written in any programming language supported by MSCOM, like C++, Delphi, Visual Basic, C# etc. COM plugins are created on per tab basis when a tab is created (SideBar/Toolbar/MHO/COM_Button types) or when the plugin button is clicked (Button type), and is destroyed when the tab is closed. A COM plugin can implement the IObjectWithSite interface to obtain the pointer to webbrowser of the tab, the browser events and the Document Object Model for manipulation.
COM_Global - COM_Global plugins are created only once when Maxthon is started, and is destroyed when Maxthon is closed. COM_Global plugins are mostly for browser functions not related to the Document Object Model. Yet COM_Global plugins can implement a PutMaxCommander function through the IDispatch interface to obtain a Maxthon plugin object, which can be used the same way as Maxthon's external object for script plugins (see script plugin commands below), for interaction with the Document Object Model of tabs and Maxthon.
Note that Maxthon 2.0 is multi-thread (a thread for each tab). Plugins designed for extensive interaction with the Document Object Model of tabs should be implemented as COM (per tab) instead of COM_Global so they can work more efficiently within the same thread of individual tab.
Type - Button, SideBar, Toolbar, COM_Button, MHO, and MHO_Button
Button - A button will be added to the plugin bar. The operation specified by script (Script plugin), executable (EXE plugin), dll (COM plugin) will be runned when the button is clicked. Optionally button plugins can implement a dropdown menu for the plugin. A COM button plugin must implement the IOleCommandTarget interface to receive the button click. If a plugin menu is implemented, the IOleCommandTarget_Exec function will receive a command id of 1 when the button is clicked, and a command id of 2 when the first menu command is clicked, and so on. A COM button plugin is created when the button is clicked and is destroyed when the tab is closed (the same as IE7).
SideBar - A button will be added to the sidebar, and an item will be added to the main menu > View > SideBars. When the button or menu item is clicked, Maxthon's sidebar will be opened and show the HTML file specified by the plugin (script plugin), or the window specified by the plugin through the IDeskBand interface (com or com_global plugin).
Toolbar - Toolbar plugins must be written in COM. A new toolbar will be added, which can be shown or hidden from Main Menu > View > Toolbars. A Toolbar plugin must implement the IDeskBand interface to specify the toolbar window. Toolbar plugins can be COM or COM_Global. COM Toolbar plugins are created on per tab basis when a tab is created, and are destroyed when the tab is closed. This enables the adoption of most IE Toolbars in Maxthon with minimal or no change. COM_Global Toolbars are created only once when Maxthon is started, and are destroyed when Maxthon is closed. If a COM_Global Toolbar implements the IObjectWithSite interface, it can obtain the webbrowser pointer of the active tab throught SetSite. When the active tab is changed, SetSite will call again to pass the webbrowser pointer of the new active tab.
COM_Button - COM_Button plugins are similar to Toolbar plugins, except that COM_Button plugins are shown in Maxthon similar to a button, instead of a toolbar. A COM_Button plugin has the flexibility of placement in Maxthon interface like other buttons, but also supports the richer interface of a toolbar than a button.
MHO - MHO plugin is similar to IE's Browser Helper Object and must be written in COM. MHO plugins are created on per tab basis when a tab is created, and are destroyed when a tab is closed. MHO plugins should implement the IObjectWithSite interface to obtain the webbrowser pointer of the tab for interaction with the DOM. MHO plugins do not have interface.
MHO_Button - MHO plugin is a combination of MHO plugin and COM Button plugin. MHO_Button plugins are created on per tab basis when a tab is created, and are destroyed when a tab is closed. In addition, an instance of MHO_Button plugin will be created when its button is clicked, and the instance will be destroyed when the operation is finished. MHO_Button plugin essentially adds a button interface to the MHO plugin.
[edit] Create Maxthon Plugin
Major Components of Maxthon Plugin
A Maxthon normally contains the following files：
INI file – The plugin.ini file necessary for all Maxthon plugins. It defines various attributes of the plugin.
HTML/DLL/EXE file – The most main component necessary for all Maxthon plugins specifying the operation to be done or the content to be displayed.
Icon file – The button ico (*.ICO) necessary for button and sidebar plugins. COM and EXE plugin may use icons in their own resources.
Config.html – An optional HTML file for use with Script and HTML type plugins as the configuration dialog.
plugin.ini file
[General] necessary for definition of various plugin attributes
Name= plugin name
Author= author name
Version= plugin version
ModuleType= can be Script, HTML, EXE, COM, or COM_Global
FileName= can be HTML file (Script and HTML plugins)，DLL file (COM plugins)，or EXE file (EXE plugins)
Comments= the description shown in plugin options dialog and/or button type plugin tooltips
Type= can be M2Plugin_Button, M2Plugin_Sidebar, M2Plugin_Toolbar, M2Plugin_COM_Button, M2Plugin_MHO, or M2Plugin_MHO_Button
IdealSize= the width and height of plugin interface (eg 120 20, for HTML plugin only)
IdealSizeVertical= the width and height of plugin interface when docked vertically (eg 120 20, optional for HTML plugin)
Icon= the button icon for button and sidebar plugins
HotIcon= the button icon when the button plugin is hovered
CLSID= the CSLID for COM and COM_Global plugins
DefaultLocation= optional, set the default location of plugin icon, can be None (in plugin bar but not shown after installation, user can show the button from the add/remove button menu), MenuBar, ToolBar, or StatusBar. If this is not set, the plugin will be shown in the plugin bar. For Button type plugin and Maxthon 2.0.5 or later.
StartAfterPageDoneURL= optional, set the addresses where the plugin should auto start, supports wildcards, and can use "|" to separate addresses, eg *maxthon.com*|forum.maxthon.cn*. If not set, will auto start in all addresses, equivalent to a setting of *. For Script Button type plugin and Maxthon 2.0.5 or later.
StartAfterPageDoneURLExclude= optional, set where the plugin should not auto start, has higher priority than startAfterPageDoneUrl. Use the same format as startAfterPageDoneUrl eg. forum.maxthon.cn/index.php?|*.maxthon.cn/index.php?showtopic*. For Script Button type plugin and Maxthon 2.0.5 or later.
[MyIE2Buttons] optional for definition of drop down menu for Button and MHO_Button plugins
Count= the number of drop down menu items
Name1= the name of the first menu item
FileName1= the file name, or the file name plus the parameter for EXE plugins, of the first menu item. For COM Button and COM MHO_Button plugins, put an arbitrary and distinct name, eg. 1 for FileName1 and 2 for FileName2 etc
Install Maxthon Plugin
Maxthon plugins are installed in the "Plugin" folder inside Maxthon's installation folder. Every plugin has own dedicated plugin folder which contains the plugin.ini file and other necesary files and/or subfolders.
A finished plugin, comprising the plugin folder and all files and/or subfolders inside can be compressed into a ZIP file (*.zip) for released.
Maxthon 2.0
Maxthon 2.0 supports custom M2P plugin installation pack (essentially a *.zip renamed to *.m2p. Plugin will be installed when the M2P file is doubleclicked or dragged into Maxthon's browser window.
Maxthon 1.X
Plugins are installed in Maxthon 1.x according to the following procedures：
1. close Maxthon
2. extract the plugin zip file to the "Plugin" folder inside Maxthon's installation folder. Typically the relevant plugin.ini file will be located C:\Program Files\Maxthon\Plugin\NewPlugin\plugin.ini
3. open Maxthon, the Plugin Installation window will be shown
4. confirm the installation of new plugin
[edit] Maxthon Script Plugin Commands
Maxthon provides various plugin commands to improve the capability of Script plugins. These plugin commands can be run through the window.external object. Some plugin commands requires a Security ID generated by Maxthon to be run.
How to obtain the Security ID
1. Script button plugins can use "%max_security_id" for the Security ID
2. Script sidebar plugins and HTML button plugins have to load "max.src", a script generated by Maxthon. Then "max_security_id" can be used。
<script src=max.src></script>
Reference for Maxthon Plugin Commands
Unless specified otherwise, the following plugin commands are applicable for both Maxthon 2.0 and Maxthon 1.X。
1. max_version - return Maxthon's version number
Example：
alert(external.max_version);
2. max_language_id - return Maxthon's language ID
Example：
alert(external.max_language_id);
Note: Maxthon 2.0 and Maxthon 1.X have different language ID format
3. tab_count - return the number of tabs opened by Maxthon
Example：
alert(external.tab_count);
4. cur_sel - return the index of Maxthon's current tab
Example：
alert(external.cur_sel);
5. m2_plugin_folder( security_id , plugin_name ) - return the folder path of the specified plugin
Example：
alert(external.m2_plugin_folder( %max_security_id , 'ViewSource!'));
6. m2_run_cmd( security_id , command_id ) - run the specified command ID
Example：
external. m2_run_cmd( %max_security_id , 32772 ));
Note: Maxthon 2.0 and Maxthon 1.X have different command ID. Command ID can be found in Maxthon's language file.
7. get_tab( security_id , tab_index ) - return the window object of the specifed tab
Example：
var oWin=external.get_tab(%max_security_id, 0); alert(oWin.document.URL);
8. activate_tab( security_id , tab_index ) - activate the specified tab
Example：
external.activate_tab(%max_security_id, 0);
9. close_tab( security_id , tab_index ) - close the specified tab
Example：
external.close_tab(%max_security_id, 0);
10. readFile( security_id, plugin_name, file_name) - read the content of specified text file
Example：
var sText=external.readFile(%max_security_id, 'ViewPage', 'readme.txt'); alert(sText);
11. writeFile( security_id, plugin_name, file_name, content ) - write content to the specific text file
Example：
external.writeFile(%max_security_id, 'ViewPage', 'test.txt', 'This is the file content');
12. m2_readIni( security_id, plugin_name , file_name , section_name , key , default_value) - read data from specific INI file
Example：
var sDownloadTool=external.m2_readIni(%max_security_id, 'ViewPage', 'plugin.ini', 'Settings', 'Tool', ); alert(sDownloadTool);
13. m2_writeIni( security_id , plugin_name , file_name , section_name , key , value ) - write data to specific INI file
Example：
external.m2_writeIni(%max_security_id, 'ViewPage', 'test.ini', 'Config', 'height', '100px');
14. max_modelessDialog( security_id , url , option , attr , window ) - returns a modeless web page dialog
Example：
var oDialog= external.max_modelessDialog( %max_security_id , 'blank.html', window , , window );
var oDoc=oDialog.document;
oDoc.write('Testing');
oDoc.close();
15. max_activex(security_id ,program_id) - return specified ActiveX object
Example：
var oWSH=external.max_activex(%max_security_id, 'WScript.Shell');
oWSH.run('notepad.exe');
16. m2_search_text(security_id) - return the text in search bar
Example：
alert(m2_search_text(%max_security_id));
17. max_callback(event_name) - a function which is run when certain Maxthon events happen (for HTML button plugins and Script sidebar plugins)
HTML button plugins and Script sidebar plugins can implement the max_callback function for reacting to certain Maxthon browser events like switching to a different tab.
Example：
function max_callback(x){
if(x=='tab_change') alert('Current tab is changed.');
}
By checking the parameter of the max_callback function, plugin can get the following browser events:
HTML button plugins
tab_change – after the current tab is switched
document_Complete - after the current tab is fully loaded
self_destroy - when the html is unloaded, usually when Maxthon exits
Script sidebar plugins
sidebar_tab_change - after the current tab is switched
sidebar_activate - when the sidebar plugin is activated
sidebar_deactivate - when the sidebar plugin is deactivated
sidebar_unload - when the sidebar plugin is unloaded (Maxthon is closed)
18. max_getObj (for Maxthon 2.0 only) - return various Maxthon objects, including:
Info - general information about Maxthon
Adhunter – about Ad Hunter
FavManager – about Favorites
RssManager – about RSS
PluginManager - about Plugins, for Maxthon 2.0.5 or later
Example：
var oInfo=external.max_getObj(%max_security_id, 'info');
Info Object supports the following property and method:
Property:
fileProxy - read-only, returns the path of the current user's proxy configuration document.
Example：
var oInfo=external.max_getObj(%max_security_id, 'info'); alert(oInfo.fileProxy);
folderUser - read-only, returns the path of the profile folder of the current user
Example：
var oInfo=external.max_getObj(%max_security_id, 'info'); alert(oInfo. folderUser);
Method:
getFolderPluginData(plugin_name) - obtain the path of plugin data storage folder for the current user and the plugin
Example：
var oInfo=external.max_getObj(%max_security_id, 'info');
alert(oInfo.getFolderPluginData('ViewSource!'));
AdHunter object support the following method:
Method:
reloadFilter(filter_name) – reload the specified Maxthon filter (currently content filter only) after modifying the relevant filter
Example：
var oAdHunter=external.max_getObj(%max_security_id, 'AdHunter');
oAdHunter.reloadFilter('content');
enableFilter(filter_name, bEnable) – enable or disable Maxthon's 'content' or 'popup' filter
Example：
var oAdHunter=external.max_getObj(%max_security_id, 'AdHunter');
oAdHunter.enableFilter ('content', false);
PluginManager object support the following method:
getPluginFolder - return Maxthon main plugin folder path
Example：
var oPluginManager=external.max_getObj(%max_security_id, 'PluginManager'); alert(oPluginManager.getPluginFolder)
getCount - return the number of all installed plugins, both enabled and disabled
Example：
var oPluginManager=external.max_getObj(%max_security_id, 'PluginManager'); alert(oPluginManager.getCount)
getList - return a list which contains information like name, author etc of all plugins
Example：
var oPluginManager=external.max_getObj(%max_security_id, 'PluginManager'); alert(oPluginManager.getList)
getPlugin(Index) - Index is a number, return the corresponding plugin object
Example：
var oPluginManager=external.max_getObj(%max_security_id, 'PluginManager'); var oPlugin=oPluginManager.getPlugin(0);
The plugin object returned from getPlugin(Index) supports the following property and method:
Property:
title - read only, return plugin name
Example：
alert(oPlugin.title);
folderName - read only, return plugin's folder name
Example：
alert(oPlugin.folderName);
fullPath - read only, return plugin folder's full path
Example：
alert(oPlugin.fullPath);
enable - read/write, return or set if the plugin is enabled
Example：
oPlugin.enable=false; alert(oPlugin.enable); oPlugin.enable=true; alert(oPlugin.enable);
startAfterPageDone - read/write, return or set if the plugin is auto started
Example：
oPlugin.startAfterPageDone = true; alert(oPlugin.startAfterPageDone); oPlugin.startAfterPageDone = false; alert(oPlugin.startAfterPageDone);
startAfterPageDoneUrl - read/write, return or set the address where the plugin will be auto started
Example：
oPlugin.startAfterPageDoneUrl='*maxthon.com*|*maxthon.cn*'; alert(oPlugin.startAfterPageDoneUrl);
Methods:
config() - open plugin configuration dialog (config.html)
Example：
oPlugin.config();
remove() - delete the plugin
Example：
oPlugin.remove();
[edit] Mscript
Maxthon 2.0 supports custom mscript in addition to normal script for script button plugins. Unlike normal script，mscript is not run on webpages and so mscript does not subject to security restrictions imposed on normal script, and does not need to worry about being exploit by webpages. mscript can greatly enhance the functionality of script plugins since mscript can operate with scripting disabled and mscript can access contents in cross domain frames. To use mscript in a Script button plugin, replace the <script...> tag with <mscript...>
Example - the following script button plugin can disable scripting in the current page by changing Maxthon's content control:
<script language="javascript"> external.m2_run_cmd(%max_security_id, 33175); </script>
But after scripting is disabled, the plugin cannot operate. So it cannot re-enable scripting in the current page. On the other hand the following mscript plugin can operate with scripting disabled, so it can renable scripting in the current page.
<mscript language="javascript"> external.m2_run_cmd(0, 33175); </script>
Note an arbitrary number can be used as %max_security_id when mscript is used
[edit] Create Multi-Lingual Ready Plugin
Original Link:[1]
There are various ways to make plugin multi-lingual. Personally I have been using the following method which I find pretty convenient for both plugin author and translator:
For Plugin Authors A
- In the plugin folder create a sub folder "Language" for holding the language files
- Create the default English language file (create a text file and name it "0x0409.ini", "0x0409" is the language id for English)
- Open the file with text editor and add the necessary strings, eg.
[General] 01=Hello! 02=This is testing. ...
Here strings "01", "02", ... etc. are added under the section "General".
For Toolbar Button plugin, add the following function (replace "Test" with name of your plugin) to the plugin script:
function getStr(x){
var sString=external.m2_readIni(%max_security_id, 'Test', 'Language/'+external.max_language_id+'.ini', 'General', x, );
if(!sString) sString=external.m2_readIni(%max_security_id, 'Test', 'Language/0x0409.ini', 'General', x, );
return(sString);
}
For Sidebar plugin, add the following scripts to the head section of the html file:
<script src=max.src></script>
<script>
function getStr(x){
var sString=external.m2_readIni(max_security_id, 'Test', 'Language/'+external.max_language_id+'.ini', 'General', x, );
if(!sString) sString=external.m2_readIni(max_security_id, 'Test', 'Language/0x0409.ini', 'General', x, );
return(sString);
}
</script>
Now the "getStr" function can be used to get strings from the language files. For example "getStr('01')" will try to get the "01" string from the language file which corresponds to Maxthon's language. If the language file is not found, it will get the "01" string from the default English language file.
For Translators
- Get the appropriate language id for your translation here
- Duplicate the English language file and rename it with the relevant language id, eg. 0x0804.ini for Simplified Chinese
- Open the file with text editor and translate the strings which follow "01=", "02=", ...etc
- Save the file in unicode format to avoid encoding problem
- Upload the file to forum or send it to the plugin author
Put the language file in the plugin's "Language" folder. It will work immediately if user select the relevant language.
Translate Plugin.ini
In addition to translating the strings used within the plugin scripts, it is good for translators to translate the plugin.ini as well. In that case, plugin comments and plugin dropdown menu, if any, will also be shown in the relevant language. To translate the plugin.ini:
- Get the appropriate language id for your translation here
- Duplicate the plugin.ini and rename it to eg. plugin0x0804.ini for Simplified Chinese
- Open the file with text editor and translate the string for "Comments", and if there is a "[MyIE2Buttons]" section, also translate "Name1", "Name2", ...
- Save the file in unicode format to avoid encoding problem
- Upload the file to forum or send it to the plugin author
Put the plugin ini file in the plugin's folder. It will work after restart maxthon and reset the plugin bar if user select the relevant lanugage.
Example
The "Test" plugin contains 2 languages, English (default - 0x0409) and Simplified Chinese (简体中文 - 0x0804). Try change the language of maxthon and click the plugin button (restart of maxthon and reset the plugin bar are required for loading plugin ini for new language). Also try add new language file and plugin.ini for your language.
