Maxthon 2 - Plugin Reference

From Maxthon Wiki
Jump to: navigation, search

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.

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

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();

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


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

  1. In the plugin folder create a sub folder "Language" for holding the language files
  2. Create the default English language file (create a text file and name it "0x0409.ini", "0x0409" is the language id for English)
  3. 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

  1. Get the appropriate language id for your translation here
  2. Duplicate the English language file and rename it with the relevant language id, eg. 0x0804.ini for Simplified Chinese
  3. Open the file with text editor and translate the strings which follow "01=", "02=", ...etc
  4. Save the file in unicode format to avoid encoding problem
  5. 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:

  1. Get the appropriate language id for your translation here
  2. Duplicate the plugin.ini and rename it to eg. plugin0x0804.ini for Simplified Chinese
  3. Open the file with text editor and translate the string for "Comments", and if there is a "[MyIE2Buttons]" section, also translate "Name1", "Name2", ...
  4. Save the file in unicode format to avoid encoding problem
  5. 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.