Tutorial Plugin : 3 - Commandes de Maxthon

Maxthon now has more than 20 commands. Most commands only work in plugins but some can also be used on normal webpages.

Maxthon a maintenant plu de 20 commandes. La plupart des commandes fonctionne seulement dans les plugins, mais certaines peuvent aussi être utilisées dans des pages Web normales.

You can call these commands through the 'window.external' object. Because it was possible for webpages to use these commands, most commands require a security_id now. A security_id is a variable that looks like this: "{DCFC4598-B97C-49B6-8108-EE86F8694283}". The security_id changes every time you restart your browser.

For script plugins, you need to use %max_security_id in your script file, such as 'var security_id=%max_security_id', then you can use 'security_id' in your script. NOTE: Webpages are able to get this security_id variable if you run a plugin on a webpage and if the webpage knows the variable you use to store the max_security_id in. You can avoid this security issue if you put all your code in an anonymous function. More about anonymous functions in part 4.
For sidebar plugins, a file named "max.src" will be created in your plugin's folder with variable max_security_id as the security_id. You can include this file into your html page to get the id.Like this:
```
<script language="JavaScript" type="text/JavaScript" src="max.src">
</script>
```
This code should be placed inside the <head> element.

These are the Maxthon DHTML commands, don't forget to put 'external.' before them!:

readFile( security_id, plugin_name, file_name) The 'plugin_name' refers to the plugin name defined in plugin.ini and the 'file_name' indicates which file it wants to read (located in the plugin folder). This filename can include a subpath, like 'data/settings.ini' to read the file 'settings.ini' in the 'data' subfolder.The filename can also include '..' to read the parent directory, for example '../../config/plugins.ini' to read the plugins.ini file in the Maxthon/config directory. You can't use '..' more than two times, so you are not able to read/write files outside the Maxthon directory (for more security). The command will return the file contents. If the plugin is not enabled or the 'plugin_name' is wrong or not found, the command will fail and return null. This command can only read ANSI text files.
```
var text = external.readFile(%max_security_id,
"Test plugin","export.txt")
```
writeFile( security_id, plugin_name, file_name, content ) The 'plugin_name' refers to the plugin name defined in plugin.ini and the 'file_name' indicates the file name which will be written. The 'content' is the content that will be written to the file. If the plugin is not enabled or the 'plugin_name' is wrong or not found, the command will fail and return null. This command can only write text files. Also, the command adds an extra NULL character to the end of the file. This doesn't matter much, but it makes it impossible to write XML files. You have to use FileSystemObject (an ActiveX component) for that. Please note: The file will be overwritten from the beginning. To add content to a file, read the data from a file first, then add the new data and then write the data.
```
external.writeFile(%max_security_id,"Test plugin",
"export.txt", "Some Data.")
```
m2_readIni( security_id, plugin_name , file_name , section_name , key , default_value) This command will read the key in the ini-file specified by file_name in the plugin folder. It will return the default_value if the key is not available or if the file_name or plugin_name are wrong.
```
path = external.m2_readIni(%max_security_id,
"testplugin","settings.ini","general","save","0")
```
m2_writeIni( security_id , plugin_name , file_name , section_name , key , value ) This command will write the key with 'value' to the ini file specified by file_name.
```
external.m2_writeIni(%max_security_id,"testplug",
"settings.ini","general","save","1")
```
tab_count This command will return the total number of open tabs, just like 'Number of tabs' in the statusbar.
```
var total_tab = external.tab_count
```
activate_tab( security_id , index ) This command will activate tab number 'index' in Maxthon. ('index' is starting from zero)
```
external.activate_tab(%max_security_id,2)
```
close_tab( security_id , index ) This command will close tab number 'index' in Maxthon. ('index' is starting from zero)
```
external.close_tab(%max_security_id,2)
```
get_tab( security_id , index ) This command will return a web page object of tab number 'index'. ('index' is starting from zero) You can use this if you need to get information about this tab, like the title or URL.
```
var doc = external.get_tab(%max_security_id,2).document
```
cur_sel This command will return the number of the current active tab (starting from zero).
```
var cur_tab = external.cur_sel
```
m2_plugin_folder( security_id , plugin_name ) This command will return the local path of the plugin. You can use this command if you add local images to a webpage or if you add a local stylesheet to a webpage.
```
var folder = external.m2_plugin_folder(%max_security_id,
"ViewSource!")
```
This will return for example: "C:\Program Files\Maxthon\Plugin\ViewSource!\"
m2_run_cmd( security_id , id ) This command will call a Maxthon command with the specified ID. The id of every command can be found in the language file, or here.
```
external.m2_run_cmd(%max_security_id,32772)
```
This will open a blank page.
m2_callerName( security_id, plugin_name) This command tells Maxthon the call is made from a Plugin. It's usually used before a 'window.open()' call to let maxthon bypass the popup filter. The opened window will get the focus if you use this command.
```
external.m2_callerName(%max_security_id,"ViewSource!")
```
max_showConfig( security_id, plugin_name) This command will show the plugin's configuration dialog (check part 2 of this tutorial for more info about the configuration window).
```
external.max_showConfig(%max_security_id,"ViewSource!")
```
max_activex(security_id, prog_id) This command will create the ActiveX control with the prog_id. This ActiveX control has more rights than a normal ActiveX control, you can use it even if you have very high security settings, but it's still possible that virus scanners block the component. You have to open a new window or else you get the alert "This command can only be called from local pages". A new window is a 'local page' for Maxthon.
```
external.m2_callerName(%max_security_id,'PLUGINNAME')
window.open('about:blank','_blank')
var XML=external.get_tab(%max_security_id,
external.cur_sel).external.max_activex( %max_security_id, 
"Microsoft.XMLDOM")
external.get_tab(%max_security_id,external.cur_sel).close()
```
max_modelessDialog( security_id , url , option , attr , window ) This command will open a modelessDialog. It's same as the window.ShowModelessDialog command. The last parameter 'window' is the window object of the web page.
```
 external.max_modelessDialog(%max_security_id,
'example.htm',window, 'status:no;help:no;
 resizable:yes;scroll:yes;',window)
```
max_language_id This property returns the user's current selected Maxthon language code. You can view all the language codes here
```
var language=external.max_language_id
```
max_actSideBarItem( plugin_name ) This command will activate the sidebar plugin named as 'plugin_name'.
```
external.max_actSideBarItem("Calculator++&quot)
```
addFavorite( url , title ) , addFavorite( url ) This command will ask the user to add the 'url' into favorites, using 'title' for the name of the url (not required).
```
external.addFavorite( "http://www.google.com" )
external.addFavorite( "http://www.google.com","This 
is google")
```
addProxy (name, address, speed, is_web_proxy) This command will call Maxthon's 'add proxy' dialog to add the proxy named as 'name' at address 'address', giving the initial speed 'speed'. The is_web_proxy indicates whether the proxy is a web proxy or a normal proxy.
```
external.addProxy("My proxy","192.168.1.0:8080",1,0)
```
addFilter( address ) , addFilter( address, is_pop_filter ) This command will call Maxthon's 'add filter' dialog, setting the address to be filtered as 'address'. 'is_pop_filter' indicates whether the default filter type is 'pop filter'.
```
external.addFilter("http://www.yahoo.com/ad*")
external.addFilter("http://www.yahoo.com/img/*", 0)
```

m2_addSearchEngine(name, address) This property will call Maxthon's 'add search engine' dialog.

javascript:external.m2_addSearchEngine('SteadySearch',
'http://www.steadysearch.com/search?p=Q&ts=ne&w=%us');

m2_search_text( security_id ) This property will return the text in Maxthon's search bar.
```
var text = external.m2_search_text(%max_security_id)
```

In a sidebar plugin you can implement a script function called max_callback(status).

When the plugin is created the URL will be filename?maxcmd=init
When the plugin is activated, max_callback('sidebar_activate') will be called
When the plugin is deactivated, max_callback('sidebar_deactivate') will be called
When the active tab is changed, max_callback('sidebar_tab_change') will be called
When the plugin is unload, max_callback('sidebar_unload') will be called.

< Partie 2 : Fichiers Plugin | Sommaire Plugin | Partie 4 : Astuces >